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

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/cm²/s. Fluxes in other units should always be converted to erg/cm²/s wherever possible. Some fluxes are occasionally given in photons/cm²/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.