NAME:
dbphot
PURPOSE:
Add or update observation entries in the photometry data base.
DESCRIPTION:
Opens data table in the phot data base and adds observations.
Normally some or all of the observations already in the database for the
same RefID will be deleted. This 'cleaning', controlled by keyword,
can cover all of the RefID, or all observations for the RefID matching the
input set by a) object name and filter or (b) jd. Dbphot can also be used
to delete entries only.
CATEGORY:
Photometry
CALLING SEQUENCE:
dbphot, refid,obj,jdobs,filstr,mag,magerr
INPUTS:
refid - String (up to 20 chars) which identifies an observing run.
It corresponds to the value of the RefID field in the db table.
All data added to or removed from the database in a call will
pertain to this id, which must be a non-null string.
obj - String or string array giving the object(s) names. A null string
will engender a NULL value for the data base ObjName field.
An object name may not exceed 20 characters in length.
jdobs - JD time of observation or array of times, which is either a string
of Gregorian date and time suitable for jdparse, or a double JD
number. Jd values less than or equal to zero, or empty string,
will engender a NULL value for the data base jd field.
Note: null jd often validly applies to catalog entries.
filstr - String (up to 10 chars) or string array giving the filter(s) names.
mag - Array of reduced magnitudes.
magerr - Array of reduced magnitude errors (one sigma).
OPTIONAL INPUT PARAMETERS:
KEYWORD INPUT PARAMETERS:
BAD - Array of bad flags, integers, by default all zero.
CLEANBYJD - Flag, if set, all previous entries in the data base
with this RefID and an exact match to any of the
jdobs input values will be deleted.
If set, CLEANBYOBJFIL, NOCLEAN and CLEANBYREFID must be
unset.
CLEANBYOBJFIL - Flag, if set, all previous entries in the data base
with this RefID and an exact match to any of the
filter, objname and color input value combinations
will be deleted. If COLOR is not specified then the match
is to object, filter and the color '-'. If this keyword is
set, CLEANBYJD, NOCLEAN and CLEANBYREFID must be unset.
CLEANBYREFID - Flag, if set, all previous entries in the data base
with this RefID will be deleted. If set, CLEANBYJD, NOCLEAN
and CLEANBYOBJFIL must be unset.
CLEANONLY - Flag, if set, only the removal of previous entries as depicted
above will be done and the input entries will not be added.
It is still necessary to specify one or more input values
and all the usual restrictions will be in effect.
COLOR - String, represents color against which the magnitudes were
reduced (if applicable). This is a scalar applied to all
values, and placed in the Color column of the data table.
Normally it is of the form (filter1-filter2), like 'B-V'.
If unspecified, or a null string is used, it will be
defaulted to '-'.
DATABASE - String, name of photometry MYSQL database, by default 'phot'
If keyword TABLE specifies a database via the '.' notation,
DATABASE is ignored.
DECL - Scalar or array of double precision dec values in radians, or
strings in sexagesimal format suitable for decparse.
If not specified, or empty string, a NULL
value will be used for the ra and decl columns in database.
NOCLEAN - Flag, if set, no previous values will be cleaned from the db.
If set, CLEANBYJD, CLEANBYOBJFIL and CLEANBYREFID must be
unset.
RA - Scalar or array of double precision ra values in radians, or
strings in sexagesimal format suitable for raparse.
If not specified, or empty string or 0.0, a NULL
value will be used for the ra and decl columns in database.
SILENT - Flag, if set, dbphot prints no non-error output.
It is ignored if TEST set.
TABLE - String, name of photometry table, by default 'data' If the
string is of the form 'a.b' then a is taken to be the
name of the database and b is the tablename. Note that
if neither TABLE nor DATABASE is specified the photometry
table is located at 'phot.data'
TEST - Flag, if set, the data base will not change, but the cmds that
would have been generated will be printed. It queries the
db to list which existing entries would have been removed.
VERBOSE - Flag, if set prints verbose debug output- in particular, what
TEST prints, but does perform all the database operations.
OUTPUTS:
KEYWORD OUTPUT PARAMETERS:
NREMOV - Set to number of previous data rows removed, or, if TEST set,
would be removed.
COMMON BLOCKS:
SIDE EFFECTS:
DBPHOT removes all existing db entries for refid, instrument, objects,
filters, and jd according to the *CLEAN* flags.
As many data base entries will be added as there are
elements in the mag array unless CLEANONLY is specified.
Specifying both CLEANONLY and NOCLEAN is a no-op but can be
useful for validating an input set to DBPHOT.
RESTRICTIONS:
The number of elements in the mag and magerr arrays must
be equal. The number of elements in the obj, jdobs, filstr, bad
and RA,DECL (if specified)
arrays must also be the same. However, if a scalar is specified
for jdobs, filstr, obj, bad, RA or DECL, this is a legal case and the
value is replicated for all entries. It is legal for RA and DECL to be
unspecified, or obj to specified as a null string, however, for each
observation, there must be a specified value for either obj or RA,DECL.
It is legal to specify both obj and ra,decl for an observation but it
is not ordinarily done. If one of ra and decl is specified for an
observatory, they will be both posted as NULL.
If bad is unspecified, a bad flag value of 0 is replicated for all entries.
One and only one of the flags NOCLEAN, CLEANBYREFID, CLEANBYOBJFIL and
CLEANBYJD must be specified.
CLEANBYJD requires that all values of jdobs be non-null.
CLEANBYOBJFIL requires that all values of obj and filstr be non-null.
Be aware that if you are following the practice of removing all bad
data from your input prior to calling DBPHOT (and thus not using BAD),
you will need to call DBPHOT with /CLEANONLY if and when all your data
are marked bad to make sure the previous db entries are scrubbed.
This routine only works with the photometry 'data' table- the reference
table is not modified or examined.
PROCEDURE:
MODIFICATION HISTORY:
2006/08/10, Written by Peter L. Collins, Lowell Observatory
2006/09/26, PLC, add support and keyword for INSTRUMENT field in
database- phot.data.
2006/12/05, PLC, add support for RefID field in the data table,
which replaces the former Rundate and Instrument
fields. Also RA and DEC are available as keyword
inputs. Richer set of supported formats, defaults
and validity checks.
2006/12/09, PLC, test for inaccessible data base via openmysql and
length checking on RefID, obj, and filstr.
2006/12/27, PLC, rationalization of data base keywords, and recoding
of VERBOSE keyword.
2007/01/12, PLC, add CLEANONLY keyword.
2007/01/23, PLC, add COLOR keyword (with change to database table to add
Color column). Tweak add/delete prints to reflect clean
flags.