Page tree
Skip to end of metadata
Go to start of metadata

This section provides a more complete description of EPN-TAP parameters, with meaning and usage. 

Definition, types, UCDs, and a short definition are provided here (which is the main source): EPN-TAP V2.0 parameters

Although additional, service-specific parameters can be used, care must be taken to have no duplication. In general, parameters must appear only once in a service.

Mandatory parameters

1- Granule references

These 3 keywords must always be informed. If granule grouping is not relevant, use a single value for granule_gid (and obs_id can be identical to granule_uid).

granule_uid

Unique granule ID in the data service.

There can be only one file associated to a granule (plus possibly a thumbnail for quick-look purpose in a search interface).

obs_id

Associates granules derived from the same data (e.g. various representations / processing levels). May be the ID of original observation.

granule_gid

Associates granules of same type (e.g. same map projection, or geometry data products) - think of it as a simple and convenient way to group or differentiate types of data.

When several files relate to the same data, this parameter helps distinguishing them: this will allow the user to select the type of data of interest. E. g., a service may provide links to calibrated images, plus raw data and ancillary information for every granule; these will share the same obs_id, but will have different granule_gid.

2- Data Description

dataproduct_type

The dataproduct_type parameter describes the high level scientific organization of the data product linked by the access_url parameter, or directly included in the table (in which case the value is 'ci' for catalogue_item). EPNCore currently defines several types listed below. The data provider must select the type most adapted to his data. In complex situations (e. g., when a file contains several data products), several types can be used to describe the same granule by using a hash-list — although using several granules to describe the file content may be a better solution.  

