<p>Stemmaweb is a set of tools that has grown out of the <a href="http://treeoftexts.arts.kuleuven.be/">Tree of Texts</a>, a CREA ("creative research") project funded by the KU Leuven. The tools were developed variously within the project, on behalf of the project by <a href="http://www.scsys.co.uk">Shadowcat Systems</a>, and in collaboration with the <a href="http://interedition.eu/">Interedition</a> project. The source code for all tools and associated libraries is available <a href="http://github.com/tla/stemmatology/">on Github</a>.</p>
- <p>All tools are free for scholarly (nonprofit) use and adaptation. Although some data may be viewed publicly without a user account, use of the tools with your own data is possible only by registering as a user. You may log in with a Google account or another OpenID account, or you may <a onclick="window.open('[% c.uri_for( '/register' ) %]', 'regwindow', 'height=385,width=445')">register</a> with a local username and password for use on the site. The Tree of Texts project and KU Leuven retain rights to uploaded text traditions only insofar as it is necessary to store and back them up, display them according to the stated preferences, and analyze them with the tools provided and linked.</p>
+ <p>All tools are free for scholarly and nonprofit use and adaptation. Although some data may be viewed publicly without a user account, use of the tools with your own data is possible only by registering as a user. You may log in with a Google account or another OpenID account, or you may <a onclick="window.open('[% c.uri_for( '/register' ) %]', 'regwindow', 'height=385,width=445')">register</a> with a local username and password for use on the site. The Tree of Texts project and KU Leuven retain rights to uploaded text traditions only insofar as it is necessary to store and back them up, display them according to the stated preferences, and analyze them with the tools provided and linked.</p>
<h2>Tools available</h2>
<p>At present the Stemmaweb tools comprise the following:</p>
- <h3>Uploader</h3>
+ <h3>Uploader ("Add a new text tradition")</h3>
<p>Any logged-in user may upload a text collation in one of several forms:</p>
<ul>
<li>Spreadsheet collation (Excel file, CSV file, or tab-separated values). Witness sigla should appear in the first row, one per column; the text of each witness should occur in sequence in the appropriate column, with collated words/readings lined up according to row. CSV and tab-separated value files are assumed to be Unicode, in the UTF-8 encoding.</li>
</ul>
<p>Once a tradition is successfully uploaded, you may change its name and its language, and choose whether others may view (but not edit) it.</p>
- <h3>Stemma editor</h3>
+ <h3>Stemma editor ("Add a new stemma / Edit this stemma")</h3>
<p>For any text tradition you own, you may associate one or more stemma hypotheses to the tradition. Currently the way to specify a stemma is in "dot" format, as documented within the interface for the "Add/edit stemma" buttons.</p>
+
+ <h3>Stemma generation via <a href="https://github.com/Stemweb/Stemweb">Stemweb</a> ("Run a Stemweb algorithm")</h3>
+ <p>Given an uploaded collation, it is possible to generate a stemma hypothesis using one of several algorithms. This feature, Stemweb, is a service provided by researchers at the HIIT (Helsinki Institute for Information Technology). The algorithms currently available include:
+ <!-- TODO generate this list from the docs API! -->
+ <ul>
+ <li><a href="http://cosco.hiit.fi/Articles/icdm2011.pdf">Semstem</a>: latent tree structure analysis</li>
+ <li><a href="http://cosco.hiit.fi/Articles/ecai06.pdf">RHM</a>: compression-based analysis</li>
+ <li><a href="http://en.wikipedia.org/wiki/Neighbor-net">Neighbor-Net</a>: based on neighbor-joining, recommended for highly 'contaminated' traditions</li>
+ </ul>
+ Both the Semstem and RHM algorithms require a single parameter, "iterations", to specify the number of times the analysis should be run to arrive at a consensus model. A higher number produces a more certain result, but requires a longer time to run. Suggested minimums are 50 iterations for Semstem and 1000000 iterations for RHM.</p>
+ <p>All of these algorithms run "asynchronously" - when the owner of a tradition makes a request for a generated tree, the result can take some minutes (or even hours, depending on the complexity of the tradition) to return. When a request has been made, the owner can check its progress using the same button; if the stemma has meanwhile been calculated, it will be loaded. If the owner leaves the Stemmaweb site and the stemma is calculated meanwhile, it will appear when Stemmaweb is next used.<p>
+ <p>Generated stemmas are not oriented - they have no inferred root or origin. This means that, in order to examine the texual variants against a generated stemma (see "Stexaminer" below), a root must first be chosen. This can be done simply by clicking a node in the returned graph, and choosing the option to use that node as the root. Any stemma may be re-rooted any number of times.</p>
- <h3>Relationship mapper</h3>
- <p>The relationship mapper tool allows you to define the relationships between variant readings within your text. This is useful for, among other things, later stemma analysis - it allows classification of the sorts of variants that may or may not yield clues as to the history of the text. Please see the "Help/about" link at the top of the relationship mapper for more information about its use.</p>
-
- <h3>Stexaminer</h3>
+ <h3>Stexaminer ("Examine variants against this stemma")</h3>
<p>This tool allows visualization of the variants within a text tradition, according to the selected stemma hypothesis. The stemma graph and the variant witness groupings are sent to a calculation service, provided by the <a href="http://dtai.cs.kuleuven.be">Declarative Language and Artificial Intelligence</a> research group of the KU Leuven, that attempts to determine for each variant location within the text:</p>
<ul>
<li>Whether that location fits the stemma in a genealogical way</li>
</ul>
<p>For more information on this tool and the analysis behind it, please see <a href="http://cocomile.disi.unitn.it/2012/papers/cocomile2012_manuscript.pdf">the following paper</a>.</p>
+ <h3>Relationship mapper ("View collation and relationships")</h3>
+ <p>The relationship mapper tool allows you to define the relationships between variant readings within your text. This is useful for, among other things, later stemma analysis - it allows classification of the sorts of variants that may or may not yield clues as to the history of the text. Please see the "Help/about" link at the top of the relationship mapper for more information about its use.</p>
+
<h2>License</h2>
<p>All source code for the Stemmaweb tools and user interface is open-source. The Perl libraries are governed by the Perl license; the remaining software is governed by the GNU General Public License.</p>
<p>Rights to all textual data uploaded to the Stemmaweb system are retained by its original owner. By uploading the data you assert that you have the right to use it, and you grant us rights to it insofar as it is necessary for us to store, backup, and display the data.</p>
<h3>Making relationships between words</h3>
- <p>The tool itself is an interface for allowing these relationships to be declared. The collation is presented as a variant graph running from left to right. In a variant graph, each node is a reading, and each witness takes a single path through the readings from beginning to end. When readings appear vertically aligned with each other, it is an indication that they are variant readings, occurring at the same point in the text.
+ <p>The tool itself is an interface for allowing these relationships to be declared. The collation is presented as a variant graph running from left to right. In a variant graph, each node is a reading, and each witness takes a single path through the readings from beginning to end. When readings appear vertically aligned with each other, it is an indication that they are variant readings, occurring at the same point in the text. In the example given here, the variants include "ecclesia/que", "beata/sancta/beatam", "uirgine/uirginem", and "tres/duas". </p>
+ <img src="[% c.uri_for( '/images/00_variantgraph.png' ) %]">
<p>In 'select' mode, when the nodes are green, you can navigate through the graph. Scrolling up or down will zoom in and out, respectively; dragging the graph will pan it in that direction. Use this navigation to hone in on the part of the graph to be worked with.</p>
- <p> When you are ready to draw relationships, click the 'pencil' icon to enter edit mode. When you select a node (by clicking on it) you can drag it onto another node to indicate that a relationship exists between them. Fill in the details of the relationship as follows:</p>
-<p><em>Type</em> can be one of:</p>
-<ul>
- <li>Orthographic - these are interchangeable representations of the same reading</li>
- <li>Spelling - these are variant spellings of the same reading</li>
- <li>Grammatical - these readings are word forms with the same lemma</li>
- <li>Lexical - these readings fulfill corresponding functions in the text. Use the "Annotation" field to elaborate.</li>
- <li>Meaning - these readings have corresponding meanings (e.g. synonyms, antonyms). Use the "Annotation" field to elaborate.</li>
- <li>Transposition - this pair actually represents the same reading, but its location varies between witnesses.
-</ul>
+ <p> When you are ready to draw relationships, click the 'pencil' icon to the top right of the screen to enter edit mode. When you select a node (by clicking on it) you can drag it onto another node to indicate that a relationship exists between them. </p>
+ <img src="[% c.uri_for( '/images/01_makerelation.png' ) %]">
+
+ <p>Fill in the details of the relationship as indicated in the dialog:</p>
+ <img src="[% c.uri_for( '/images/02_relationdialog.png' ) %]">
+
+<p><em>Type</em> can be any one of the types that appears in the key to the right of the screen.</p>
<p><em>Scope</em> can be one of:</p>
<ul>
<li>Local - the relationship applies only at this point in the text</li>
- <li>Global - the relationship applies throughout the text</li>
+ <li>Document - the relationship applies throughout the text</li>
+ <li>Global - the relationship applies throughout all texts of this language</li>
</ul>
+ <p><em>NOTE:</em> at the moment, "global" scope is treated as "document" scope, i.e. only applies throughout the individual text.</p>
+
+ <p>The relationships are displayed as colored paths between readings. While in 'edit' mode, clicking on a relationship path will display the information associated with it, and give the user an option to delete it. Deletion of a 'global' relationship will remove that relationship throughout the graph.</p>
+ <img src="[% c.uri_for( '/images/03_infodelete.png' ) %]">
+
+ <p>When you are ready to move elsewhere in the graph, click the 'hand' icon to return to select mode.<p>
- <p>The relationships are displayed as colored paths between readings. While in 'edit' mode, clicking on a relationship path will display the information associated with it, and give the user an option to delete it. Deletion of a 'global' relationship will remove that relationship throughout the graph. When you are ready to move elsewhere in the graph, click the 'hand' icon to return to select mode.<p>
<h3>Correcting the collation</h3>
- <p>Occasionally, the collation as uploaded will contain errors, or need for some other reason to be modified. Within the relationship mapper, you can detach a sequence of readings and re-attach it elsewhere as a form of manual collation.</p>
+ <p>Occasionally, the collation as uploaded will contain errors, or need for some other reason to be modified. For example, in the following snippet, the witness Ba96 has a string of words "cetera. Secundo uere asserendo" that have been separated from their analogues in other witnesses through an erroneous collation of the "et" in Ba96 with a later "et" in the majority of witnesses.</p>
+ <img src="[% c.uri_for( '/images/00_bad_collation.png' ) %]">
- <p>To detach one or more readings, drag with the mouse to select an area of the graph that includes all the affected readings. A dialog will pop up to ask which witnesses should be detached from the collation at that point. To attach a reading elsewhere, select it and drag it to the corresponding reading elsewhere in the graph, just as though you were making a relationship. There should be an option to specify that the readings are identical; select it.</p>
+ <p>Within the relationship mapper, you can detach a sequence of readings and re-attach it elsewhere as a form of manual collation. To detach one or more readings, drag with the mouse to select an area of the graph that includes all the affected readings.</p>
+ <img src="[% c.uri_for( '/images/01_select_decollate.png' ) %]">
+
+ <p>A dialog will pop up to ask which witnesses should be detached from the collation at that point. At least one witness must be selected; at least one witness must also remain unselected. In the case of our example, we wish to detach the reading for Ba96.</p>
+ <img src="[% c.uri_for( '/images/02_witness_select.png' ) %]">
- <p>At the moment, editing the graph in this manner can quickly lead to a rather untidy and confusing-looking graph. If at any point it becomes too difficult to follow, please re-load the relationship mapper.</p>
+ <p>The result will be one or more new readings in the graph, identical to the selected ones, with the affected witnesses using the new reading instead of the old one.</p>
+ <img src="[% c.uri_for( '/images/03_detached.png' ) %]">
+
+ <p>To attach the separated reading elsewhere, select it and drag it to the corresponding reading elsewhere in the graph, just as though you were making a relationship.</p>
+ <img src="[% c.uri_for( '/images/04_rejoin_correct.png' ) %]">
+
+ <p>There should be an option "Merge readings" to specify that the readings are identical; select it.</p>
+ <img src="[% c.uri_for( '/images/05_select_merge.png' ) %]">
+
+ <p>When two identical readings are merged, the relationship mapper will display a set of suggestions for other readings that might also need to be merged, in light of the change that was just made. Selecting the green button will accept the suggestion; selecting the red button will reject it. If a reading is erroneously merged, it may be detached again in the same manner described above.</p>
+ <img src="[% c.uri_for( '/images/06_merged_farther.png' ) %]">
+
+ <p>At the moment, editing the graph in this manner can quickly lead to a rather untidy and confusing-looking graph:</p>
+ <img src="[% c.uri_for( '/images/07_merged_mess.png' ) %]">
+ <p>If at any point it becomes too difficult to follow, please re-load the relationship mapper. The corrected graph will appear in its clean format.</p>
+ <img src="[% c.uri_for( '/images/08_merged_reloaded.png' ) %]">
+
+ <!--
[% IF language != 'NONE' %]
<h3>Adding [% language %] morphological information to readings</h3>
<p>If initial lemmatization has been performed on the text, a number of readings may appear in yellow rather than green; this means that there are multiple possible morphologies for the reading in question. Double click on the reading to select and save the correct morphology.</p>
[% END -%]
+ -->
+
[% PROCESS footer.tt %]
\ No newline at end of file
projects / scpubgit/stemmaweb.git / commitdiff
