HEASARC Conventions for the Naming of Table Parameters
Over the years, the HEASARC has developed some conventions for the naming
of (and the units for) various table columns, and this document attempts to
encapsulate those naming (and units) conventions. Although
virtual parameters can be and are used to
provide generic names for certain types of table parameters or columns, it is
better to just name the table columns in a consistent fashion wherever
possible.
In general, cryptic column names should be avoided if at all possible. It
is better for a column name to be longer but more clearly understood than for
it to be short and cryptic. Column names can be up to 24 characters long.
They should be all lowercase, as some databases do not support mixed-case
column names. Column names should never start with a number.
New tables added to the HEASARC database should use the following common
column names where appropriate:
- name
- The primary designation for the target, object, or source.
- alt_name
- An alternative designation for the target, object, or source. If
there are multple alternative names, then use alt_name,
alt_name_2, alt_name_3, etc. If the original
catalog provides multiple names in a single column, then
alt_names is acceptable, but splitting them up is
preferred.
- ra
- The right ascension of the object. The value stored in the
database should be in J2000 decimal degrees.
- dec
- The declination of the object. The value stored in the
database should be in J2000 decimal degrees.
- lii
- The Galactic longitude of the object. The value stored in the
database should be in decimal degrees.
- bii
- The Galactic latitude of the object. The value stored in the
database should be in decimal degrees.
- error_radius
- The uncertainty in the position of the object, in arcseconds.
- pm_ra
- The proper motion in the right ascension of the object, in
mas/yr.
- pm_dec
- The proper motion in the declination of the object, in mas/yr.
- position_angle
- The position angle of the object, in degrees. For example, the
angle of inclination of the major axis of an elliptically-shaped
source detection.
- roll_angle
- The roll angle of the spacecraft, in degrees.
- class
- The Browse object
classification. The value stored in the
database should be a two-byte integer (int2).
- source_number
- A sequential integer which uniquely identifies each source in a
catalog.
- source_type
- A character string which identifies the type of source.
- spect_type
- A character string which identifies the spectral type of a
source.
- morph_type
- A character string which identifies the morphology of a source.
- time
- The date and time (in UTC) of the event, usually the start of an
observation in an observation catalog. The value stored in the
database should be in Modified Julian Date (MJD).
- end_time
- The date and time (in UTC) of the end of the event, usually when
the observation was completed in an observation catalog. The value
stored in the database should be in Modified Julian Date (MJD).
- exposure
- The length of time, in seconds, that a detector was exposed.
- duration
- The literal length of time from the start of an observation to the
end of the observation, in seconds. This is usually different from
the exposure, but that may not always be true. If they are the same
thing, then exposure is the preferred name.
- counts
- The number of photons that were detected.
- count_rate
- The counts per second that were measured.
- flux
- The energy flux, in erg/cm2/s. Fluxes in other units
should always be converted to erg/cm2/s wherever
possible. Some fluxes are occasionally given in
photons/cm2/s, however.
- flux_N_cm
- The flux density, in mJy, where N is the wavelength in centimeters.
Flux densities in other units should always be converted to mJy.
- lx
- The X-ray luminosity of the source, in erg/s.
- obsid
- A character string or number that uniquely identifies an
observation for a given mission or observatory.
- redshift
- The redshift of the object.
- radial_velocity
- The radial velocity of the object, in km/s.
- vmag
- The V magnitude of the object.
- bmag
- The B magnitude of the object.
- hmag
- The H magnitude of the object.
- imag
- The i magnitude of the object.
- ic_mag
- The Cousins I magnitude of the object.
- jmag
- The J magnitude of the object.
- kmag
- The K magnitude of the object.
- rmag
- The r magnitude of the object.
- umag
- The u magnitude of the object.
- bv_color
- The B-V color index of the object.
- ub_color
- The U-B color index of the object.
- jh_color
- The J-H color index of the object. Reference: Lada et al.
(1996AJ....111.1964L).
- ri_color
- The Cousins R-I color index of the object.
- vi_color
- The Cousins V-I color index of the object.
- app_mag
- The apparent magnitude of the object.
- abs_mag
- The absolute magnitude of the object.
- abs_vmag
- The absolute V magnitude of the object.
- spectral_index
- The spectral index of an object's emission.
- snr
- The signal-to-noise ratio for a given detection.
- stellar_age
- The age of the source in years.
- stellar_mass
- The mass of the source in Solar mass units.
- nh
- The absorbing hydrogen-I column density in the line of sight to the
source or target, in cm-2.
- major_axis
- The major axis of an elliptically-shaped source detection, usually in
arcminutes.
- minor_axis
- The minor axis of an elliptically-shaped source detection, usually in
arcminutes.
- semi_major_axis
- The semi-major axis of an elliptically-shaped source detection,
usually in arcminutes.
- semi_minor_axis
- The semi-minor axis of an elliptically-shaped source detection,
usually in arcminutes.
- distance
- The (usually) heliocentric distance to an object. The units are
usually pc (parsec) for intragalactic distances and Mpc
for extragalactic distances.
- x_pixel, y_pixel
- The X and Y pixel coordinates of the detected source in an image.
- offset, ra_offset, dec_offset
- The angle between the position of an object and (often) its
equivalent position at another wavelength (e.g., the xray cf.
optical position of the object) or (sometimes) its position as
measured by another telescope (ROSAT cf. Chandra position). In many
cases this offset is given as separate right ascension and declination
offsets, hence ra_offset and dec_offset. These
offsets tend to be small, and the preferred units are arcseconds.
- off_axis
- The angle between the position of the object and the pointing
direction of the observation/instrument in which the source was
measured. The units should always be in arcminutes.
- cycle
- The proposal cycle (or AO) from which an observation originated.
- prnb
- The proposal number unique to a given mission or observatory from
which an observation originated. Cryptic, but historically common
in the HEASARC database.
- target_id
- A character string or number that uniquely identifies the target of an
observation. This is usually some concatenation of proposal number
and target number within the proposal.
- title
- The title of the proposal from which an observation originated.
- pi_lname, pi_fname, pi_mname
- The last name, first name, and middle name (or initial) of the
principal investigator for a proposal or observation.
- pi_name
- In some cases, missions may provide principal investigator names in
an aggregate fashion that cannot be parsed into separate first,
middle, and last names fields. This is not preferable and should be
avoided wherever possible.
- abstract
- The abstract of the proposal from which an observation
originated.
- num_obs
- The number of observations of the target or source.
- status
- The status of the observation, usually one of the following
character strings (with some minor variation by mission/observatory):
- accepted
- scheduled
- observed
- processed
- archived
- process_date
- The date that the observation data was processed. This value does
not usually have a time (in UTC) associated with it, but it can.
The value stored in the database should be in Modified Julian Date
(MJD), usually as an integer, unless there is a time in which case
a float8 should be used.
- public_date
- The date that the observation data is made available for anyone to
access. This value does not usually have a time (in UTC) associated
with it. The value stored in the database should be in Modified
Julian Date (MJD), as an integer.
The uncertainty for a given parameter should be named as follows: the same
as the column with which it is associated plus the suffix _error.
For example, an uncertainty in the count rate should be named
count_rate_error.
Asymmetric uncertainties should use the suffixes _pos_err and
_neg_err.
A flag which specifies whether a given parameter is an upper limit or
lower limit should be named as follows: the same as the column with which it
is associated plus the suffix _limit. For example, the limit flag
for the count rate should be named count_rate_limit. For many years,
however, the HEASARC would routinely use a prefix (limit_) instead
of a suffix, and the prefix form is very common.
A miscellaneous flag which indicates something about a given parameter
value should be named as follows: the same as the column with which it is
associated plus the suffix _flag. For example, a column containing a
flag (e.g., ":") which indicates that a given redshift value is uncertain,
should be named redshift_flag.
A character field which specifies a reference code for where a given
parameter value originated should named as follows: the prefix ref_
plus the column name with which it is associated. For example, the reference
for the redshift should be named ref_redshift.
If the field contains values which are the logarithms of some property,
then the field name should be prefixed with log_. For example, the
logarithm of the X-ray luminosity should be named log_lx.
If a table has multiple columns that are related in some way (such as they
originate from some catalog or pertain to a specific part of the
electromagnetic spectrum), use a common prefix. Among other reasons, using a
common prefix (i.e., instead of a suffix) allows for the columns to be
grouped together when alphabetically sorted.
For example, a table might have the following parameters:
twomass_name, twomass_ra, twomass_dec, etc.,
indicating that the values for these parameters come from the 2MASS catalog.
(Also, notice that, since parameter names cannot start with a number, the "2"
in "2MASS" is spelled out to get the "twomass_" prefix.)
Another example: An X-ray catalog that has columns pertaining to an
optical counterpart to the X-ray source might have the parameters
optical_name, optical_ra, optical_dec,
optical_error_radius, etc., indicating that these parameters refer
to the optical counterpart.
If a table has multiple columns of the same type for different energy
bands, the HEASARC will use the following X-ray band prefixes to specify the
energy band:
- hb_: indicates the hard energy band (e.g., 0.2 to 2 keV)
- sb_: indicates the soft energy band (e.g., 2 to 12 keV)
- mb_: indicates some "medium" energy band between the hard and
soft energy bands or possibly a subrange of the soft energy band
(e.g., 2 to 5 keV), where applicable
- fb_: indicates the total (or full) energy band (e.g., 0.2 to 12 keV)
For example, a table might have hb_flux, mb_flux,
sb_flux, and fb_flux parameters.
Alternatively, for when it is desirable to be explicit about the energy
range for some parameter, append the suffix
_low_high_unit. For example, the flux in the
energy range 0.3 to 1 GeV might be named flux_0p3_1_gev. Note that
the decimal point has been turned into a "p" (short for "point") here. The
_unit portion may be left off if the length of the parameter
name (or related parameter names, such as the uncertainty) otherwise will
exceed the maximum allowed length.
If (and only if) a table has multiple parameters of the same type
for different confidence levels, the HEASARC will use the suffix
_ConfidenceLevel to specify the confidence level. For
example, a table might have error_radius_68 and
error_radius_90 parameters for the 68% confidence level and 90%
confidence level positional uncertainty parameters.
Documentation prepared by the
HEASARC Database Group
HEASARC Home |
Observatories |
Archive |
Calibration |
Software |
Tools |
Students/Teachers/Public
Last modified: Thursday, 04-Nov-2021 18:05:20 EDT
The Astrophysics Science Division (ASD) at NASA's Goddard Space Flight Center (GSFC) seeks a creative, innovative individual with strong teamwork and leadership skills to serve as Director of the High Energy Astrophysics Science Archive Research Center (HEASARC). This will be a permanent civil servant position. + Learn more.
|