Skip to main content

The HEASARC Database System

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.

Recommended Names for Table Parameters

abs_mag abs_vmag abstract alt_name app_mag bii bmag
bv_color class count_rate counts cycle dec dec_offset
distance duration end_time error_radius exposure flux flux_N_cm
hmag ic_mag imag jh_color jmag kmag lii
lx major_axis minor_axis morph_type name nh num_obs
obsid off_axis offset pi_fname pi_lname pi_mname pi_name
pm_dec pm_ra position_angle prnb process_date public_date ra
ra_offset radial_velocity redshift ri_color rmag roll_angle semi_major_axis
semi_minor_axis snr source_number source_type spect_type spectral_index status
stellar_age stellar_mass target_id time title ub_color umag
vi_color vmag x_pixel y_pixel

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.

Guidelines for the Naming of Uncertainties, Limit Flags, Other Flags, or References for Other Table Parameters

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.

Guidelines for the Naming of a Logical Grouping of Table Parameters

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.

Guidelines for the Naming of Energy Band-Specific Table Parameters

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.

Guidelines for the Naming of Confidence Level-Specific Table Parameters

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.