
Digest2 Documentation   ----- version 0.10 -----

Contents

1.  Program overview:  purpose, version, availability, sample run
2.  Downloading:  source, other files
3.  Unpacking, building, installing
4.  Usage:  command line syntax
5.  Configuring file locations
6.  File formats
7.  Algorithm outline


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.

This version of the program is written in C.  Source code is available
at http://code.google.com/p/digest2/ and is distributable under an
MIT-style open source license.

Sample run:  For example, here are the discovery observations of a few Amors.

     K11B24L  C2011 01 28.23223 04 18 49.14 +23 19 10.3          20.4 V      G96
     K11B24L  C2011 01 28.24096 04 18 49.53 +23 19 54.9          20.6 V      G96
     K11B24L  C2011 01 28.24963 04 18 49.86 +23 20 39.8          20.5 V      G96
     K11B24M  C2011 01 28.26394 01 15 26.644+12 59 50.61         21.0 w      F51
     K11B24M  C2011 01 28.26864 01 15 27.253+13 00 02.25         20.9 w      F51
     K11B24M  C2011 01 28.27489 01 15 28.067+13 00 17.96         20.9 w      F51
     K11B24M  C2011 01 28.27958 01 15 28.652+13 00 29.58         21.0 w      F51
     K11E15F  C2011 02 25.29299 10 27 43.23 +09 55 54.4          20.5 V      G96
     K11E15F  C2011 02 25.30345 10 27 42.51 +09 55 58.2          20.5 V      G96
     K11E15F  C2011 02 25.31391 10 27 41.76 +09 56 02.2          20.5 V      G96
     K11E15F  C2011 02 25.32441 10 27 41.00 +09 56 05.8          20.6 V      G96

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

Desig.    RMS Int NEO N22 N18 Other Possibilities
K11B24L  0.24 100 100  20   0 (MC <1) (JFC <1)
K11B24M  0.11  99  99  38   0 (MC 1) (JFC <1)
K11E15F  0.17  36  36   8   0 (MC 3)

Only considering the discovery arcs, digest2 predicts that the first two
objects are almost certain to be NEOs.  The last one, with a score of 36
still has a fair chance of being a NEO.  MC 3 means it has a small chance
of having a Mars-crossing, but non-NEO orbit.  The scores do not add to 100
because all possible orbits are not categorized.  The missing fraction
corresponds to orbits that are possible, but do not fall into commonly
recognized orbit classes.  Orbit classes are based on orbital elements
and are either known dynamic populations like "Hungarias" or popular
classifications like "NEO."

The RMS figure is an RMS of residuals in arc seconds of the observations
against a great circle fit.  A high RMS could indicate either bad observations
or significant great circle departure over the observation arc.  It can thus
be used as a quick check that scores are meaningful.  If the RMS is low,
scores are meaningful.  Scores are still meaningful if the RMS is high due
to great circle departure, but digest2 offers no way of distinguishing this
case from one where observations are bad.


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 "tar xvjf digest2.c.0.10.tar.bz2"
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
digest2.h
d2model.h

Type make, and executables should be built and other files created.
This process 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.  There is no extra installation command.
The executable and associated files are built in the current directory
and are usable as they are.  If you would like to manually relocate files,
read below under configuration.


4.  Usage

The main executable is digest2.  Invoking the program without command line
arguments (or with invalid arguments) shows this usage prompt.

Usage: digest2 [options] <obsfile>    score observations in file
       digest2 [options] -            score observations from stdin
       digest2 -h or --help           display help information
       digest2 -v or --version        display version information

Options:
       -c or --config <config-file>
       -m or --model <model-file>
       -o or --obscodes <obscode-file>
       -p or --config-path <path>

The help information lists a quick reference to keywords and orbit classes
allowed in the configuration file.  The configuration file is explained
below under File Formats.


5.  Configuring file locations

The digest2 executable can be copied to another location, a bin directory
for example, and you can access it as you would any other binary executable.

When digest2 runs, it reads observations either from a file or from stdin.
It also reads from two other required data files and an optional configuration
file.  The two required files, digest2.model and digest2.obscodes can
be relocated.  You specify the path and filename of these files with the -o
and -m options.  The file digest2.config is read as a configuration file
but is not required to be present.  As with the the model and obscode files,
a path and filename of a configuration file may be specified with the -c
option.  If so, it is then required to be present.

You can use the -p option to specify a common path to the three files
digest2.model, digest2.obscodes, and digest2.config.  They will be accessed
with their default names but in the specified location.

If you specify -p in combination with -c, -o, or -m, the path specified
with the -c, -o, or -m option takes precedence.  That is, the path specified
with -p is not joined with with a file name specified with -c, -o, or -m.


6. File formats

Observations, whether supplied in a file or through stdin, should contain
observations in the MPC 80 column observation format and nothing else.
The observations should be sorted first by designation and then by time
of observation, and there should be at least two observations of each object.

Digest2.obscodes is a text file containing observatory codes in the standard
MPC format.  Running make as described above downloads the current obscode
list from the MPC web site.  You can edit or update this file as needed.

Digest2.model is a binary file generated by a program called muk, which is
built and run by make.  Muk takes as input a binned version of the PanSTARRS
Synthetic Solar System Model, and a copy of Lowell Observatory's orbit catalog,
astorb.dat.  The binned S3M is distributed with digest2.  Make downloads a
fresh copy of astorb.dat from the Lowell web site.

Digest2.config, the optional configuration file, is a text file with a simple
format.  Empty lines and lines beginning with # are ignored.  Other lines must
contain either a keyword or an orbit class.

Allowable keywords:
   headings
   noheadings
   rms
   norms
   raw
   noid
   poss

Headings and the rms column can be turned off if desired.  Keywords raw
and noid determine the score produced as described below under Theory.
The default is noid.  If both keywords are present, both scores are output.
The keyword poss specifies to output the "Other Possibilities" column.
By default, other possibilities are suppressed if orbit classes are
explicitly specified.

Orbit classes:
   Abbr.  Long Form
   ---    -------------
   Int    MPC interest.
   NEO    NEO(q < 1.3)
   N22    NEO(H <= 22)
   N18    NEO(H <= 18)
   MC     Mars Crosser
   Hun    Hungaria gr.
   Pho    Phocaea group
   MB1    Inner MB
   Pal    Pallas group
   Han    Hansa group
   MB2    Middle MB
   MB3    Outer MB
   Hil    Hilda group
   JTr    Jupiter tr.
   JFC    Jupiter Comet

Listing an orbit class limits scoring to only the listed classes.
Other possibilities are not computed or listed.  Either abbreviations or
long forms may be used.  In any case they must be spelled exactly as
shown.

Example 1:

Int
Neo
N22
N18
poss

This is equivalent to default program behavior without a config file.

Example 2:

# just three
NEO
Hun
JTr

program output is

Desig.    RMS NEO Hun JTr
K11B24L  0.24 100   0   0
K11B24M  0.11  99   0   0
K11E15F  0.17  36   0   0

The program runs considerably faster in this case, as it computes scores for
only these three classes and not all possible classes.

Example 3:

noheadings
norms
N22

output:

K11B24L  20
K11E15F   8
K11B24M  37

This might be useful, for example, in an automated search for larger NEOs.

Known quirks:  The order of designations may not match the input.
The program parallelizes on multi-core CPUs and does not reorder output.
Also, scores may be slightly different from one run to the next.
The program uses randomness in its search of the orbit space.


7.  Algorithm outline

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.

