/ 
Text-Tradition-Analysis-2.0.4
River stage zero No dependents
/ Text::Tradition::Stemma

NAME

Text::Tradition::Stemma - a representation of a stemma codicum for a Text::Tradition

SYNOPSIS

use Text::Tradition;
my $t = Text::Tradition->new( 
  'name' => 'this is a text',
  'input' => 'TEI',
  'file' => '/path/to/tei_parallel_seg_file.xml' );

my $s = $tradition->add_stemma( dotfile => '/path/to/stemma.dot' );

DESCRIPTION

Text::Tradition is a library for representation and analysis of collated texts, particularly medieval ones. The Stemma is a representation of the copying relationships between the witnesses in a Tradition, modelled with a connected rooted directed acyclic graph (CRDAG).

DOT SYNTAX

The easiest way to define a stemma is to use a special form of the 'dot' syntax of GraphViz.

Each stemma opens with the line

digraph "Name of Stemma" {

and continues with a list of all manuscript witnesses in the stemma, whether extant witnesses or missing archetypes or hyparchetypes. Each of these is listed by its sigil on its own line, e.g.:

alpha [ class=hypothetical ]
1 [ class=hypothetical,label=* ]
Ms4 [ class=extant ]

Extant witnesses are listed with class=extant; missing or postulated witnesses are listed with class=hypothetical. Anonymous hyparchetypes must be given a unique name or number, but can be represented as anonymous with the addition of 'label=*' to their lines. Greek letters or other special characters may be used as names, but they must always be wrapped in double quotes.

Links between manuscripts are then listed with arrow notation, as below. These lines show the direction of copying, one step at a time, for the entire stemma.

alpha -> 1
1 -> Ms4

The final line in the definition should be the closing brace:

}

Thus for a set of extant manuscripts A, B, and C, where A and B were copied from the archetype O and C was copied from B, the definition would be:

digraph "Test stemma 1" {
    O [ class=hypothetical]
    A [ class=extant ]
    B [ class=extant ]
    C [ class=extant ]
    O -> A
    O -> B
    B -> C
}

CONSTRUCTOR

new

The constructor. This should generally be called from Text::Tradition, but if called directly it takes the following options:

  • dot - A filehandle open to a DOT representation of the stemma graph.

  • graph - If no DOT specification is given, you can pass a Graph object instead. The vertices of the graph should have an attribute 'class' set to either of the values 'extant' or 'hypothetical'.

  • is_undirected - If the graph specification (or graph object) is for an undirected graph (e.g. a phylogenetic tree), this should be set.

new_from_newick( $newick_string )

A constructor that will read a Newick-format tree specification and return one or more undirected Stemma objects. TODO test

rename_witnesses( \%namehash, $all_extant )

Take a hash of old -> new sigil mappings, and change the names of the witnesses.

METHODS

as_dot( \%options )

Returns a normal dot representation of the stemma layout, suitable for rendering with GraphViz. Options include:

  • graph - A hashref of global graph options.

  • node - A hashref of global node options.

  • edge - A hashref of global edge options.

See the GraphViz documentation for the list of available options.

alter_graph( $dotstring )

Alters the graph of this stemma according to the definition specified in $dotstring.

editable( $opts )

Returns a version of the graph rendered in our definition format. The output separates statements with a newline; set $opts->{'linesep'} to the empty string or to a space if the result is to be sent via JSON.

If a situational version of the stemma is required, the arguments for situation_graph should be passed via $opts->{'extant'} and $opts->{'layerwits'}.

situation_graph( $extant, $layered )

Returns a graph which is the original stemma graph with all witnesses not in the %$extant hash marked as hypothetical, and witness layers added to the graph according to the list in @$layered. A layered (a.c.) witness is added as a parent of its main version, and additionally shares all other parents and children with that version.

as_svg

Returns an SVG representation of the graph, calling as_dot first.

witnesses

Returns a list of the extant witnesses represented in the stemma.

hypotheticals

Returns a list of the hypothetical witnesses represented in the stemma.

root_graph( $root_vertex )

If the stemma graph is undirected, make it directed with $root_vertex at the root. If it is directed, re-root it.

LICENSE

This package is free software and is provided "as is" without express or implied warranty. You can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Tara L Andrews <aurum@cpan.org>