ZMap Configuration

Overview

ZMap configuration is via command line options and a number of resource files read during intitialisation and during subsequent processing. This section describes the various ways ZMap can be configured.


Command Line Options

ZMap recognises command line options starting with double dashes:

Usage:
  zmap [OPTION...] 

A multi-threaded genome browser and annotation tool.

Help Options:
  -?, --help                Show help options

Application Options:
  --version=          Program version.
  --start=coord             Start coord in sequence, must be in range 1 -> seq_length.
  --end=coord               End coord in sequence, must be in range start -> seq_length, but end == 0 means show to end of sequence.
  --conf_file=file path     Relative or full path to configuration file.
  --conf_dir=directory      Relative or full path to configuration directory.
  --win_id=0x0000000        Window ID of the controlling application.

Configuration Files - Format

The format of the configuration files follows a stanza-based key-value format defined in the GLib Key-value parser package, e.g.

# this is a comment.

[StanzaName]
# another comment.
property = value                           # string
numeric = 1.0                              # float
number = 32000                             # int
truth = true                               # boolean
list = one ; two ; three ; four            # multiple strings

[Next Stanza]

etc.

White space is not important.

Any text following (and including) a "#" is interpreted as a comment and ignored.

Some keywords are mandatory within a stanza and hence have no default value. If are not specified the stanza is ignored.

A longer annotated example can see seen here.


Directories and Files

ZMap uses configuration files to find its servers, files and to configure aspects of its interface. By default ZMap looks for these files in the users $HOME/.ZMap directory. The user can specify an alternative directory using the --conf_dir option.

If the configuration directory does not exist then ZMap will not run.

ZMap configuration file

By default the ZMap configuration file is searched for in the configuration directory but an alternative file can be specified with the --conf_file option. If this file does not exist ZMap will not run.

Styles configuration file

This file should be located in the configuration directory and named according to the value of the stylesfile option in the ZMap stanza of the ZMap configuration file.


ZMap Configuration File Stanzas

The following stanzas are supported by ZMap:

ZMap will work with single or multiple data sources. If there is only one data source it can be named 'source' and will be used automatically. If there are multiple data sources each one must be named uniquely and listed in the sources key in the ZMap stanza.
Styles should be defined a separate configuration file, referred to in the ZMap stanza with the 'stylesfile' key.


ZMap Application Options These are options that control the fundamental way ZMap behaves.

Stanza "ZMap"
Keyword Datatype Default Description
"show_mainwindow" Boolean true If false then the intial main zmap window is not shown, this is useful when zmap is being controlled by another application and its not necessary for the user to directly open feature windows themselves.
"exit_timeout" Int 5 Time in seconds to wait for zmap to finish clearing up server connections before exiting. After this zmap will exit and some connections may not have been clearly terminated.
"default_sequence" String "" if a particular sequence has its own unique configuration file, then the sequence name can be specified in the file.
"default_printer" String "" Specify a printer which will be the default printer for screen shots from ZMap.
"script-dir" String "ZMap run-time directory" Specify the directory where data retrieval scripts are stored by default.
"data-dir" String "ZMap run-time directory" Specify the directory where GFF data files are stored by default.
"stylesfile" string "" Styles specify how sets of features are displayed and processed. By default this information is fetched from the server for each feature set. As an alternative the styles can be specified in a file in $HOME/.ZMap. (see "style" stanza description)
Logging Options ZMap writes messages to the logfile $HOME/.ZMap/zmap.log by default, but the log filepath and other parameters of logging can be specified in the "logging" stanza.

Stanza "logging"
Keyword Datatype Default Description
"logging" Boolean true Turn logging on or off.
"file" Boolean true true: messages to logfile, false: messages to stdout or stderr.
"directory" String "$HOME/.ZMap" Absolute or relative directory to hold logfiles (relative is relative to $HOME/.ZMap).
"filename" String "zmap.log" Name of logfile, this is combined with "directory" to give the logfile path.
Data Source Options ZMap can obtain sequence data from files and servers of various kinds, source stanzas specify information about the source. Each source stanza should must have a unique name, and must be referenced in the 'sources' resource in the [ZMap] stanza.

