Screen Reference Index
Plato Documentation  version 0.9, 2014.02.14
 Documentation Index    Markup: Cross Reference Maps
Introduction to Plato
The Basics
Plato's Display
Building Object Classes
Creating and Using Objects
Importing Objects
Creating and Managing Cross References
Creating and Managing Databases
Creating and Managing Class Libraries
Creating and Managing Markup
Markup: Document Creation
Markup: Data Import
Markup: Autoenumeration
Markup: Cross Reference Maps
Markup: Database Export
Markup: Class Library Export
Creating and Managing Scripts
External Integration
Cross References
Multi-dimensional Categories
Setting Up
Configuration: System
Configuration: Database
Configuration: Folders
Screen Reference
Properties Reference
Cross Reference Map
Cross reference maps are sets of markup that produce maps (sometimes called 'networks') of cross references. These maps are usually text files that are designed to be read and displayed by specialized graphics applications such as GraphViz, Gephi, Pajek, the Network Workbench, and others.

Map files typically contain a collection of nodes and edges. Very simply put, nodes are "things" and edges are the connections between them. In Plato's terminology, objects are nodes and cross references are edges. The intent of xRef map markup is to take Plato objects and cross references and translate them into formats that are compatible with the various applications that are designed to display and analyze cross reference maps. Plato comes with generic markup for the following graphic file types:
  • dot The Graphviz dot format is a standard format that specifies nodes and edges, attributes such as color, shape and labels, and more advanced constructs such as nested graphs (but Plato does not support the creation of nested graphs from markup).
  • xgmml An XML based standard format that specifies and displays nodes and edges. The format also supports the specifying of node/edge attributes beyond labels, but such attributes may be application-specific.
  • net This is the Pajek standard network file format. It consists of a list of vertices (nodes) and a list of edges.
  • gml An XML based standard format that specifies nodes and edges. In addition to node and edge attributes, it supports more advanced contructs such as nested graphs (but Plato does not support the creation of nested graphs from markup).
  • sif A very simple format that specifies edges.

How Plato Handles Cross Reference Maps

When Plato gets a request to build a cross reference map using markup, it has already built a table of edges and used it to display xrefs in its native hierachical display (see the left half of figure 1). It then takes the edge table and generates a list of nodes that are referenced in the edge table, and ensures that each node in this table is only listed once. Once this list is complete, it also builds an internal cross reference table that allows all edges to be referenced againd the node list. This allows some flexibility in how nodes and edges may be referenced in the markup, since the graphics formats have various conventions for such referencing. Some formats such as SIF (and simple DOT constructs) require only edges to plot a graph. But other formats such as GML and XGMML require that both nodes and edges be specified; Pajek NET requires nodes and edges and further stipulates the order in which they must appear in the NET file.

How Plato Displays Cross References
Plato data structures
Figure 1: How Plato Displays Cross References in the Tree Pane
Plato displays cross references in the tree pane in a standard left-to-right hierarchy. The are three displays:
  • categories Relationships between categories within a family of categories are captured via cross references of the "intra-category link" type. This allows them to be displayed as maps.
  • cross reference hierarchies The cross reference hierarchy display is keyed to the currently selected object in a folder and displays all the parent/child relationships between that object and ther objects. This hierarchy display is also interactive in that double-clicking an object will generate a new display with the clicked object as the new reference point. This display may be capured as a map at any point.
  • folders Nested folders are "nested" using cross references of the "nested-folder" type, which allows them to be displayed as maps if desired. However they are a special category of cross reference and cannot be modified outside of altering a folder's properties (see xxxxx).
Each display uses exactly the same internal structures to generate its cross reference display.
Using the Markup Editor for Cross Reference Maps
Plato data structures
Figure 2: Markup Pane for Xref Maps
Figure 2 shows the markup editor configured for cross reference map markup. The conventions and controls are the same as for document creation markup, with a few differences outlined below.

Note that the markup editor controls are keyed to the selected section type: as you change the section type, the available controls will change based on the section you're selected. In some cases the editor will allow you to enter codes into a section using controls that are not applicable to it. However, the error checker will identify any inapplicable codes and force you to correct them before saving the markup.

