Candidate ratings
=================

This package is designed to walk through a database of pulsar survey
detection candidates and assign "ratings" to each one. A "rating" is an
automatically computed number that measures some aspect of the candidate;
for example, one rating might estimate the fraction of its period that the
candidate is on, so that a short spike might have a rating of 0.01 while
a sine wave would have a rating of 0.5. The computed ratings are stored
in the database; the idea is that a human will compose a query to select
candidates whose combination of ratings suggests that they may be real.


Database format
---------------

The database format is currently that used for the GBT 350 MHz drift-scan
survey, which is essentially the same as that used for the PALFA
survey. This database format records certain essential information
- e.g. period and DM - in the database itself, but the detailed
information about each candidate is stored in ".pfd" files external to
the database. The locations of these files are encoded in the database.

Setup/Installation
------------------

You will need to create and populate a database of candidates, probably
using the driftscan/PALFA database scripts. These scripts include a
config file, DRIFT_config.py or PALFA_config.py; you will need to create
a symbolic link from config.py pointing to it.

Running the ratings
-------------------

Use the script apply_all_ratings.py. It takes command-line options,
including --help. The ratings are executed in a framework that
avoids recalculating ratings unless they have changed and that reuses
calculations where possible.

Using the ratings
-----------------

Patrick's Ms. Pulsar Finder is capable of running queries that include
ratings, as is the under-development web-based candidate viewer. MySQL
queries are a little more complicated; the easiest way to construct one
is to start with Ms. Pulsar Finder, and switch to "advanced mode".

Overview of the code
------------------

The basic infrastucture for running ratings is in rating.py. It
establishes a basic object representing a rating of a particular
candidate and handles all database interaction; to calculate a rating
for every candidate in the database, you call the function "run" in the
rating module.

Individual ratings are in various files; each one is implemented
as a subclass of some appropriate parent class. The idea is that
the parent classes handle all the work of extracting .pfd files and
computing profiles and background levels, so that each rating has
direct access to whichever processed data it needs. These classes are
also self-documenting; in particular, they have a version number, a
name, and a long description. The name serves to identify the rating
conceptually, and the version number is used to determine whether a
rating should be recomputed. Queries normally only use the most recent
version of a rating. The long description of a rating should describe
what it calculates and what values you can expect.

If you want to add a rating, the first question is what information
you need: do you simply need the numbers in the database already, or
the folded profile, or the whole datacube of intensity as a function
of frequency, time, and pulse phase? Once that is decided, I recommend
taking a look at the existing ratings to find one that uses the same
input data. Then copy that code, which will be subclassing the correct
class to provide you with the data you need. You'll want to change the
name, version number and description, then you'll want to replace the
implementation with your own. Finally, you'll want to add your rating
to the list in apply_all_ratings.py.

If you want to modify a rating, siply change the implementation and long
description and increase the version number.