Data sources are identified using urls in the following supported variants:

    url = "<url_identifier>"

    where <url_identifier> should match ([] = optional)

    <protocol>://[[<username>:<password>@]<hostname>[:<port>]]/<location>#<format>

    <protocol> may be one of acedb, file, pipe or http
    <username> should be a username string
    <password> should be a password string
    <hostname> should be a hostname string
    <port>     should be a port number
    <location> should identify the location on a particular server
    <format>   may be one of gff, das, das2 (default gff)

    examples

    file:///var/tmp/my_gff_file.gff#gff
    pipe:////software/anacode/bin/get_genes?dataset=human&name=1&analysis=ccds_gene&end=161655109...
    http://das1.sanger.ac.uk:8080/das/h_sapiens#das
    acedb://any:any:23100

    N.B.  <location> might include a query string too. e.g.

                 http://www.sanger.ac.uk/das/h_sapiens?chromosome=1#das
    Note that for file: and pipe: sources file:///file is a relative file name and file://// is absolute.

Stanza "source"
Keyword Datatype Default Description
"url" String Mandatory The url specifying where to find the source.
"featuresets" String "" A list of feature sets to be retrieved from the source(s). The list also gives the order in which the feature sets will be displayed in the zmap window. If not specified, all available feature sets will be retrieved and they will be displayed in whichever order the list of available sets was returned by the server.
"navigatorsets" String "" A list of feature sets to use in a navigator window.
"timeout" Int 120 Timeout in seconds to wait for a server to reply before aborting a request.
"version" String "" The minimum version of the server supported, must be a standard version string in the form "version.release.update", e.g. "4.9.28". If the server is an earlier version than this the connection will not be made.
"use_acedb_methods" Boolean false Only read for acedb databases. If true, then zmap reads style information from Method class objects instead of the newer and more flexible ZMap_style classes.
"sequence" Boolean false If true, this is the server that the sequence for the feature region should be fetched from, only one such server can be specified.
"writeback" Boolean false If true, this is the server that user changes/annotations to features should be written back to. Only one such server can be specified.
"format" string "" Defunct, use the "url" keyword/value to specify the format.
"styles" string "" List of all styles to be retrieved from styles file. If not specified then all styles will be read if a file has been specified in the [ZMap] stanza, otherwise the source should provide the styles itself. By default a featureset will use a style of the same name.

Mapping data sources into display columns

Traditionally, ACEDB provided this mapping during ZMap startup, but without an ACEDB connection we have no way of recieving this data.

By default, any feature requested from a pipe or other server that does not support the REQ_FEATURESETS request will be mapped to a column of the same name - this will produce a wider than normal display, but the data will at least be visible.

The stanza [featuresets] may be used to override this default mapping and will contain lines of the form:

column = source1; source2; ... sourceN
where 'column' is the name of the column that is used to display all the sources and sourceX is the name of a featureset used to request the data as receieved from Otterlace and as sent by a pipeServer or other server.

NB: This stanza will only be read in when creating a view and not on requesting a column. To change this mapping it is necessary to update the file ZMap (config) and then create a new ZMap window.

Style Options

NB: this stanza appears in a separate config file specified in [ZMap] stylesfile=xxx. Available options are given here.

ZMap Feature Window Options The ZMap feature window is where sequence features are displayed, various aspects of it can be configured from colours to performance factors.

