zmapFeature - Feature Context - the model part of MVC

Index Terminology Mapping to columns and styles Identifying
Terminology

Features are organised in columns on the ZMap display, a group of these is known as a featureset.

However it gets a little more complicated than that: in include/Zmap/zmapServerProtocol.h we find that a feature source is the name of a feature as it is known in a far-away database. Several of these can be placed in a single featureset.

A feature source is not where a feature is retrieved from but the name of it. Various parts of ZMap also refer to a source in a zmapServer context in which case source refers to the name of the server as defined in a ZMap config file stanza or the zmapServer module itself. A server module can supply a mapping that specifies which featureset a feature source is to be placed in.

Many of these words can get used interchangably.

Example

EST_human is a column that contains the feature sources EST_human and Saturated_EST_Human, all three of which are know as featursets. column is unambiguous.
Mapping features (data sources) to featureset (display columns) and feature style

Source to feature set

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.

A new config stanza [featuresets] will be provided in ZMap 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 the a pipeServer or other.

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.

Mapping Features to Styles

Traditionally ACEDB could map a feature to a style, but for a pipeServer that cannot do this (as GFF does not support this) the obvious solution is to have a 1-1 mapping of featuresets to styles of the same name. As styles can be inherited, if it is required to have two featuresets displayed using the same style then they can both inherit the same base style unmodified.

Merging data from different sources

Previous ACEDB functionality will remain honoured. If we end up with conflicting data being defined by different sources then the first defined data will have priority regardless of the source. This is in line with existing merge operations. Note that this implies that feature attributes can only be added to or changed but not removed (eg by taking out a background colour).

Identifying a featureset A featureset has a original_id and a unique_id (see zmapFeature.h) - the original_id is as given in a config file or from a database and is regarded as case insensitive. This is stored as as a GQuark and is translated into an internal_id which is in lower case, and for some features also includes extra information as necessary.

There are functions (eg zMapFeatureSetCreateID() - simple lower casing) that do this. (Need some more notes here).

A zmapView has some data structures that map feature set sources to display columns and styles:

  GHashTable *featureset_2_stylelist ;    /* Mapping of each feature_set to all the styles it requires. */
  GHashTable *source_2_featureset ;       /* Mapping of a feature source to a featureset. */
  GHashTable *source_2_sourcedata ;       /* Mapping of a feature source to its data. */
These are hash tables that map a featureset unique_id to another data structure.

According to zmapViewRemoteReceive.c/xml_featureset_start_cb() zmapView->source_2_featureset is a hash table of ZMapGFFSet and zmapView->source_2_sourcedata is a hash table of ZMapGFFSource. We presume that the id fields relate to unique_id rather than original_id (styles have both, as for featuresets).

/* Struct for "feature set" information. Used to look up "meta" information for each feature set. */
typedef struct
{
  GQuark feature_set_id ;                           /* The set name. */
  char *description ;                               /* Description. */
} ZMapGFFSetStruct, *ZMapGFFSet ;


/* Struct holding "per source" information for GFF data. Can be used to look up the
 * style for a GFF feature plus other stuff. */
typedef struct
{
  GQuark source_id ;                                /* The source name. */
  GQuark source_text ;                              /* Description. */
  GQuark style_id ;                                 /* The style for processing the source. */
} ZMapGFFSourceStruct, *ZMapGFFSource ;

zmapView->featureset_2_stylelist is more obscure: zmapView.c/addPrefined() sets zmapView->orig_styles as a GData (keyed data list), and then zmapView->featureset_2_stylelist as a GHashTable of GLists of style quark id's. (see zmapView.c/styleCB() and zmapGlibUtils.c/zMap_g_hashlist_insert());

This last thing looks confusing: it looks like the style is is keyed off the style id rather than the featureset id; (it may be that the style names are identical to the featureset names in this case??). Identical code appears in zmapView.c/processDataRequests() to add in a 1-1 mapping from a (pipe) server that does not support this mapping. zmapServer/acedb/acedbServer.c/parseMethodStyleNames() set up a similar list with different featureset and style names.

Some related information from zmapGFF2Parser.c: "NOTE the feature sets style has the same name as the feature set" - this relates to featureset expressed as a display column.

NOTE:In zmapFeatureContext.c/zMapFeatureString2QuarkList() the function zMapStyleCreateID() is used to get a feature ID, or so it seems... This function is used to make a list of featureset names in zmapViewConnect().