NCBI C Toolkit Cross Reference

   CONFIGURING SEQUIN'S ASN2GRAPHIC GRAPHICAL SEQUENCE VIEWER
   
   asn2graphic is a viewer for displaying biological features on sequences. It
   is designed to be both efficient and flexible. It is able to quickly process
   entire chromosomes with thousands of features, displaying them at any
   desired scale of magnification. Its behavior can be easily modified using a
   simple, human-readable configuration file.
   
   There are three questions to consider when customizing the display:
  
    1. How should a given feature be rendered?
    2. Which features should be displayed?
    3. Where should those features be positioned?
  
  asn2graphic addresses these issues by the concepts of Styles, Filters, and
  Layout methods, respectively. Configurations are stored in a file called
  asn2gph.ini (on PC), asn2gph.cnf (on Mac), or .asn2gphrc (on UNIX). Several
  styles and several filters can be specified, and the names for these can be
  presented in popup menus.
  
  Styles
  
  Styles control how features are rendered, specifying such details as color,
  line height, label font, and gap style. The [Styles] section lists the
  individual styles that are configured:
  
    [Styles]
    style1 = warm
    style2 = cool
    ...
  
  style00 is reserved as the built-in Default style, and should not be present
  in the configuration file.
  
  The [Styles] section can also have the following elements:
  
    maxarrowscale = 5
    minarrowpixels = 5
    shadesmears = false
  
  These can be overridden by settings in individual styles.
  
  Each style has a master section, and it must have an element specifying the
  name presented to the user:
  
    [warm.master]
    name = Bright Colors
  
  The master section can also override relevant global values set earlier:
  
    maxarrowscale = 5
    minarrowpixels = 5
    shadesmears = false
  
  The master section can also set defaults for the box and font used when the
  features of a named annotation are grouped together or when a filter
  displays a groupbox around its feature contents:
  
    annotboxcolor = dark grey
    annotlabelfont = Times, 12
    annotlabelcolor = black
    groupboxcolor = red
    grouplabelfont = Courier, 9
    grouplabelcolor = blue
  
  The master section, and specific feature sections, can include any of the
  following elements:
  
    color = 205, 133, 63
    labelfont = medium
    labelcolor = dark red
    label = above
    displaywith = box
    height = 20
    gap = line
    showarrow = no
    showtype = no
    showcontent = true
    shadesmears = false
  
  Note that "yes", "true", and "on" are all recognized as true, and "no",
  "false", and "off" are all recognized as false. Note also that named colors
  can be prefixed by "light" or "lt" for lighter, and "dark", "drk", or "dk"
  for darker.
  
  Individual features can have their own sections, which can override values
  inherited from the master section. Only the elements that are to be changed
  need to be specified:
  
    [warm.cds]
    color = magenta
    labelfont = program
    labelcolor = magenta
    showarrow = yes
    gap = angle
  
  Alignment sections can also have a format element, the same as Bioseq's.
  This specifies the information included in the feature's labels:
  
   [warm.align]
   format = fasta
 
 Import features (e.g., exon, variation) can have an intermediate section for
 overriding default settings. Individual import features then inherit from
 that section:
 
   [warm.imp]
   color = gray
   labelcolor = light gray
   showcontent = false
 
   [warm.exon]
   color = green
   showcontent = true
 
 Several feature sections can also indicate a named style for inheritance,
 allowing a set of attributes to be shared among unrelated groups of
 features:
 
   [UseLabels]
   label = left
   showtype = true
   showcontent = true
   height = 15
   
   [warm.gene]
   usenamedstyle = UseLabels
   labelfont = Courier,12,b
   showarrow = yes
   
   [warm.mrna]
   usenamedstyle = UseLabels
   displaywith = outlinebox
 
 The Bioseq style can have the following elements:
 
   [warm.bioseq]
   label = left
   format = accn
   scale = true
   labelfont = system
   scalefont = small
   height = 10
   scaleheight = 20
   color = green
   labelcolor = dark green
   scalecolor = black
 
 FILTERS
 
 Filters control how features are grouped for display, allowing different
 kinds of features to be collected in separate passes. Each group is placed
 below the previous one. The [Filters] section lists the individual filters
 that are configured:
 
   [Filters]
   filter1 = mol-bio
   filter2 = single
   ...
 
 filter00 is reserved as the built-in Default filter, and should not be
 present in the configuration file.
 
 The [Filters] section can also have the following elements:
 
   maxlabelscale = 200
   grouppadding = 2
   rowpadding = 2
 
 These can be overridden by settings in individual filters and filter groups.
 
 Each filter has a main section, and it must have an element specifying the
 name presented to the user:
 
   [mol-bio]
   name = Molec Biol
 
 The main section can also specify the following optional elements:
 
   layout = compact
   grouppadding = 3
   rowpadding = 5
   suppressbioseq = false
   suppressgraphs = false
   annotgroup = true
   annotbox = true
   annotlabel = above
   annotboxcolor = grey
   annotlabelcolor = black
   annotlabelfont = program
 
 By default, the Bioseq and scale are placed above the first group, and
 graphs (e.g., base quality scores) are placed below the last group. These
 can be overridden with the "suppressbioseq" and "suppressgraphs" elements.
 
 If annotgroup is true (which it is by default) features and alignments that
 are within a named annotation will be grouped separately. A box can
 optionally be drawn around them (annotbox) and the section can be labeled
 with the annotation's name (annotlabel). The other 'annot' color and font
 settings override the style settings with the same names.
 
 The main section must also specify a list of filter groups:
 
   group1 = bioseq-and-scale
   group2 = gene-mrna-cds-prot
   group3 = rnas
   group4 = intron-exon
   group5 = everything-else
   ...
 
 Each group has its own named sections, and these could be used by more than
 one filter. The group lists the individual feature types collected in that
 pass:
 
   [filters.gene-mrna-cds-prot]
   feature1 = gene
   feature2 = mrna
   feature3 = cds
   feature4 = prot
 
 Note that "everything" or "all" collect all remaining features, "rna" and
 "prot" collect all remaining RNAs or proteins, respectively, and "bioseq"
 and "graph" as feature values override the default placement of the Bioseq
 or graphs.
 
 In each group, the following elements can also be specified:
 
   name = Gene-mRNA-CDS-Prots
   layout = geneproducts
   grouppadding = 3
   rowpadding = 5
   groupbox = true
   groupboxcolor = 150, 100, 50
   fillbox = false
   grouplabel = above
   grouplabelfont = large
   grouplabelcolor = dark grey
   label = above
   showtype = true
   showcontent = true
   strand = both
 
 Features pass through the groups until they match. Thus, if two different
 groups match the same type of feature, these features will only appear in
 the first matching group. This simplifies the creation of "everything else"
 groups. A filter that includes "everything" only displays features not yet
 matched by a previous group.
 
 If an element of a filter group has the same name as one in a style section
 (e.g., label, showtype, showcontent), any value specified in the filter
 group overrides that set in the style section.
 
 LAYOUT METHODS
 
 A filter group can specify a layout method if it does not want to inherit
 the default value. This determines how features in a group are packaged with
 respect to each other. The possible choices are:
 
   inherit -      Inherits the default value.
 
   diagonal -     Each feature is placed in a different row.
 
   compact -      Attempts to minimize the number of rows, without permitting
                  features or labels to overlap.
 
   bytype -       Features are grouped by type, and the groups are separated
                  vertically. Within each group neither features nor labels
                  will overlap.
 
   smear -        Features are grouped by type, but each group occupies only
                  one row. Overlapping features are drawn as an ambiguous
                  smear.
 
   geneproducts - Similar to compact, but genes, mRNAs, and CDS features are
                  treated specially. Genes are displayed first, then pairs of
                  mRNAs followed by the CDSs they encode. This clearly shows
                  mRNA/CDS pair combinations in alternative splicings.
 
 PARSER REFERENCE
 
 When parsing colors, the following named colors are recognized:
 
   black, blue, brown, coral, cyan, gray, green, grey, lavender, magenta,
   maroon, orange, olive, pink, purple, red, white, yellow
 
 Variations on these colors are supported with the light/lt or dark/drk/dk
 prefixes.
 
 Colors can also be specified using a triplet of numbers to represent the
 red, green, and blue intensities (in that order). The numbers must be
 integers between 0 and 255 inclusive. The numbers can be separated with
 commas, which improves readability.
 
 Fonts are parsed as the typeface name and the point size, separated by a
 comma. For example:
 
   labelfont = Courier,12
 
 Modifiers can optionally be added after the size: "b" for bold, "i" for
 italic, and "u" for underline (in any combination).
 
   labelfont = Helvetica,24,ib
 
 Also, a few named fonts are recognized: "system" and "program" are the
 (platform-specific) default fonts. "small", "medium", and "large" are also
 recognized.
 
 There are several ways that features can be rendered. These are controlled
 by the displaywith element in a style. The following values are recognized:
 
   none, line, cappedline, box, outlinebox
 
 Feature labels can be displayed in several locations, which are controlled
 by the label element. The values can be one of:
 
   above, top, left, below, inside, none
 
 Filter and annotation groups can also have labels. The grouplabel and
 annotlabel element can be one of:
 
   above, top, left, below, none
 
 Sometimes it is desirable to create a filter group that only matches
 features on a specific strand. This is done by specifying a strand element.
 Values of "plus" or "minus" refer to features only on those strands. The
 default value is "both".
 
 A Bioseq or alignment style has several options for its label, which are
 controlled by the format element. These include:
 
   accession, accn, fasta, long
 
 The accession or accn choices show the accession.version (U54469.1), while
 fasta shows the short FASTA parsable form (gb|U54469.1|), and long shows the
 long FASTA form (gb|1322283|gb|U54469.1).
 
 Bioseq label locations can be one of:
 
   above, top, left, below, none
 
 PROGRAMMING
 
 asn2graphic uses the picture component of Vibrant, the graphical user
 interface mocule of NCBI's C language software toolkit. Pictures are a
 Vibrant memory structure containing the primitive graphical elements to be
 displayed. Interactive programs then attach the picture to a viewer in order
 to be displayed. Web servers can instead generate a GIF from the picture by
 linking with the vibgif library, and do not link in the vibrant library.
 
 Applications must #include <asn2graphic.h> to get the basic function
 prototypes. CreateGraphicView collects features on a Bioseq (optionally
 limited to a specific subregion) and creates a SegmenT, the internal data
 type for a picture:
 
   NLM_EXTERN SegmenT CreateGraphicView (
     BioseqPtr bsp,
     SeqLocPtr location,
     Int4 scale,
     CharPtr styleName,
     CharPtr filterName,
     CharPtr overrideLayout
   );
 
 The following functions parse the configuration file and return lists of
 style, filter, and layout names, respectively:
 
   NLM_EXTERN CharPtr PNTR GetStyleNameList (void);
   NLM_EXTERN CharPtr PNTR GetFilterNameList (void);
   NLM_EXTERN CharPtr PNTR GetLayoutNameList (void);
 
 Graphic view in Sequin has popup menus for Style and Filter populated from
 these procedures.
 
 Functions in the private header <asn2graphicp.h> control parsing of the
 configuration file, or generating styles and filters programmatically if you
 do not wish to use or provide an asn2gph file. However, it is easier to use
 TransientSetAppParam to simulate the configuration file than to use these
 functions.