Markup Labels The following section labels may be used:
  • [[head]] Markup under this section will be placed at the beginning of the output file.
  • [[tail]] Markup under this section will be placed at the end of the output file.
  • [[cross_reference_edge]] Markup under this section defines a cross reference edge, usually in terms of two nodes and perhaps an edge type.
  • [[cross_reference_edge_no_parent]] This is special category of markup if you wish to treat unconnected nodes in a special way. If you include a "cross_reference_node_no_parent" section and leave it blank, unconnected nodes will be excluded from the map.
  • [[cross_reference_node]] Markup under this section defines nodes and their attributes. Usually these attributes are simply color, shape, or descriptive labels, but depending on the mapping application other node attributes may be described as well.
  • [[dot_link_labels]] This section only pertains to maps in the dot format. It allows you to list attributes for edges. A sample:
    hydrographic_chains = [color=blue];
    general cross references = [color=black];
    In this sample two link types are assigned color attributes.
  • [[dot_object_labels]] This section only pertains to maps in the dot format. It allows you to list attributes for nodes. A sample:
    geo_fjord = [color=lightblue]
    geo_river = [color=green]
    geo_tributary = [color=turquoise]
    geo_town = [shape=ellipse color=brown]
    geo_strait= [color=lightgray]
    geo_sound = [color=lightgray]
    geo_lake = [shape=circle color=green]
    In this sample a list of nodes (geo_fjord, Geo_river, etc.) are assigned color and shape attributes.
  • [[post_processing]] This section defines post-processing instructions.
  • [[swap_list_template]] Acts only on the markup before any object data is attached.

Markup Codes The code generator works as for document markup with some variations for depicting cross references. For cross reference edges, each attribute code is prefaced with a "parent:" or "child:" prefix, since this is how Plato distinguishes each cross reference node. A special code is available to indicate the type of cross reference. In a cross reference edge for a SIF-formatted file, these codes might appear thus:
[parent:@mapnode] [xrefType] [child:@mapnode]
. There are some other special codes available to cross reference markup:
  • [@hierarchy] will insert a unique hierarchy label in to the map that shows the position of the current node with reference to the hieracrchy of of nodes it resides in:
    The label illustrated indicates that the current node is the second node at the fourth level, and is a child of the 23rd node at the third level, which is a child of the 12th node at the second level, which is a child of the first node at the first level.
  • [@MapNode] Provides a unique reference to the position of a node in the node table; such referencing is the preferred method to cross reference edges to the node table in many map formats.

Invoking Cross Reference Maps
Plato data structures
Figure 3: Invoking Cross Reference Maps
Sample Map Output: Plain Text
Plato data structures
Figure 4:

Object Class Hierarchy Description
--------------- -------------------- --------------------------------------------
[child:@objectclass/15] [child:@hierarchy/20] [child:@description]
Sample Map Output: Dot Format, Zvgr
Plato data structures
Figure 5: Dot Formatted Map Viewed in Zgvr.

digraph g{
node[shape=box, style=filled, color=lightblue];
fontsize = 20;
"[parent:@description]" -> "[child:@description]"
zgvr $plato_out$\

Sample Map Output: Net Format, Pajek
Plato data structures
Figure 6:

*vertices %map_node_count%
[[cross_reference_node function_category: 497]]
[@mapnode] "[@description]"
[parent:@mapnode] [child:@mapnode]
copy $plato_out$\ $plato_out$\
pajek $plato_out$\

Sample Map Output: Dot Format, Gephi
Plato data structures
Figure 7:

digraph g{
"[parent:@description]" -> "[child:@description]";
gephi $plato_out$\

Sample Map Output: Indented Text
Plato data structures
Figure 8:

Root Node
Class Library
Class Library Settings
Cross Reference Map
Export Class Library
Export Database
Object Import
Script Markup
Markup Sections
Object Attributes
Data Types
Object Attribute Editing
Object Classes
Object Actions
Object Categories
Object Class Editing
Class Library List
Class Library List Editing
Database List
Database List Categories
Database List Editing

This page last updated on 2014.09.06