Topic map processing, an introduction


Introduction

The Topic Map processor is a piece of software that is capable of importing, exporting, querying and manipulating Topic Maps. Topic Maps is defined in an international standard, ISO/IEC 13250 Topic Maps.

See the reference documentation for a complete overview of topic map classes and their methods. Only a few of them are mentioned here in this introduction. For an introduction to the Topic Map concept itself see the standard or the papers at the Infoloom site.


The command line utility; tmproc.py

The topic map processor can be started using the tmproc.py script. This tool takes several command line arguments. Use the -i option with the python interpreter to enter interactive mode after processing.

Usage

      python [-i] tmproc.py [options] file.xml

      Options:
            --validate : use a validating SGML/XML parser
            --debug    : write debug messages to stdout
            --arch=?   : do architectural processing on the file, where ? is the architecture name
            --name     : the name of the topic map
            --test     : dump information about the topic map to stdout
            --module=? : load the topic map classes from the specified python module [default: tm]
      

Sample usage

The following command will import the topic map that is stored in the XML file music.xml

python -i tmproc.py music.xml

An example of architectural processing in combination with topic map processing (requires xmlarch).

python -i tmproc.py --arch=TOPICMAP playsmap1.xml

Querying the Topic Map

The music.xml file contains a sample topic map about The Beatles. The examples in this introduction is taken from that topic map. Play around with it yourself in order to see what it is about.

In all the examples below the tm object is an instance of the TopicMap class. When you execute tmproc.py in interactive mode an object called tm is available. The tm object is the resulting topic map after the import of the topic map document.

The string representation of a topic consists of the following parts "<" + the name of the topic map module + "." + the name of the Topic class + " " + the SGML id of the topic + ">".

Example: <tm.Topic t-lennon-john>, where tm is the topicmap module and Topic is the topic class. t-lennon-john is the SGML id of the topic.

Topics, Associations and Facets

Locate a topic with a specific SGML id:

tm["t-lennon-john"] tm.get_topic_by_sgml_id("t-starr-ringo")

Get a list of all topics in the topic map:

tm.get_topics() tm.get_topics()

Get a list of all associations in the topic map:

tm.get_associations()

Get a list of all facets in the topic map:

tm.get_facets()

Check to see if a topic, association or facet is of a given type or a subtype:

tm.is_type(tm["t-harrison-george"], tm["tt-guitarist"]) tm.is_type(tm["t-harrison-george"], tm["tt-person"]) tm.is_type(tm["t-harrison-george"], tm["tt-person"], transitive=1)

Check to see if a topic map has a specified topic, association or facet:

tm.has_topic(tm["t-dylan-bob"]) tm.has_topic(tm["t-lennon-john"])

Other variants:

tm.has_association(association)
tm.has_facet(facet)

Get a list of all types of single topic, association or facet:

tm.get_types_list(tm["t-mccartney-paul"]) tm.get_types_list(tm["t-mccartney-paul"], transitive=1)

Get a nested list [hierarchy] of all types of a single topic, association or facet:

tm.get_types_hierarchy(tm["t-mccartney-paul"])

Getting topics that are used as types

The generic method for this is TopicMap.get_object_types(self, tm_objects=None, transitive=0).

TopicMap.get_topic_types(topics=None, transitive=0)

Returns a list of topics that are used as topic types

The method get_topic_types may take up to three parameters. topics can be a list of topics, but if None is specified all Topics of the TopicMap is evaluated. If transitive set to a true value all transitive types [ie. types of types] are included in the result.

Examples

Get the types of all topics in the topic map

tm.get_topic_types()

Get the types of two topics

tm.get_topic_types([tm["t-lennon-john"], tm["t-starr-ringo"]])

Get the types including transitive types

tm.get_topic_types(transitive=1) tm.get_topic_types([tm["t-lennon-john"], tm["t-starr-ringo"]], transitive=1)

TopicMap.get_association_types(associations=None, transitive=0)

Returns a list of all topics that are used as association types.

Examples
tm.get_association_types()

Other variants:

tm.get_association_types(transitive=1) tm.get_association_types(associations) tm.get_association_types(associations, transitive=1)

TopicMap.get_facet_types(associations=None, transitive=0)

Returns a list of all topics that are used as facet types.

Examples
tm.get_facet_types()

Other variants:

tm.get_facet_types(transitive=1) tm.get_facet_types(facets) tm.get_facet_types(facets, transitive=1)

Getting topics, associations and facets that are of a given type or a subtype

The generic method for this is TopicMap.get_objects_of_type(self, type, tm_objects=None, transitive=0).

TopicMap.get_topics_of_type(self, type, topics=None, transitive=0)

Returns a list of all topics that is of a given topic type or a subtype.

The method get_topics_of_type may take up to three parameters. type must be an existing topic. topics can be a list of topics, but if None is specified all Topics of the TopicMap is evaluated. If transitive set to a true value all topics of transitive types [supertypes] are included in the result.

Examples

Get all topics in the topic map that are persons.

tm.get_topics_of_type(tm["tt-person"])

Get topics that are persons from a list of three topics.

