ACEDB source code documentation: histogramming

# Using the histogram features in Physical-Chromo-Map

    Several people have asked how to use the facility in acedb to show
    histograms of the chromosomal distribution of various items.  There is
    in fact quite a flexible system for doing this, but it is a little
    intricate to use.  I always have to relearn it myself whenever I use
    it, so it seemed a good idea to write comprehensive instructions.

    From a standard map display, go to "Physical Chromo Map" (the last
    item on the menu).  From there choose "Full Genome Distribution".
    With a worm database, you should now see the six chromosomes with
    yellow bars for the physically mapped regions.  There are now two
    relevant menu entries, "Create histogram from file" and "Create
    histogram from keyset".

    Create histogram from file
    --------------------------

    The file version is more flexible, so I will describe that first.  The
    file must have the ending ".hisinf" to be read in by the program.  The
    required format is

    	CLONE_NAME [n] [len]

    where n is the number of items in that cosmid, and len is its length.
    The clone must be on the physical map for the information to register.
    If n is missing it is assumed to be 1.  Multiple lines for the same
    clone will add; this is fine for the n values, but the lengths also
    add (unfortunately), so you should not have multiple lines per clone
    if you give length information.

    You can create multiple histograms for a single window by reading in
    multiple files.  For each data set, you get a little window that lets
    you set a number of different parameters:

      Histogram bin: bin size in Mb (i.e. as on image scales).  Must be > 0.
        If you set the bin width to 0 you suppress the column, even in line
        mode.
      Width factor: Let us call this wfac. In histogram mode, if you gave
        lengths then the width of each block is wfac*ntot*1000000/lentot,
        i.e. wfac=1 shows the normalised number per Mb.  In a histogram
        without length information, the block width is wfac*ntot/binsize,
        equivalent to assuming there is complete coverage of information
        in the bin (not a good assumption for sequence-based information!).
        In line mode, lengths are ignored, and the line size for each
        clone is wfac*n.
      Colour: acedb colour: 0=WHITE, 1=BLACK, 2=LIGHTGREY, 3=DARKGREY,
        4=RED, 5=GREEN, 6=BLUE, etc.
      Offset: offset right of yellow bars, in character width units.
      Name: gets printed above the column for each chromosome.
      Is Line: 0 or 1 - 0 for a histogram, 1 for a line per clone

    To see any effect after a change you must redraw the display with
    "Full Genome Distribution".

    If you quit the column specification window, you can get it back again
    with "Edit histogram columns" from the menu.

    Create histogram from keyset
    ----------------------------

    The "from keyset" option makes a list from the active keyset.  It
    takes all Clone objects that are either directly on the physical map,
    or that are connected by a Positive tag2 relationship with clones on
    the map, e.g. cDNA clones with hybridisation data.  Note that the
    latter functionality is only available via the keyset option.  It then
    works the same way as the file option without lengths.

    Example
    -------

    There is an example file containing the number of CDS per cosmid from
    in ~rd/worm.data/9510/cosmids.cds.hisinf:

      AH6 13 37801
      B0034 5 35228
      B0228 9 38946
      B0244 8 43546
      ...

    Load this file, set (bin 1, wfac 0.02, colour 3, offset 0, name
    "His", isline 0), and to see something.

    Now load the same file again, and use (bin 1, wfac 0.5, colour 6,
    offset 5, name "Line", isline 1) to see an example of line display.

    You can vary the histogram width in histogram mode without changing
    anything else.  If you set it very small, e.g. 0.1, you get something
    that looks quite like the line display, but is in fact a little
    different.

    Make a keyset of all A* clones, load this with "Create histogram from
    keyset" and set (bin 1, wfac 1, colour 4, offset 10, name "A*", isline
    0).  This shows the chromosomal distribution of the 97 unburied Axxxx
    clones.