Stanza "ZMapWindow"
Keyword Datatype Default Description
"canvas_maxsize" Integer 30000 Set the maximum vertical extent of the feature window. Setting a smaller size will result in faster display as less data gets mapped as you zoom in but will mean you have less data to scroll over. The default is to create close to the maximum window size possible, this is 32k for X Windows.
"canvas_maxbases" Integer 0 Set the vertical extent of the feature window using dna bases. Is just an alternative method of setting "canvas_maxsize".
"keep_empty_columns" Boolean false Some requested feature sets may not contain any features, by default these will not be displayed. For multiple blocks/alignment display it may be clearer to get zmap to display empty "placeholder" columns for these sets so that columns in different blocks line up better.
"colour_root" string white" Colour for window background, specified as in the "Type" stanza.
"colour_alignment" string "white" Colour for each alignment background, specified as in the "Type" stanza.
"colour_block" string "white" Colour for each block background, specified as in the "Type" stanza.
"colour_m_forward" string "white" Colour for forward strand column group background in master alignment, specified as in the "Type" stanza.
"colour_m_reverse" string "white" Colour for reverse strand column group background in master alignment, specified as in the "Type" stanza.
"colour_q_forward" string "light pink" Colour for forward strand column group background in matched alignment, specified as in the "Type" stanza.
"colour_q_reverse" string "pink" Colour for reverse strand column group background in matched alignment, specified as in the "Type" stanza.
"colour_m_forwardcol" string "white" Colour for forward strand column background in master alignment, specified as in the "Type" stanza.
"colour_m_reversecol" string "white" Colour for reverse strand column background in master alignment, specified as in the "Type" stanza.
"colour_q_forwardcol" string "light pink" Colour for forward strand column background in matched alignment, specified as in the "Type" stanza.
"colour_q_reversecol" string "pink" Colour for reverse strand column background in matched alignment, specified as in the "Type" stanza.
Debugging Options You should only use these if you are a developer as they can impact the performance of ZMap significantly or cause it to write large amounts of data to stdout.

Stanza "debug"
Keyword Datatype Default Description
"threads" Boolean false Turns on/off debug output for the threading sections of ZMap.
"feature2style" Boolean false Turns on/off debug output for mapping featuresets to styles.
"styles" Boolean false Turns on/off debug output for style definitions.
Multiple Alignment Options ZMap can display multiple alignments, each alignment can contain multiple blocks. This stanza specifies which blocks in which alignment match each other. Note that all parameters are mandatory otherwise zmap will not know how to display the blocks.

Stanza "align"
Keyword Datatype Default Description
"reference_seq" String Mandatory Name of the "master" or reference sequence, this sequence is shown on the right of the window and blocks in other alignments are aligned to it.
"reference_start" int Mandatory Start position of a block in the reference sequence.
"reference_end" int Mandatory Start position of a block in the reference sequence.
"reference_strand" int Mandatory Which strand of the reference sequence is being aligned, 1 means forward strand, -1 means reverse.
"non_reference_seq" String Mandatory Name of the "master" or non reference sequence, this sequence is shown on the right of the window and blocks in other alignments are aligned to it.
"non_reference_start" int Mandatory Start position of a block in the non reference sequence.
"non_reference_end" int Mandatory Start position of a block in the non reference sequence.
"non_reference_strand" int Mandatory Which strand of the non reference sequence is being aligned, 1 means forward strand, -1 means reverse.
Blixem Options ZMap can show multiple alignments using the blixem program, this stanza tells zmap how to find and run blixem.

Stanza ZMAPSTANZA_ALIGN_CONFIG
Keyword Datatype Default Description
"netid" String Mandatory The network id of the machine running pfetch from which blixem will retrieve the sequences to be shown in the multiple alignement.
"port" int Mandatory The port number on the "netid" machine for the pfetch server.
"script" String Mandatory The name of the blixem program, this could be a shell script which sets up some environment and then starts blixem or indeed another multiple alignment display program.
"scope" Int 40000 The span around the selected feature about which blixem will get and display data for the multiple alignment.
"homol_max" Int ???? The maximum number of homologies displayed ?? CHECK THIS....