In EPN-TAP these types are identified by a 2-characters ID, so that multivalued queries are unambiguous. Possible IDs are listed below with their meaning:

  • im (= image): scalar field with two spatial axes, or association of several such fields, e.g., images with multiple color planes, from multichannel or filter cameras. Preview images (e.g. map with axis and caption) also belong here. Conversely, vectorial 2D fields are described as spatial_vector (see below).
  • ma (= map): scalar field / rasters with two spatial axes covering a large area and projected either on the sky or on a planetary body, associated to spatial_coordinate_description and map_projection parameters (with a short enumerated list of possible values); each pixel is associated to 2D coordinates. This is mostly intended to identify radiometrically calibrated and orthorectified images with complete coverage that can be used as reference basemaps. 
  • sp (= spectrum): measurements organized primarily along a spectral axis, e.g., radiance spectra. This includes spectral aggregates (series of related spectral segments with non-connected spectral ranges, e.g., from several channels of the same instrument, various orders from an échelle spectrometer, composite spectra, etc).
  • ds (= dynamic_spectrum): consecutive spectral measurements through time, organized primarily as a time series. This typically implies successive spectra of the same target / field of view.
  • sc (= spectral_cube): sets of consecutive spectral measurements with 1 or 2D spatial coverage, e.g., imaging spectroscopy. The choice between image and spectral_cube is dictated by the characteristics of the instrument (which dimension is most resolved & which dimensions are acquired simultaneously). The choice between dynamic_spectrum and spectral_cube is related to the uniformity of the field of view and by practices in the science field.
  • pr (= profile): scalar or vectorial measurements along 1 spatial dimension, e.g., atmospheric profiles, atmospheric paths, sub-surface profiles, traverses…
  • vo (= volume): measurements with 3 spatial dimensions, e.g., internal or atmospheric structures, including shells/shape models (3D surfaces).
  • mo (= movie): sets of chronological 2D spatial measurements (consecutive images)
  • cu (= cube): multidimensional data with 3 or more axes, e.g., all that is not described by other 3D data types such as spectral cube or volume. This is intended to accommodate unusual data with multiple dimensions. This can be used for 3D ancillary data associated to spectral cubes, e.g., providing the coordinates or illumination angles for each spectrum.
  • ts (= time_series): measurements organized primarily as a function of time (with exception of dynamical spectra and movies, i.e. usually a scalar quantity). Typical examples of time series include space-borne dust detector measurements, daily or seasonal curves measured at a given location (e.g. a lander), and light curves.
  • ca (= catalogue): applies to a granule providing a catalogue of object parameters, a list of features, a table of granules in another TAP service, a list of events... The result metadata table of a service can be considered as a catalogue. Catalogues can be provided as VOtable (possibly containing multiple tables, although this is not supported by SAMP). It is good practice to describe the type of data included in the catalogue using a hash-list (e.g., a table of spectra should be described by ca#sp, so that it will respond to a query for spectra).
  • ci (= catalogue_item): applies when the service itself provides a catalogue with entries described as individual granules, in particular when there is no associated file (e. g., a list of asteroid properties or spectral lines). Catalogue_item can be limited to scalar quantities (including strings), and possibly to a single element. This organization allows the user to search inside the catalogue from the TAP query interface.
  • sv (= spatial vector): vector information associated to localization, such as a spatial footprints, a GIS-related element, etc —  e. g. a klm or geojson file (STC-S strings are provided though the s_region parameter, though). This includes maps of vectors, e.g., wind maps.
  • ev (= event): introduces individual VOevents formatted according to IVOA standard (or possibly events with other formatting, TBC)


Example TAP queries:

select * from epn_core 
where dataproduct_type like '%im%'

or 

select * from epn_core 
where ivo_hashlist_has(lower(dataproduct_type), 'im') =1

will return only image data (the second syntax handles lists of values in a robust way).

The measurement_type parameter defines the physical quantities contained in the data, using UCDs. It relates to the reported quantity, not to the type of experiment. Therefore only UCD related to physical quantities can be used; e.g., phys.absorption;em.opt.I is eligible, while stellar_occultation is not.

The "UCD1+" list from IVOA must be used as a reference. New UCDs relevant for Solar System studies are regularly discussed, therefore recent extensions of this list must be also considered (i.e., at time of writing: http://www.ivoa.net/documents/UCD1+/20180527/index.html, and Requests For Modifications). 

Whenever several quantities are comprised in the data, the measurement_type parameter must describe all these quantities, using multiple UCDs in a hash-list. 

Examples:

  • For images in general (i.e., actual measurements with a camera), the relevant UCD is obs.image (or obs.image;stat.uncalib if not calibrated).
  • For spectra: phot.radiance describes radiance, phys.reflectance stands for reflectance factor (= I/F), and phot.flux.density for a flux vector (irradiance)The associated spectral vector is described by UCDs em.wl, em.freq or em.energy, and the related error has the form stat.error;phys.reflectance (for I/F).
  • Quantities derived from modeling/simulation are described by the regular UCD with ";meta.modelled" appended. 

The processing_level parameter is intended to provide the user with a quick evaluation of data readiness level. When the original dataset uses a specific encoding of processing levels, this one should be used to meet the expectations of historical users; e. g., a service deriving from a telescopic archive will preferably use the processing levels from this archive. When no practice exists for a dataset, EPN-TAP uses a simplified version of CODMAC / PDS3 levels as described below.

Several classifications are in use in different contexts, as summarized in the table below. EPNCore uses the CODMAC / PDS3 levels but removes the intermediate calibration levels; this is equivalent to using the simplified PDS4 levels and maintaining a separated level for ancillary data. "Partially calibrated" datasets are in general considered as not calibrated, but this evaluation is up to the data provider, depending on context. "Ancillary" data include all extra information documenting the measurements, in particular coordinates or geometry files. Several processing levels can be included in the same service (in particular calibrated and ancillary data, but also raw data). When mixed in the same file, several values may be provided as a hash-list.

Most EPN_TAP data services are expected to include Calibrated or Derived data. 

EPN-TAP

CODMAC

PSA

NASA

PDS3

PDS4

ObsTAP

Description


1

1
(raw)

(0?)


UDR

Telemetry

0

Unprocessed Data Record (low-level encoding, e.g. telemetry from a spacecraft instrument. Normally available only to the original team)

2

2
(edited)

1

0

EDR

Raw

1

Experiment Data Record (often referred to as "raw data": decommutated, but still affected by instrumental effects)

3

3
(calibrated)

2

1A

RDR

Calibrated

2

Reduced Data Record ("calibrated" in physical units)

5

4
(resampled)


1B

REFDR

Derived

± 3

Reformatted Data Record (mosaics or composite of several observing sessions, involving some level of data fusion)

5

5
(derived)

3

2-5

DDR

Derived

± 4

Derived Data Record (result of data analysis, directly usable by other communities with no further processing)

6

6
(ancillary)



ANCDR

Derived


Ancillary Data Record (extra data specifically supporting a data set, such as coordinates, geometry…) 

Notes:

  • This table is a compilation of information from PSA, PDS4, & ObsCore documents
  • The PDS3 column corresponds to the PDS3/PSA PRODUCT_TYPE keyword
  • Descriptions are extracted from PSA documentation, with comments.

3- Target description

The target_name parameter identifies a target by name or ID. The target may be any Solar System body, exoplanet, planetary sample, or meteorite, plus in some cases astronomical objects or spacecraft. Any other feature (craters, regions, atmospheric layers…) must be named using the optional feature_name parameter (see 4.3.3). This parameter can be multivalued only to describe several targets related to a granule (e.g. with events). Alternative names of the same target must not be listed here, but may be provided through the optional alt_target_name parameter. 

The best practice is to use the official designation of the target as defined by IAU. This parameter is case sensitive (mixing lower/upper cases) and all values must use the standard spelling and case; unusual characters (such as intermediate spaces) are allowed, except quotes (preferably changed to _ , which is the single-character wildcard in TAP queries). Data providers must be aware that services which do not use the IAU designations might not be accessible by the clients. Conversely, users must be aware that some services containing data of interest might not be visible, if they do not use the recommended IAU nomenclature for planetary bodies. The SSODnet name resolver from IMCCE may help data providers (as well as users) to handle multiple denominations; it is available from the VESPA portal to support queries.

Concerning celestial objects (at fixed position, i. e., stars, galaxies…) the name should be identifiable through Simbad (http://simbad.u-strasbg.fr/simbad/).

Other best practices are listed below:

Example TAP query:

select * from epn_core 
where target_name like 'Ceres' or target_name like 'Vesta' 
and target_type like 'dwarf_planet' or target_class like 'asteroid'

Will return data only from 1 Ceres or 4 Vesta. Complex queries may also include parentheses.


Example:

1P is the official IAU designation for comet Halley

The target_class parameter identifies the type of the target. Solar System bodies are defined without ambiguity by the couple target_class and target_name; in other cases, targets may have no proper name (i.e., samples).  This parameter must be informed whenever a value for target_name is provided. The possible values for target_class are:

  • asteroid
  • dwarf_planet
  • planet
  • satellite
  • comet
  • exoplanet
  • interplanetary_medium
  • sample
  • sky
  • spacecraft
  • spacejunk
  • star
  • calibration

Usage:

  • Any target has a unique target class.
  • "interplanetary_medium" refers in particular to interplanetary dust observed in context (not to samples)
  • "sample" refers to lunar or planetary samples, to meteorites, but also to terrestrial samples, e.g., in laboratory studies.
  • "satellite" stands for natural satellites only - artificial satellites are handled though spacecraft or spacejunk.
  • "star" is used typically for calibration targets, and for the Sun.
  • "sky" should be used for all other celestial bodies, usually referred to by their sky coordinates. It also includes the Interstellar Medium.
  • "calibration" is used for observations only related to instrument or signal calibration, including dark current, flat field, reference sample (in lab), etc (use of "calibration" with planetary bodies is left to data providers).
  • planetary rings are not considered as a target class, but appear in target_region with their planet indicated in target_name.

Comment:

All "Types" of objects used by the SsODNet resolver are included in the EPNCore list: "asteroid", "spacecraft", "comet", "exoplanet", "spacejunk", "satellite", "planet", "dwarf planet", "star".
Additional EPNCore classes are: "interplanetary_medium", "sample", "sky", "
calibration".

4- Axes

EPN-TAP describes the data location along 8 main axes: time, spectral, spatial (3 coordinates), and viewing geometry (3 angles). 

Locations along the time/space/spectral axes are described with a range and a resolution and/or sampling step. 

Each quantity is a set of 2 parameters providing min and max values (except spatial_frame_type and s_region). They must both be present with the same value when min = max.

The time parameters are always provided in UTC and formatted in Julian Days (expressed in double precision). EPNCore uses standard JD to avoid ambiguity with time origin (as opposed to ObsCore which uses Modified JD). The use of double precision floats insures an accuracy on the order of 1 ms, which is considered sufficient for search purposes (the initial accuracy is preserved in the data itself).  The client front-end may expose times formatted in a more convenient way for human users.

Examples TAP queries:

  • Search data described by a time range:
select * from epn_core where time_min > '2455197.5' and time_max < '2455927.5'
  • Search data described by a start time parameter
select * from epn_core where time_min between '2455197.5' and '2455927.5'

Time range is by default provided in the observer frame (i.e., at the observer location), which is almost always the native time in the data. For instance, space-borne observations are usually documented with spacecraft on-board time, which is expected here (provided as JD, not as on-board clock timing). For other cases, the location where time is measured must be provided though the time_origin parameter.

To support space-borne vs ground-based campaigns, multiple spacecraft observations, or survey of periodic events, measurement times need to be corrected for light path. Whenever comparisons are potentially involved, the use of the target_time_min and target_time_max parameters is recommended in addition to time_min and time_max to simplify this kind of comparison.

Non-compulsory parameters may be used to accommodate additional, specially formatted time scales such as native on-board time for space borne observations. The information of the time_min and time_max parameters is however greatly recommended for all observations, as it is used by default to search datasets.

These parameters provide the sampling step in seconds for measurements of dynamical phenomena, and for computations. This is the time between 2 successive measurements or data, which is mostly relevant when the measurements are regularly spaced. This may also be used as an input parameter, e.g., for ephemeris computations. This parameter is intended to allow the user to search for time-resolved observations of dynamic phenomena, but can also accommodate the "repetition time" for several types of instruments.

These parameters correspond to the integration time (or exposure time) of measurements in seconds. They provide an estimate of the time resolution for dynamical phenomena, as well as an indication of relative S/N ratio inside a given dataset. This time is usually shorter than the time_sampling_step if both are present. It provides the overall integration time, i.e. individual exposure time x number of summed frames when relevant. 

The spectral_range parameters define the upper and lower bounds of the spectral domain of the data. This quantity is conventionally expressed on a frequency scale in Hertz, although the client front-end may propose conversions to other units/scales. The spectral range and associated parameters only apply to electromagnetic waves. See the optional parameters particle_spectral_* for particle energy or mass detection.

Since this is the standard parameter to identify a spectral range, it is recommended to fill it even for images obtained through a filter (central wvl ± FWHM/2, or even central wvl in both parameters, may be enough for search purposes). The svo Filter Profile Service (http://svo2.cab.inta-csic.es/theory/fps3/) provides responses for many instrument filters; bandwidths can be retrieved easily with a python library: https://github.com/hover2pi/svo_filters


Conversions
with c = 2.99792458E8 (m/s)
spectral_range_min  = c*E6 /spectral_range_max_micron
spectral_range_max  = c*E6 /spectral_range_min_micron
(notice the inversion)

These parameters are most relevant for radio observations (long wavelengths / low frequencies) with regular sampling. They can also help distinguish between Nyqvist and sub-Nyqvist sampling rates (together with resolution).


Conversions
with c = 2.99792458E8 (m/s)
df = c*1E6 dlam / lam^2 (from wavelength, with lam and dlam in micron)
df = c*1E3 dlam / lam^2 (same if dlam provided in nm)
df = c/1E-2 du (from wavenumber u in cm-1)

The spectral_resolution parameters actually provide the (dimensionless) resolving power: | lambda / Delta(lambda) | = | fq / Delta(fq) |  

These parameters are mostly intended to provide an order of magnitude, e.g., to distinguish between Fourier spectrometers, grating spectrometers or filter cameras, or between observations related to surfaces or atmospheres. This is often most relevant for optical/infrared observations (short wavelengths / high frequencies).


Conversion
spectral_resolution_min  = abs( spectral_range_min_micron / max(DeltaLambda) )
spectral_resolution_max  = abs( spectral_range_max_micron / min(DeltaLambda) )

c1 (min/max)

c2 (min/max)

c3 (min/max)

These parameters provide up to three spatial coordinates of the measured target. The coordinates depend on the spatial_frame_type parameter defined below. All services must handle three spatial coordinates, even if the third one is always set to NULL. In body-fixed coordinates c1 is longitude, always counted eastward; c1min is then the westernmost longitude and c1max the easternmost one (so as accommodate 0 meridian crossing). Note that the c3 parameter is related to the observed area; the target distance (e. g., geocentric distance for ground based observations, or spacecraft distance) is introduced by the optional parameters "earth_distance" or "target_distance".

In order to make uniform requests possible, spatial coordinates provided in the epn_core table must be standardized. However, they can be provided in several systems types, as defined by the spatial_frame_type parameter.  The native coordinate system used with the dataset can be described by parameters spatial_coordinate_description and spatial_origin. This is intended to provide this information prior to loading the data, especially when several coordinate systems are available in the same service. Descriptions for EPN-TAP are provided in a separate document (draft here: Planetary Coordinate Systems). Secondary coordinates can be introduced using additional parameters, e.g., c1 and c2 ranges identify the visible region of a planetary disk, while extra RA / Dec parameters provide location on the sky at this moment, and subobserver_longitude_min/max and subobserver_latitude_min/max provide the coordinates of the disk center.

c1_resol (min/max)

c2_resol (min/max)

c3_resol (min/max)

These parameters provide a simple estimate of resolution in the same frame/units as c1/c2/c3. For instance, if spatial_frame_type = 'celestial' it can accommodate the FWHM of the PFS on the sky (in degrees). The client front-end may propose more appropriate units to the user, depending on context (e.g., angular resolution in mas, distance in m…).

Provides the "flavor" of the coordinate system, which defines the nature of the spatial coordinates (c1,c2,c3) in the epn_core table and queries, and the way they are defined. A value is always required (use "none" if not applicable, although "body" is found in older services and may be OK). This may be different from the coordinate system associated to / included in the data themselves. The frame center can be specified using the spatial_origin parameter in case of ambiguity. The possible types are described below:

  • celestial: 2D angles on the sky, i. e., right ascension c1 and declination c2 + possibly heliocentric distance in c3 (in au) – although this is a special case of spherical frame, the order and conventions are different. Assumes ICRS coordinates; right ascension is provided in degrees. For ground-based observations, Earth distance may be provided in the earth_distance parameter (rather than c3).
  • body: 2D angles in body-fixed frame: longitude c1 and latitude c2 + possibly altitude as c3. 
    A planetocentric system with eastward longitudes in the range (0,360)° is required for service interoperability. Current IAU frame is assumed, in particular for definition of the prime meridian. IAU 2009 planetocentric convention applies, in particular eastward longitudes and a north pole located on the north side of the invariant plane of the Solar System for planets and satellites.  
    Parameter c3 is measured above the reference ellipsoid, and can be <0 for interiors. Two other parameters are available to provide other vertical scales if needed (radial_distance and altitude_fromshape).
    Planetocentric rotating frames are defined as spherical (rather than body).
  • cartesian: (x,y,z) as (c1,c2,c3). This includes spatial coordinates given in km (TBC: was in pixels in a previous version). 
  • spherical: (r, theta, phi) as (c1,c2,c3), as defined in ISO standard 80000-2:2009; r = radius; theta = zenith angle/colatitude/inclination; phi = azimuth (E longitude). Angles are provided in degrees. When related to the sky or tied to a solid body, "celestial" (with RA/Dec) or "body" (with longitude/latitude) frames must be used instead.
  • cylindrical: (r, theta, z) as (c1,c2,c3); r = radius in km; theta = azimuth; z = height in km. The angle is provided in degrees.
  • none: to be used when no spatial frame is defined for the dataset. This is intended to prevent useless searches when space coordinates are not defined (a non-zero value is required by the mixin in DaCHS).
  • healpix: usage TBC, will conform to IVOA decision.

This parameter, although related to the specific coordinate system in use, is mostly intended to identify the nature of the coordinates handled by the service (e. g., angles versus distances). This parameter is provided as a column of the epn_core table, to ensure it can be queried through the basic TAP mechanism. Although it will in general remain constant along the table for simple services, this parameter can vary from granule to granule and a value must therefore be provided in any query that includes spatial coordinates. Whenever additional coordinates are provided, they must be stored in extra columns of the table. If several different frames are mixed to provide the main coordinates, the use of different granule_gid may help clarify the situation. At any rate, easy access to the data must be considered during the design of the service. 

The incidence angle parameters define the upper and lower bounds of the incidence angle range in the data (also known as Solar Zenith Angle). This is always indicated in decimal degrees, and may range from 0 to 90° (with 0° indicating the normal to the surface). Incidence and emergence angles may be counted relative to the normal of the ellipsoid model, or to the local normal (e. g., using a 3D shape model). In case the two systems are included in the data, these keywords introduce the values relative to the ellipsoid (local values may be provided through non-compulsory parameters).

The emergence angle parameters define the upper and lower bounds of the emergence angle range in the data (a.k.a. viewing angle). This is always indicated in decimal degrees, and may range from 0 to 90° (with 0° indicating the normal to the surface). Incidence and emergence angles may be counted relative to the normal of the ellipsoid model, or to the local normal (e. g., using a 3D shape model). In case the two systems are included in the data, these keywords introduce the values relative to the ellipsoid (local values may be provided through non-compulsory parameters).

The phase angle parameters define the upper and lower bounds of the phase angle range in the data (i.e., scattering angle - 180°, or light source-target-observer angle). It is always indicated in decimal degrees, and may range from -180 to 180° (with 0° corresponding to opposition, i. e., light source in the back of the observer). Negative values may refer, e. g., to geometry before opposition, depending on context. Phase (phi), incidence i and emergence e are partly related:

abs(i - e) < phi < i + e

If the azimuth angle a is available instead of the phase angle, the latter can be derived from knowledge of the three angles:

cos phi = cos i cos e + cos a sin i sin e

s_region

This parameter introduces a footprint for spatially extended data products in 2D, most notably on the sky (using RA, Dec) or on planetary surfaces (using E longitude, latitude). This is a single parameter with no min/max declinations. It must contain a PgSphere spoly variable with syntax: '{(lon1,lat1), (lon2,lat2), … }' (with no quotes) where (lon1,lat1) = (10.d, 5d), character d included (it stands for degrees). Pairs (lon1,lat1) must sample the dataproduct contour in sequence, provided in direct (counter-clockwise) sense. The result of the query is an STC-S string (as in ObsCore; currently limited to polygons). Coordinates are provided in the same reference system as C1/C2 parameters.

In addition, the resource descriptor (q.rd for DaCHS) must contain the line (for body coordinates) - (TBC if still applicable):

<stc>  Polygon UNKNOWNFrame [s_region] </stc>

Open issue: this parameter is responsive to the STC-S string standard of IVOA, which is at draft level and has changed recently at the time of writing - the indication of a coordinate system is no longer included in the string, and the exact support for E longitude (body) is uncertain.

5- Data origin

This parameter provides the name of the observatory or spacecraft that performed the measurements. A hash-list of host names must be provided for integrated data sets. In the epn_core table, the acronym is preferred to the full name to avoid long strings and related errors (both values can be provided in the list). An observatory list is being developed in Europlanet2020 (VESPA / NA1 activity) and will be implemented in a resolver by merging existing lists (draft here: Observatory Facility Database).

Reference lists include:

Identifies the instrument(s) that acquired the data. A hash-list of instruments must be provided for integrated datasets. Service providers are invited to include multiple values for instrument name, e.g., complete name & usual acronym. This will allow queries on either "VISIBLE AND INFRARED THERMAL IMAGING SPECTROMETER" or "VIRTIS" to produce the same reply. 

Example:

VISIBLE AND INFRARED THERMAL IMAGING SPECTROMETER#VIRTIS

A list of recommended values (to be implemented in a resolver) is discussed here: Observatory Facility Database

The most complete ready-to-use list of international planetary missions and orbital observatories is found here: http://nssdc.gsfc.nasa.gov/nmc/

Instruments on board planetary missions in particular are listed here: 
http://nssdc.gsfc.nasa.gov/nmc/experimentSearch.do

6- Granule call-back info

Provides an acronym for the service/table title. This parameter is used to refer to the service providing the data, therefore the value must be equal to the name of the schema and must be constant throughout the service.
When designing the service, care must be taken to use a schema name not already ascribed to another EPN-TAP service - it must be unique on the provider side in any case.

Provides the date when the granule was introduced

Provides the date when the granule was last updated (intended to speed up mirroring between sites)

Provides the date when the granule becomes public (intended to support a proprietary period, usage TBD)

Optional parameters

EPN-TAP can query any parameters included in the metadata table. Some of these parameters are defined precisely but are relevant only to very specific data services. Those are not mandatory, but they must be implemented as defined in this section when present. Besides, the names of optional parameters are reserved for this particular usage and must not be used to introduce other quantities

access_url

The data of interest are often stored in a file, not in the table itself. In this very usual case, the access_url parameter provides a complete path to the data products on the network, so that they are accessible for download by plotting or processing tools. All URLs in the epn_core table are case sensitive and must provide an actual and unique link. The link may be a call to a web service (e.g., CRISM service) or the output of a script (e. g., Titan atmospheric profiles service); in both cases the link must include the adequate arguments. In any case, this parameter must link to the actual data, not to a file of metadata nor a document. Datalinks (which typically open a page with either a list of links or an input interface for parameters) can be used for this later purpose, and must be provided via the datalink_url parameter. 

access_format

Access_format provides the format of the data file linked through the access_url parameter.
The data may be stored under native format, and no format conversion is required to set up an EPN-TAP service; this field can therefore include reference to unusual formats. However, VO ready formats are required to take advantage of visualization and processing in VO tools. Consistently with ObsCore, possible values are MIME-types written in lower cases; the most common ones are listed on this page: Data Formats and MIME Types.

access_estsize

The access_estsize field provides an order of magnitude (in kilobytes) of the file available via the corresponding URL. It is intended to provide an indication that can help to tune download functionalities in an application, depending on data volume and transfer bit rate.


Other parameters may be used to describe the data files:

The thumbnail_url parameter contains the URL of a reduced version of the data product used for quick-look purpose (e.g., a small jpeg image, typically 200x200 pixels). This may be handy in the case of big data files or unusual data formats, to facilitate data selection by the user. The EPN-TAP client uses this thumbnail for on-line quick-look, which therefore provides important added value to a service. Preferred formats include jpeg and png, which are handled easily by a basic viewer. Larger or more elaborate previews must be provided as independent granules and identified via a granule_gid different from that of the data. All URLs in the epn_core table are case sensitive and must provide an actual link.

file_name

The file_name parameter introduces the name of the data file, with extension but no path information. In many data services, the file name encodes the most relevant metadata and may be a very handy access mechanism for specialists. In services providing sets of files in a complicated directory tree (e.g., related to a spacecraft operation plan), the file_name parameter is a handy key to perform automatic operations such as mirroring, pipeline processing, etc - a web service is available to retrieve a file from the file_name parameter in any EPN-TAP service (File grabbing interface). Its use is therefore always recommended when data are provided in separated files, i. e., not included in the table.
All file_name values in the epn_core table are case sensitive and must reflect the filename of the product provided through access_url; for instance, if access_url is a link to a script converting an ascii file to VOTable, file_name must refer to the outcome of this script, in this case the VOTable.

access_md5

This parameter introduces a MD5 Hash for the file when available (link to a real file), to be used as a checksum.

accref

Although not an EPNCore parameter, this name is reserved for internal use - but it must not be used explicitly. It is used to introduce a URL with datalink in TAP / DaCHS (present in epncore2 mixin), and is also generated automatically in the q.rd when using the localfile mixin (when accessing data files located on the DaCHS server itself). It may also be required to handle proprietary periods in DaCHS, TBC.

This parameter is used to provide extra accesses through a datalink/SODA interface. It can either provide a table of hard links (dlmeta) or a dialogue to setup input values on the fly and  call a web service on the data server (dlget). Links can be parameterized with input values retrieved from the current granule at the time of ingestion; if several EPN-TAP parameters need to be passed, they must be first concatenated in an extra parameter in the table (often called ds_id).

8- Supplementary descriptions

The bib_reference parameter introduces an individual bibliographic reference at granule level. This provides the origin of the data, e. g., if the resource is a compilation of data from various origins. References are best provided as bibcode (as used e. g. by ADS), as DOI, or as arXiv reference, although other formats are acceptable. A generic regular expression for bibcode (from IPDA discussions) is: [0-9]{4}[A-Za-z0-9\&\.]{5}[A-Za-z0-9\.]{9}[A-Z\.] 

See http://adsabs.github.io/help/actions/bibcode

Specifies the publisher of the data service (not necessarily at the origin of the data). Currently a free format string.

The internal_reference parameter can be used to identify granules (or sets of granules) intimately related to the current one. E.g., in a service containing both observations and results of analysis of observation sets, internal_reference can be used to provide the set of observations used to compute a result. This contains a list of granule_uid in the same service.
This is specifically intended to provide internal references in services which would otherwise need to be split in several tables, and must it be used only as a last resort (clever use of  obs_id and granule_gid is usually more satisfying). 

The external_link parameter can be used to provide extra information that does not fit easily in the table, and is intended for human reading only. This parameter must contain a single URL. This is typically an extended discussion of a granule on a web site, which may include images, tables, or other documents. For instance, the individual planet pages of the Encyclopedia of exoplanets are linked with this parameter. Alternatively, it can provide a link to a web service related to this granule; for instance, in the HRSC/MEx service (hrsc3nd) it displays a detailed view of the image with zooming functions for quick examination.

species

The species parameter introduces the chemical species of interest in simple data services. The formatting is very basic and simply uses the standard formula in ascii, e. g., H2O for water, CO2 for carbon dioxide or Fe for iron. This is one of the few query parameter provided in case sensitive form, using the standard chemical notation. This format can only accommodate atoms and simple molecular species, and does not support isotopic variations.  

An example application is related to atmospheric composition: a table providing vertical profiles of gaseous species with altitude. All columns are abundances and are described by the same measurement_type parameter. The use of the "species" parameter allows identifying the various species and accessing the requested information. This of course is restrained to simple cases.

If more elaborated compositional information must be included, the use of parameter species_inchikey is recommended. InChiKeys identify molecule, including isotopes, but not the physical state or phase.

waveband

provides a rough indication of the spectral domain, e.g. when variable in a large archive. Values are from VODataService / ConeSearch (beware of slight differences in SSA: ultraviolet instead of UV, and no EUV): 

  • Radio
  • Millimeter
  • Infrared
  • Optical
  • UV
  • EUV
  • X-ray
  • Gamma-ray

Introduces a supplementary name to provide more details about the observed target. It is intended in particular to accommodate a local name (crater, surface feature, region…) whereas target_name is reserved to identify the whole body (Mars, Moon, Ceres…). Use of official features names defined by IAU (http://planetarynames.wr.usgs.gov/) is preferred when relevant.

Specifies a type of region on the target. This parameter only introduces generic regions (e.g., atmospheric layer, internal structure…), not specific local names which must be handled using the feature_name parameter.

Values are best selected from the Unified Astronomy Thesaurus: http://astrothesaurus.org/thesaurus/

Older sources (some of them may be integrated in the UAT) include:


Example

"atmosphere", "surface", "ionosphere"
The same sources are used for the declaration file in the registry.

Spatial_coordinate_description

Spatial_origin

These two parameters provide a description of the spatial frame in use, depending on the spatial_frame_type parameter. 

Spatial_coordinate_description provides an acronym of the Coordinate Reference System as discussed in Planetary Coordinate Systems. For body-fixed frames, IAU/SPICE/WMS strings such as IAU20xx:49900 are eligible - in this case, the final 00 which stands for planetocentric E-handed is the only valid option (refers to EPN-TAP standard on C1/C2 coordinates) - TBCIf absent the current IAU coordinate system is assumed, depending on context. 

Spatial_origin may be used to identify frame center in specific situations, TBC

Examples (TBC)

ICRS, BODY?, Mars_IAU2000? IAU2000:49900
Geocenter

Indicates where the time is measured. This knowledge is required to cross-correlate event-based observations, in particular to indicate light-path differences. It applies to the time_min and time_max parameters (while target_time always refers to the target in the FoV). If this parameter is not informed, time is expected to be provided in the observer frame. Example values for time_origin are:

Earth, (solar system bodies), (spacecraft)

Always UTC in data services. This may be relaxed in computational services such as ephemeris, using standard acronyms for time scales.

Solar longitude (a.k.a. heliocentric longitude, or ecliptic longitude of the Sun, traditionally noted Ls) is the Sun-Planet vector angle counted from the planet position at N hemisphere spring equinox. It provides a measurement of season.

Ls = 90° corresponds to the northern summer solstice, Ls = 180° to the northern autumn equinox, and Ls = 90° to the northern winter solstice. Although it is most usually applied to Mars and Titan (using Saturn's Ls), this notion can be enlarged to any planetary body without ambiguity.

This should not be confused with the true anomaly of the body (which is the same angle counted from the perihelion position), nor with the longitude of the subsolar point (see below).

Provide the local time at the observed area. These parameters are provided in unit of target rotation divided by 24 and are measured from local midnight (ranges from 0 to 24, must increase with time at a given location). They are provided in decimal hours.

The target_distance parameters introduce the distance of the observer to the observed area (in km) along the line of sight. This is mostly intended for space borne data, where it provides the spacecraft-target distance in km. For ground-based observations the earth_distance_min/max parameters should be used instead (in au).

The target_time parameters introduce the time measured in UTC scale at the target. This is intended to directly correlate simultaneous observations such as ground-based support and space-borne observations, or multi-spacecraft campaigns. Values in ISO 8601 format reusing this pattern: “YYYY-MM-DDThh:mm:ss”. 

earth_distance (min/max)

sun_distance (min/max)

these two parameters provide the corresponding distance of Earth or Sun to the target at the time of observation (in au). When the target is the Sun or Earth, use the target_distance_min/max parameters to provide the distance to the observer.

Provide coordinates of sub-observer point, in particular sub-Earth point (disk center) or central meridian for ground-based observations (this is different from the FoV location which is provided in C1/C2 parameters). The min/max pair is required to support long exposures related to time series, especially on giant planets to test target attitude.

Provide coordinates of sub-solar point, e.g., especially for disk images. The min/max pair is required to support long exposures related to time series.

sky coordinates of the target can be provided in addition to standard coordinates, in which case they must be stored in these parameters (no min/max variations to maintain compatibility with existing software). This may for instance document the location of a planet in a celestial image, while the main coordinates c1/c2 are used to describe the observed area as longitude and latitude. ICRS coordinate system is assumed; right ascension is provided in degrees (similar to ObsCore). RA, DEC parameters are interpreted correctly by most VO tools.

Vertical scales on planets

In body-fixed frame, parameters C3min/max, if provided, introduce a vertical range counted from a reference surface, typically the reference ellipsoid for the current target.

Two other parameters can be used provide different vertical scales, and must be considered for atmosphere-related services when available/relevant:

radial_distance (min/max)

Distance of observed area (at C1/C2) from body center, measured in km. Not to be confused with target_distance (which provides the distance from observer to observed area). 

altitude_fromshape (min/max)

Altitude of observed area (at C1/C2) above local surface, measured in km. The local surface is provided by a DTM or a shape model. This parameter typically provides the height in the atmosphere.

C3 can be used to select services/data in a given altitude range above the ellipsoid, while radial_distance and altitude_fromshape provide other convenient vertical scales to compare observations from various origins. This use of C3min/max also applies to planetary interiors (C3 is then <0) and measurements at high altitude/distance. 

Extensions

EPN-TAP extensions are subsets of optional parameters related to a specific field of data, based on several implemented services.
When the corresponding quantities are present, they must be introduced by these parameters to favor interoperability of services.
All parameters of an extension may be present when the extension is in use. All parameters are available in other situations, provided that the meaning and usage are preserved. 

9- Particle spectroscopy extension

The particle_spectral_type parameter introduces the type of axis in use: either energy (provided in eV), mass (in amu), or mass/charge ratio (in amu/qe).

The particle_spectral_range parameters define the upper and lower bounds of the spectral domain for particles. Depending on the particle_spectral_type parameter, this quantity is expressed on an energy, mass, or mass/charge scale, with respective units eV, amu, or amu/qe.

The particle_spectral_sampling_step parameters provide the spectral separation between measurements, in the same scale and unit as particle_spectral_range.
This parameter is mostly intended to provide an order of magnitude.

The particle_spectral_resolution parameters correspond to the actual resolution of the measurements, and are provided in the same scale and unit as particle_spectral_range.
This parameter is mostly intended to provide an order of magnitude.

10- Solar System Objects extension

Service providing descriptions of solar system objects contain no observations (only inferred properties).
In this case, the target_distance_min/max parameters can provide distances from the frame origin (typically heliocentric), in km for consistency - TBC, not favorite

mean_radius, equatorial_radius, polar_radius

These parameters are used to provide solar system object sizes (in km)

mass

Solar system object mass (in kg)

sideral_rotation_period

Solar system sidereal rotation period (in hour)

semi_major_axis

in au,

inclination, etc

See discussion page: orbital parameters


When target_class = asteroid or dwarf_planet, the following parameters can be used:

dynamical_class

introduces the class of small body, from an enumerated list. The draft list includes: TNO, MBA, NEO - add OCC (Oort Cloud comet), JFC (Jupiter family comet) here, and Centaur, Trojan (but which planet?)

dynamical_type

introduces a subdivision of the above, from an enumerated list. It currently includes:

  • NEO (complete): Atira, Aten, Apollo, Amor
  • TNO (complete, but check values): res 2:5 (develop?), res 1:2 (develop?), Plutino, Hot classical, Cold classical, Scattered disk object, Detached object, Inner Oort object (not strictly KBO?)

MPC service also contains the following (unclear) values as orbit_type: 4 NEO types + Object with perihelion distance < 1.665 AU, Hungaria, MBA, Phocaea, Hilda, Jupiter Trojan, Distant Object, Unclassified


To be made consistent with SsODNet. See discussion page: Small bodies sub-types

11- Maps

map_projection

Provides map projection description (preferably as FITS name or code) or parameters as a free string — for instance, several services use this to store proj4 parameters. This refers to the data, not necessarily to the spatial coordinates in the table (which have to be east-handed).

map_height & map_width

Provide dimensions of raster maps / WCS.

pixelscale (min/max)

Pixel size at a surface, in km/pixel.

12- Contributive works

Services including data provided multiple sources can identify them with parameters of type observer_*, e.g., observer_id, observer_location, etc
This is used in particular for services compiling amateur data, of facility-related data services. List TBD, see also PVOL.

original_publisher

Services compiling data from many sources can use this parameter to refer to the source of the data

data_calibration_desc

The data_calibration_desc parameter from the spectroscopy extension can be used to provide information on post-processing (this is preferred over a "comment" parameter)

producer_name & producer_institute

provide reference to who produced the data, especially for experimental data services

13- Experimental spectroscopy

Specific *_desc parameters describe the sample and the experimental setup. Although optional, they are important to provide the context. They introduce free descriptive strings which are not intended as search parameters.

Note: VOtable are often better supported than fits files by VO spectral tools, and are therefore the preferred option to distribute spectral files if format conversion has to be considered. For dimensionless data (e.g., reflectance), units="" (VOunit standard)

producer_name & producer_institute

provide reference to who measured the sample (from Contributive Works extension).

sample_id

Additional ID of the sample, e. g., a specific fraction of a meteorite (in addition to target_name). Intended to refer to a pre-existing catalogue of a collection, will therefore contain a name/ID mainly for local use. 

sample_classification

provides composition as group, class, sub-class, etc… of sample concatenated in a hash-list (this allows for flexible searches with LIKE and %; this is in practice the only way to ensure that we get all results). It should include the specification "meteorite" plus the meteorite type when applicable, as well as description of (main) mixtures ingredients. Meteorite types as in Krot et al 2005. Dana or Struntz classification tags can be used for minerals. Minor/trace components are not welcome here (would multiply false alarms).

species_inchikey 

can accommodate an accurate machine-oriented description of species involved. InChiKeys do not include #, and are therefore consistent with the hash-list syntax.

grain_size (min/max)

provide the particle size range in µm. A very large value (eg, >1000 µm) can be used locally in a service to identify bulk material - see if we define a code for this (-1 could do, but we also have to reserve a code for N/A). This is really grain_size, since particle is reserved for particle spectroscopy.

azimuth (min/max)

azimuth angle in degrees - see if negative values of angles can have a special meaning (also for phase angle)

pressure & temperature

Provide experimental conditions, in bar and K - although not recommended by IAU, unit bar is accepted for pressure in this context, as it refers to terrestrial/lab conditions.

sample_desc

free string or hash-list describing the sample, its origin, and possible preparation

setup_desc

free string or hash-list describing the experimental setup if needed - may include aperture (size of sample measured), etc

data_calibration_desc

free string or hash-list describing data post-processing / calibration

geometry_type

Describes the geometry for spectral measurements, from an enumerated list. Possible values are:

  • direct (therefore in emission)
  • specular
  • bidirectional
  • directional-conical
  • conical-directional
  • biconical
  • directional-hemispherical
  • conical-hemispherical
  • hemispherical-directional
  • hemispherical-conical
  • bihemispherical
  • directional
  • conical
  • hemispherical
  • other geometry
  • unknown

spectrum_type

Explicitly provides the type of spectral measurement, from an enumerated list - this is where 'radiance factor', 'reflectance', 'reflectance factor' etc… are defined. The purpose is to give a precise description of complex measurements independently from UCDs, which are not expected to reach this level of description.

A list of possible values is provided on this page, together with corresponding UCDs (which appear both under measurement_type and in the data files): Lab spectroscopy extension

measurement_atmosphere

Provides description of experimental conditions as a free string. Measurements under vacuum are indicated here with the word 'vacuum'.

Use of general parameters 

More general parameters have restricted usage in this case:

thumbnail_url Provides a link to a small spectral plot - caution should be taken to maintained minimal readability in small format in the VESPA portal. Larger plots can be included as separated granules (previews).

datalink_url External documents are often available to provide extra information in this context, e.g. chemical analysis or descriptive image of the sample. Such documents can be considered an extension of the table for the current granule, as opposed to other data products which must be defined as different granules/lines. The best solution identified consists in providing such links under the datalink_url parameter (as dlmeta)  - the alternative idea to use specific parameters such as document_url, image_url… is deprecated.

target_class = 'sample', constant

target_name provides the name or ID of the sample — a value is mandatory in this case. It introduces the name of a meteorite or lunar sample when applicable. Various parts of the same sample can be indicated and described in sample_desc (such as "Location A", etc) or in sample_id.

measurement_type provides the type of measurement/scale as a UCD (REFF, I_over_F, etc…), and is completed by spectrum_type which is expected to be more accurate in general.

species is also available, see if usage is desirable (absence of a species here may suggest that no measurement is available in a services, while usage is limited to some species in practice).

original_publisher may be used to identify a source database in a collective service such as SSHADE


Special cases to handle:

  • Photometric measurement sets: some wlv and many angles, distributed together
  • Band lists: tables with characteristics and attributions - EPNCore may not be the best possible solution, TBC
  • Optical constants: use two associated spectra? Or only one if complex data are available.

14- APIS extension

A specific extension has been designed for compatibility with the APIS service, so that all services in the field of planetary aurorae can be queried together and consistently.

Definition here: EPNcore extension for APIS

This page contains a table of Extra parameters defined for APIS, which can be used for other services distributing observational data from a large facility.

15- Events

The following parameters are proposed to handle VOevents (Work in progress):

Use of general parameters 


access_url is expected to link to a VOevent file (TBC) with dataproduct_type = ev 

access_format = text/xml (for broad identification) or = application/x-voevent+xml 

instrument_host_name instrument_name are expected to be "simulation" + reference of code used, including version number if the event is a prediction (standard use applies for observation)

target_name groups all targets in a hash list (e.g., Sun#Earth) - TBC

obs_id is identical for related events

event_type

Provides a type of event from a pre-defined list. Possible values include:

  • meteor_shower
  • fireball
  • lunar_flash
  • comet_tail_crossing

event_status

Following the VOevent standard, this can be:

  • prediction
  • observation
  • utility (e. g., local event related to an instrument, like a change of detector)

event_cite

Following the VOevent standard, this can be:

  • followup
  • supersedes
  • retraction (an alternative is to update the event lists)

16- Other extensions

Other extensions will be defined by topical working groups. They will complete the current list.


 



  • No labels

8 Comments

  1. Need to compare param for planetary disks obs: angular size, resolution/scale from obs, etc

    + what is the main coord system?

    1. You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account.
  2. Do we build an exoplanet extension, based on the exoplanet service? There was a need for such a model expressed by IVOA folks.

  3. dataproduct_type should vo in case of access_url in voevent format, if it's another format should we use ev as event if the voevent. There is no mention in the PSWS requirement to use VOEvent format even if it is a VO Standard


  4. Stéphane Erard Do the standard consider a parameter for describing the "system" a target/body is part of? Say we want to query data from all moons of Jupiter, or all records/granules of the Jupiter system, should I got "select ... from ... where target_name = Ganymede OR target_name = Europa OR target_name ..."? Or should we have something like "select ... where target_system = Jupiter"?

    This application occurred to me while trying to "group by" planets and respective satellites.

    Anyhow, a mechanism to link components of a system could be interesting for mining.

    1. We don't have that, but you can use it in a service if needed. We can actually add this as an optional parameters - but we have to agree on a name (not sure this is the best possible one)

      1. In principle, this should work from the portal (not in TAP, because the SSODNET name resolver does the conversion):

        target_name = 5?, target_class = satellite

        or

        target_name = 5__, target_class = satellite


        Only that it does not currently ;(

        Working on it

  5. This is an idea to think about. In my case, I can build the mappings necessary. It is worth saying that not necessarily a specific field is the best solution, maybe something analogous to UCDs may be a good solution. UCDs hierarchically describe the datum in the signal-processing space, the same structure could be used to effectively describe a granule in the "targets (bodies or samples) space".

    1. There are several prob with this solution:

      • It is orthogonal to the current parameter-based system to have several info stored together (except if you're thinking of  defining a new name for each object)
      • therefore not TAP-like, and I don't see how to support this
      • error-prone for data providers in all cases
      • That would define a new, arbitrary standard, limited to use in VESPA. Precisely what we don't want to do. 
      • Something perhaps similar exists in Spice for satellites, and is supported by our name resolver. This provides both main planet and satellite ID, with numerical codes (Phobos = 401) - but I'm not sure this is what you refer to.