tm.get_topics_of_type(tm["tt-person"], [tm["t-liverpool"], tm["t-starr-ringo"], tm["tt-artist"], tm["t-mccartney-paul"]])

Get the topics that are of the type "tt-person" or of a more specific type, like "tt-vocalist".

tm.get_topics_of_type(tm["tt-person"], transitive=1)
tm.get_topics_of_type(tm["tt-person"], [tm["t-liverpool"], tm["t-starr-ringo"], tm["tt-artist"], tm["t-mccartney-paul"]], transitive=1)

TopicMap.get_associations_of_type(self, type, associations=None, transitive=0)

Returns a list of all associations of a given association type.

Examples:
tm.get_associations_of_type(tm["at-member-of"])

Other variants:

tm.get_associations_of_type(type, transitive=1)
tm.get_associations_of_type(type, associations)
tm.get_associations_of_type(type, associations, transitive=1)

TopicMap.get_facets_of_type(self, type, facets=None, transitive=0)

Returns a list of all facets of a given facet type.

Examples:
tm.get_facets_of_type(tm["ft-birth-date"])

Other variants:

tm.get_facets_of_type(type, transitive=1)
tm.get_facets_of_type(type, facets)
tm.get_facets_of_type(type, facets, transitive=1)

Getting associations that exists within given scope or subscope

The generic method for this is TopicMap.get_objects_in_scope(self, scope, tm_objects=None, transitive=0).

TopicMap.get_associations_in_scope(self, scope, associations=None, transitive=0)

Returns a list of associations that exists within the specified scope or in any of its subscopes.

The method get_associations_in_scope may take up to three parameters. scope must we an existing topic. associations can be a list of associations, but if None is specified all Associations of the Topic Map is evaluated. If transitive set to a true value all topics of transitive types [subtypes] are included in the result.

Examples

Get all associations that exists in the "tt-pop-music" scope.

tm.get_associations_in_scope(tm["st-music"])

Other variants:

tm.get_associations_in_scope(scope, associations)
tm.get_associations_in_scope(scope, associations, transitive=1)

Let's say that the [scoping] topics "st-pop-music" and "st-opera" was both of type "st-music". Then tm.get_associations_in_scope(tm["st-music"], transitive=1) would return all associations that were in the "st-music", "st-pop-music" and "st-opera" scopes.


Querying a Topic

Get hold of the topic Paul McCartney: paul_mccartney = tm["t-mccartney-paul"]

Get the SGML id: paul_mccartney.get_sgml_id()

Get the internal id: paul_mccartney.get_id()

Get the basenames: paul_mccartney.get_basenames()

Get the identity: paul_mccartney.get_identity()

Get the names: paul_mccartney.get_names()

Get the occurrences: paul_mccartney.get_occurrences()

Get the types: paul_mccartney.get_types()


Querying a TopicName

Get hold of the name: name = paul_mccartney.get_names()[0]

Get the internal id: name.get_id()

Get the basename: name.get_basename()

Get the display names: name.get_dispnames()

Get the sort names: name.get_sortnames()

Get the scopes: name.get_names()


Querying an Occurrence

Get hold of the occurrence: occur = paul_mccartney.get_occurrences()[0]

Get the internal id: occur.get_id()

Get the locators: occur.get_locators()

Get the role name: occur.get_rolename()

Get the scopes: occur.get_scopes()


Querying an Association

Get hold of the association: assoc = tm.get_associations()[0]

Get the internal id: assoc.get_id()

Get the roles: assoc.get_roles()

Get the scopes: assoc.get_scopes()

Get the types: assoc.get_types()


Querying an AssociationRole

Get hold of the association role: assocrl = assoc.get_roles()[0]

Get the internal id: assocrl.get_id()

Get the locators: assocrl.get_locators()

Get the role name: assocrl.get_rolename()

Get the types: assocrl.get_types()


Querying a Facet

Get hold of the facet: facet = tm.get_facets()[0]

Get the internal id: facet.get_id()

Get the type: facet.get_type()

Get the values: facet.get_scopes()


Querying a FacetValue

Get hold of the facet value: fvalue = facet.get_values()[0]

Get the internal id: fvalue.get_id()

Get the locators: assocrl.get_locators()

Get the type: fvalue.get_type()

Get the value: fvalue.get_value()


Querying a Locator

Note that the Locator class is only used for Occurrences. The get_locator methods on AssociationRole and FacetValue always returns a list of Topic objects. This is a limitation of the current implementation.

Get the internal id: loc.get_id()

Get the address: loc.get_adress()

Get the locator type: loc.get_loctype()


Exporting a topic map

Here is a short example of how to export a topic map to the interchange format that is specified in the Topic Map standard.

  • Import the tmutils module which contains the TMExporter class.
  • import tmutils

  • Create a TMExporter object.
  • e = tmutils.TMExporter()

  • Import a module that contains a SAX document handler class.
  • from xml.arch import xmlarch

  • Create a SAX document handler that should receive the SAX events.
  • doc_handler = xmlarch.Prettifier(writer=sys.stdout)

  • Export the topic map.
  • e.export(tm, doc_handler)

  • The document is then written to standard output. Any SAX document handler may be used in combination with the TMExporter class.

Geir O. Grønmo, grove@ontopia.net