
Digest2 Documentation   ----- version 0.06 -----

Contents

1.  Program overview:  purpose, version, availability, sample run
2.  Downloading:  source, other files
3.  Unpacking, building, installing
4.  Usage:  command line, configuration file
5.  Supplementary program:  gcr
6.  Theory and implementation details


1.  Program Overview

Digest2 uses statistical ranging techniques to compute chances that an
object is of various orbit classes.  Input is a file of 80 column MPC-format
observations, with at least two observations per object.  Output is orbit
class scores for each object.

Compared to the version 0.02, this version has been rewritten in C and has
several new features:

*  New algorithms, designed to give more accurate scores.
*  An updated solar system model.
*  Capability to produce scores for a variety of orbit classes, in addition
   to NEOs.
*  Utilization of multiple processor cores.

The program is still provided as source under an MIT-style open source
license, and available at http://code.google.com/p/digest2/.

Sample run:  Say you have some unidentified observations.  For example,
here are the discovery observations of the NEO 2005 OJ3.  (See MPEC
2005-P07 at http://cfa-www.harvard.edu/mpec/K05/K05P07.html.)

     C5O0011  C2005 07 30.88575 20 11 19.47 -11 08 07.6          19.1 R      599
     C5O0011  C2005 07 30.89573 20 11 18.69 -11 08 08.1          19.2 R      599
     C5O0011  C2005 07 30.90566 20 11 17.91 -11 08 08.6          19.0 R      599

You put them in a file, say fmo.obs, then type "digest2 fmo.obs" and 
get the following output:

-------  ----  NEO(q < 1.3)  -------------------
Desig.    RMS    Raw  No-ID  Other Possibilities
C5O0011  0.01  96.07  98.66  (MC 1)


The raw NEO score of 96.07 means that this is almost certainly a NEO.  The
no-ID score of 98.66 means it is even more certain to be a NEO discovery
in the case where you have already tried to identify the object among known
objects and found no obvious matches.  In the "Other Possibilities" column,
MC 1 means there is still a 1% chance of this turning out to be a Mars
crosser with q >= 1.3.


2.  Downloading

Create a new directory for the program and download directly into the
new directory, if that is convenient.  The source and associated files
are available at http://code.google.com/p/digest2/.  Click the Downloads
tab and download the latest archive.


3.  Unpacking, building, installing

The package is bzip2 tarball which you can unpack on most Unix-like
systems with the command "bzip2 -cd digest2.tar.bz2  | tar xvf -"
The contents are:

README        this file
LICENSE       open source license
s3m.dat       solar system population model
Makefile      script for building executable
digest2.c     C source and header files
d2model.c
d2math.c
d2mpc.c
muk.c
gcr.c
gcfmath.c
digest2.h
d2model.h
gcf.h

Type make, and executables should be built and other files created.  This
includes downloading a copy of astorb.dat from lowell.edu.  Astorb.dat is
fairly large and bandwidth on that site is often limited.  It may take a
few minutes.


4.  Usage

The main executable is digest2.

digest2 <obsfile>         score observations
digest2 -c                list available orbit classes
digest2 -h or --help      display help file
digest2 -v or --version   display version information

Obsfile must contain observations in the MPC 80 column observation format
and nothing else.  The observations should be sorted and there should
be at least two observations of each object.

Orbit classes, listed with -c, are listed with an abbreviation and a longer
more readable form.  The longer form is used for column headings, the
abbreviations are used in the Other Possibilities column.

Either abbreviations or long forms may be listed in an optional configuration
file, digest2.cfg.  The presence of classes listed in digest2.cfg limits
scoring to only the listed classes.  Other possibilities are not computed
or listed.  For example, if digest2.cfg contains

NEO
MC
Hun

program output is

-------  ----  NEO(q < 1.3)  Mars Crosser  Hungaria gr.
Desig.    RMS    Raw  No-ID    Raw  No-ID    Raw  No-ID
C5O0011  0.01  96.13  98.68   3.87   1.32   0.00   0.00

The program runs considerably faster in this case, as it does not compute
scores for other classes.

Notice the column format allows decimal places to be output for all configured
classes.  Notice also that the NEO scores are not exactly the same as in
the sample output in the previous section.  There is a bit of randomness
built in to the algorithm, and scores vary somewhat on repeated runs.

The second column, RMS, is an RMS of residuals along a great circle.
A large value here is a warning that the class scores may be inaccurate.
Several things can cause a large RMS, noisy or bad observations, parallax
from various sources, or non-linear object motion.  To help diagnose
RMS problems, a supplementary program, gcr, is included that prints
great circle residuals by observation.

5.  Supplementary program:  gcr

Usage:

   gcr [options] <input filename>

Options:
   -c <rms cutoff>  -- set cutoff, in arc seconds.
   -p <pass file>   -- create file with tracklets with rms < cutoff.
   -f <fail file>   -- create file with tracklets with rms >= cutoff.
   -q               -- quiet.  supress normal output.
   -h               -- print program help.

Program output is

 designation     2d rms
  mjd            ra    dec
--------------------------
     C5O0011       0.01
53581.885750  -0.01  -0.00
53581.895730   0.02   0.00
53581.905660  -0.01  -0.00

In this case, as the low RMS indicated, residuals are excellent.

If any of the options -c -p -f or -q are used, a pass file and a fail file
are created.  Tracklets with RMS below the cutoff are copied to the pass
file.  Tracklets with RMS greater than or equal to the cutoff are copied
to the fail file.


6.  Theory and implementation details

The theory behind the program is explained in detail in a paper
currently in preparation.  (It's been in preparation a long time now.)
Basically though:

1.  For each object, the program computes a motion vector from the
first and last observation, and computes a V magnitude from whatever
photometry is provided.

2.  It then generates a number of orbits that are consistent with
the computed motion, complete with absolute magnitudes consistent with
the computed V magnitude.

3.  Each orbit is located within a binned, or histogram, model of the
solar system.  The model is binned in the four dimensions of q, e, i, and H.
As the bin is determined for each orbit, a flag is set for that bin.
Additionally, each orbit is tested for each configured class and a separate
flag is set, by bin, for each class.

4.  A search algorithm is used to generate orbits covering the entire range
of possible orbits, and tag corresponding possible bins.  As the algorithm
generates variant orbits, it checks if the orbits are yielding new bin
taggings, either in general or of specific orbit classes.  The algorithm
terminates after reaching a point of diminishing returns in finding bins.

5.  The histogram contains object population counts by bin.  For each bin
there is a population of each orbit class, and also a complete population
count.  After orbit search, the sum of complete population of tagged bins
represents the number of possible candidate objects in the solar system.
The population sum of tagged bins of a specified class represents the number
of possible candidates of that class.  The class sum divided by the complete
sum represents the fraction of candidate objects that are of that class.
This fraction is multiplied by 100 and output as the "raw" percentage.

6.  No-ID scores are computed similarly with a parallel histogram.
In it, population counts are not of the expected complete population of the
solar system, but of the expected yet-undiscovered population.  This
population is computed by reducing the modeled complete population by known
discoveries.  As the intended context of the no-ID score is after attempted
object identification, the selected known population is that which is readily
identifiable.  The current criteria used is sky uncertainty < 1' arc.
The uncertainty parameter selected for this comparison is field 24 of
astorb.dat, which is a peak ephemeris uncertainty over a 10 year period.

