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

 

 

More complete description of v2 parameters, providing meaning and usage. Derived from EPN-TAP v1 doc (4 - EPN-TAP queries)

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

Spaces can only be included in free strings values, and are forbidden in values of search parameters (ie, no space can be included in a search string such as target_name).

Named parameters must be unique; utypes must appear at most once in a table.


Mandatory parameters


1- Granule references

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

granule_uid

Unique granule ID in data service.

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

granule_gid

Common to 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.

obs_id

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

 

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 (see below), or directly included in the table (in which case the value is most likely 'ca' for catalogue). 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 — although using several granules to describe the file content may be a better solution.
In the epn_core view 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, all vectorial 2D fields are described as catalogue (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 a Projection parameter (with a short enumerated list of possible values). This is mostly intended to identify complete coverages that can be used as reference basemaps. Does this require a secondary UCD notation (e.g., ;map)?
  • sp (= spectrum): measurements organized primarily along a spectral axis, e.g., radiance spectra. This includes spectral aggregates (series of related spectra with non-connected spectral ranges, e.g., from several channels of the same instrument - TBC).
  • 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 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.
  • pr (= profile): scalar or vectorial measurements along 1 spatial dimension, e.g., atmospheric profiles, atmospheric paths, sub-surface profiles, traverses…
  • vo (= volume): other 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
  • 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 mostly intended to accommodate unusual data with multiple dimensions.
  • 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 single granule providing a list of events, a catalog of object parameters, a list of features... "Spatial vectors" (e.g., vector information from a GIS, spatial footprints…) belong here. This is relevant, e. g., for collections of vectorial elements (e.g. crater lists or ROI definitions) which can be handled directly in a specialized environment such as a GIS. This includes maps of vectors, e.g., wind maps.
  • ci (= catalogue_item): applies when the service itself provides a catalogue, with entries described as individual granules. The service can be, 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.
  • ev (= event): introduce VOevents formatted according to IVOA standard (or possibly events with other formatting, TBC)


Usage:
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)

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 provider must use the "UCD1+" list from IVOA as a reference, and should extend it only when necessary [RD8]:
http://www.ivoa.net/Documents/REC/UCD/UCDlist-20070402.pdf
The measurement_type parameter is used to search data relevant to a certain field. Whenever several quantities are comprised in the granule, the measurement_type parameter must therefore refer to all these quantities, including multiple UCDs if needed.
Quantities derived from modeling/simulation are described by the regular UCD with ";meta.modelled" appended.
Extra UCDs will be proposed/requested to IVOA. In the meantime, an extended list of UCDs will be made available in the EPN-DM document (in progress).
Examples:
For images in general (i.e. actual measurements with a camera), the relevant UCD is obs.image, whatever the calibration level.
For spectra phot.flux.density describes a flux vector (irradiance), while radiance and reflectance are not really defined currently (the closest UCDs are phys.luminosity;phys.angArea;em.wl and phys.albedo).
The associated spectral vector is described by UCDs em.wl, em.freq or em.energy, and the related error is described by stat.error;phot.flux.density (for flux).

In the framework of EPN-TAP, this parameter is intended to provide the user with a quick evaluation of data "usability". Several classifications are in use in different contexts, as summarized in the table below. EPNCore v2 uses the CODMAC levels / PDS3 but removes the intermediate calibration levels; this is equivalent to using the simplified PDS4 levels and maintaining a separated level for ancillary data {reason for this: level 4 is used in only 2 services by the end of 2016, and wrongly; this was also a strong suggestion from the reviewers of the 2014 paper}. "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. Although it may be more consistent to separate calibration levels in different data services, several levels can be included in the same service (in particular calibrated and ancillary data). Only one value can be accommodated in this field, so the most advanced level (1-5) must be used whenever several levels are available in the same granule (TBD: use list instead?)

Most EPN_TAP data services are expected to include Calibrated or Derived data. Other values would therefore only flag associated products.

(Compilation of information from PSA, PDS4, & ObsCore documents)


EPN-TAP v2 level

CODMAC level

/ EPN-TAP v1

PSA level

NASA level

PRODUCT_TYPE

(PDS3/PSA)

PDS4

ObsTAP

Description
(from PSA, with comments)

1

1
(raw)

1a

 

UDR

Telemetry

Level 0

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

2

2
(edited)

1b

0

EDR

Raw

Level 1
(std data format)

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

3

3
(calibrated)

2

1A

RDR

Calibrated

Level 2

Reduced Data Record
("calibrated" in physical units)

5

4
(resampled)

 

1B

REFDR

Derived

 

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

5

5
(derived)

3

2-5

DDR

Derived

Level 3

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…)

 

 

3- Target description

The target_name element 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; alternative names of the same target can 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 [RD19]. This parameter is case sensitive (mixing lower/upper cases) and all values must use the standard spelling and case. 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 provided by VOParis-IMCCE may help data providers (and users as well) to handle multiple denominations [RD11].
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:
The Exoplanet Encyclopedia provides a complete list of currently known extrasolar planets:
http://exoplanet.eu/
Meteorite catalogs can be found here:
http://www.nhm.ac.uk/research-curation/research/projects/metcat/search/indexsing.dsml
http://www.lpi.usra.edu/meteor/index.php
The catalog of lunar samples is available here:
http://www.lpi.usra.edu/lunar/samples/
Other planetary samples are listed in topical web sites, e.g. samples from the Stardust mission are described here:
http://curator.jsc.nasa.gov/stardust/catalog/
Asteroids:
Usage is to use preferably name (if it exists) or principal designation (number is not used here, can be included in alt_target_name)
Calibration:
Values can relate to existing names in a given archive (e.g., the PSA contains values such as bias, checkout, dark, flatfield, internal source…)
Usage:
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 (see ADQL syntax). Complex queries may also include parentheses
Example
1P is the official IAU designation for comet Halley.

The target_class element identifies the type of a named target. A target is defined without ambiguity by a couple of parameters: target_class and target_name (although some targets may have no proper name).
EPNCore defines the possible values for target_class:
asteroid, dwarf_planet, planet, satellite
(types from IAU list [RD22])
comet, exoplanet, interplanetary_medium, ring, sample, sky, spacecraft, spacejunk, star, calibration
(extra types defined for EPN)
Usage:
Any target has a unique target type.
"interplanetary_medium" refers in particular to interplanetary dust.
"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 - other cases are handled though spacecraft or spacejunk.
"star" is used typically for calibration targets, and for the Sun.
"sky" may be used for 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.

Comment: SsODNet uses "Types" of objects which are all included in EPN-TAP list: "Asteroid","Spacecraft","Comet","Exoplanet","Spacejunk","Satellite","Planet","Dwarf Planet","Star"
Additional EPN-TAP classes are: interplanetary_medium, ring, sample, sky, calibration

4- Axes

EPN-TAP describe the data location along 4 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 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_min and time_max parameters provide the date and time of acquisition in the observer frame.
In EPN-TAP, the time parameters are always provided in UTC and formatted in Julian days (expressed as a double precision float). Although ObsCore uses Modified JD, EPNCore uses standard JD to avoid ambiguity with time origin. With double precision floats, the accuracy is on the order of 1 ms, which is considered sufficient to identify data of interest (the initial accuracy is preserved in the data itself).
The two values min/max permit to handle long periods. Whenever acquisition time is a scalar (rather than an interval), both time_min and time_max must contain the same value in the table. There is no limiting value to this parameter.
Examples:
http://<server address>/tap/sync/request=doquery & lang=adql & query=select * from epn_core where time_min > '2455197.5' and time_max < '2455927.5'
Will search data described by a time range
http://<server address>/tap/sync/request=doquery & lang=adql & query=select * from epn_core where time_min between '2455197.5' and '2455927.5'
Will search data described by a start time parameter

Time range is normally 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 (see section 8).
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 additive, specially formatted time scales such as native on-board time (see section 8). The information of the time_min and time_max parameters is however greatly recommended for observations, as it is used by default to search datasets.

These parameters provide the sampling step 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.

These parameters correspond to the integration time (or exposure time) of measurements. It provides 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. As mentioned previously, this quantity is conventionally expressed on a frequency scale in Hertz. Conversions to the native unit are provided in Appendix A.
Since this is the standard parameter to identify a spectral location, it is recommended to fill it even for images obtained through a filter.
The spectral range and associated parameters only apply to electromagnetic waves. See the optional parameters particle_spectral_* for particle energy or mass detection.

The spectral_sampling_step parameters provide the spectral separation between the centers of two adjacent filters or channels. Like all spectral_* quantities, it is expressed on a frequency scale in Hz. Conversions to the native unit are provided in Appendix A.
These parameters are mostly intended to provide an order of magnitude, e.g., to distinguish between grating spectrometers and Fourier spectrometers, or between observations related to surfaces or atmospheres. It can also help distinguishing between Nyqvist and sub-Nyqvist sampling rates.

The spectral_resolution parameters correspond to the spectral bandwidth used for the measurement (Full Width at Half Maximum). In case of a filter camera this is the filter bandwidth; in case of a spectrometer this is the spectral resolution per se.
These parameters are mostly intended to provide an order of magnitude, e.g. to distinguish between grating spectrometers and filter cameras.

Practical computation can be performed as  (c = 2.99792458E8):
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)

 

These parameters provide up to three spatial coordinates of the measured target. The coordinates depend on the spatial frame type defined below. All services must handle three spatial coordinates, even if the third one is always set to NULL. 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 parameter "target_distance".
In order to make uniform requests possible, spatial coordinates provided in the epn_core view 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 [RD17].
Secondary coordinates can be introduced in the view using additional parameters, e.g., c1 and c2 providing central longitude and latitude of a planetary disk, and extra RA / DEC columns providing location on the sky at this moment.

These parameters provide a simple estimate of resolution, either the FWHM of the PFS on the sky (in degrees), or the pixel size on a surface (in m), depending on spatial_frame_type.
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 view and queries, and the way they are defined. This may be different from the coordinate system associated to / included in the data themselves. A value is required (use "none" if not applicable, "body" may also be OK in most cases). 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 – although this is a special case of spherical frame, the order and conventions are different. Earth distance may be provided as target_distance whenever relevant (ground-based observations). Assumes ICRS coordinates; right ascension is provided in degrees.
body: 2D angles in body-fixed frame: longitude c1 and latitude c2 + possibly altitude (above a reference surface) as c3. (c3 is expected to only provide an order of magnitude in general, not to be a fine search parameter)
Planetocentric system with eastward longitudes in the range (0,360)° is expected. Current IAU frame is assumed, in particular for definition of  prime meridian.
IAU 2009 planetocentric convention [RD12] 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 (see [RD12] for small bodies, and Annex A for details).  
The spatial_coordinate_description and spatial_origin attributes allow the data provider to indicate different conventions, e. g., to indicate a planetographic frame, or to use altitude above a reference surface as the third coordinate. It is stressed however that using other frames will make comparisons between datasets more difficult.
- No, that would preclude uniform queries. These 2 param have to relate to the coordinates provided with the data.

- Two other parameters are available to provide other vertical scales, see below (radial_distance and altitude_fromshape).
- Planetary interiors have C3 <0
- Planetocentric rotating frames are defined as spherical (TBC)

cartesian: (x,y,z) as (c1,c2,c3). This includes spatial coordinates given in pixels.
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 to a solid body, "celestial" (with RA/Dec) or "body" (with longitude/latitude) coordinates must be used instead.
cylindrical: (r, theta, z) as (c1,c2,c3); r = radius; theta = azimuth; z = height. 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).

spatial_origin used to indicate center of frame ?

Not used in the view (only possible in the data) ?
healpix: TBC (Nside and pixel#? Should also specify or assume ordering (nested/ring) ) - TBC, wait for 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 view, 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.
Ranges and specific definitions vary with the actual frame in use, and are discussed in Appendix A. - Only applies to the system provided in the data?

 

The incidence angle parameters define the upper and lower bounds of the incidence angle variation 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 available through non-compulsory parameters).

The emergence angle parameters define the upper and lower bounds of the emergence angle variation in the data (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 available through non-compulsory parameters).

The phase angle parameters define the upper and lower bounds of the phase angle variation in the data (scattering angle - 180°, or angle light source-target-observer). This 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, incidence and emergence are partly related:
abs(i - e) < phi < i + e
If the azimuth angle a is provided 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

 

Another mandatory parameter provides additional information about axes coverage:

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 (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 retrained to polygons).

In addition, the resource descriptor (q.rd for DaCHS) must contain the line (for body coordinates):


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

Open issue: this work directly in celestial coordinates, using ICRS as POLYGON value. On a planetary body, frame UNKNOWNFrame must be used. The difficulty is that W longitudes are assumed in this case. To be discussed at IVOA. The recommendation is to build s_region contours using W longitudes for the time being, but this will change in the future.

5- Data origin

This parameter provides the name of the observatory or spacecraft that performed the measurements. The best practice is to use names from the lists indicated below. A list of host names must be provided for integrated data sets.
For ground-based observations, the reference is the list of IAU observatory codes: http://www.minorplanetcenter.net/iau/lists/ObsCodesF.html
However, this list is not intended to include all ground-based observatories, and a complement still needs to be identified (including e. g. radio-telescopes).
A reasonably complete list of radio-telescopes is available here:
http://en.wikipedia.org/wiki/List_of_radio_telescopes

Other open Q:

  • are IAU ID eligible?
  • granularity is very heterogeneous (e.g. one single entry for Paranal or Mauna Kea, but many for Siding Spring).

Identifies the instrument(s) that acquired the data. A 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. They must be separated by the # character to be queried.
Example:
VISIBLE AND INFRARED THERMAL IMAGING SPECTROMETER#VIRTIS

Concerning space-borne data, the most complete 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

These 4 keywords must always be informed.

Provides an acronym for the service/table title. This is used to refer to the service providing the data, therefore this must be identical to the name of the schema and must be constant in the view.
When designing the service, care should be taken to use a schema name not already ascribed to another EPN-TAP service.

Provide the date when the granule was introduced

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

Provide the date when the granule becomes public (intended to preserve proprietary period, usage TBD)

 


Optional parameters


EPN-TAP can query parameters not included in the EPNCore. 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. Beside, the names of optional parameters are reserved for this particular usage and must not be used to introduce other quantities.
Whenever constant throughout the service, some of these parameters can be defined at the table level, instead of the granule level (i. e., in the description of the epn_core view rather than as an column).

7- Data Access Reference

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 view are case sensitive and must provide an actual link. However, the link may be the output of a script on the server, in which case this parameter provides a call to the script with adequate arguments (e.g. Titan atmospheric profiles service). In any case, this parameter must link to the actual data, not to a file of metadata nor to a document.
Whenever the data consists in a few scalar fields, this parameter may be replaced by parameters providing the data itself (e.g. mass, in a table providing the masses of Solar System bodies).

access_format

Access_format provides the format of the data file linked through the access_url parameter.
The data may be stored in their native format, and no format conversion is required to set up an EPN-TAP service. This field can therefore include reference to unusual formats, although those may not be handled by plotting tools but only in a specific environment. Consistently with ObsCore, possible values are MIME-types written in lower cases and are listed in Appendix F (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 can be provided as independent granules and identified via a granule_gid different from that of the data. All URLs in the epn_core view 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 view are case sensitive and must reflect the filename of the product provided through access_url; for instance, if this is a link to 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

Not an EPN-TAP parameter, but apparently used to introduce an URL with datalink in TAP / DaCHS (present in epncore2 mixin) - really? Also seems required to access data files located on the same DaCHS server. See with developers for use in TOPCAT and VESPA portal. May also be required to handle proprietary periods, TBC.

This parameter is used to provide extra accesses through a datalink/SODA interface. It can either provide a table of hard links or a dialogue to setup input values and call a web service. Input values can be retrieved from the current granule; if several EPN-TAP parameters need to be passed, they must be concatenated in an extra parameter in the table (often called ds_id). TBC: does this need to be called this way?

 

8- Supplementary descriptions

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).

Planetary observations may be documented using the local time at the surface, i. e. the location of the solar meridian normalized to 24. This parameter is provided in unit of target rotation divided by 24 and is measured from local midnight (ranges from 0 to 24, must increase with time at a given location). It is provided in decimal hours.

The target_distance parameter introduces the distance of the observer to the observed area (in km), not to be confused with a vertical dimension provided by c3. This is mostly intended for space borne data, where it provides the spacecraft-target distance in km. For ground-based observations the earth_distance parameter should be used instead (in au).

The target_time parameter introduces the time measured in UTC scale at the target. This is intended to correlate simultaneous observations such as ground-based support and space-borne observations, or mutlispacecraft campaigns.

earth_distance (min/max)
sun_distance (min/max)

For observational services, these two parameters provide the corresponding distance to the target at time of observation (in au).

 

 

Other parameters are available to provide additional information, and can be used independently:

Provide coordinates of sub-solar point, e.g., for ground-based observations.

Provide coordinates of sub-observer point, in particular sub-Earth point (disk center) for ground-based observations.

If fixed sky coordinates of the target are provided in the view in addition to standard coordinates, they must be stored in parameters named ra and dec. This may 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.

 

In body-fixed frame, 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 are mandatory for atmosphere-related services when available/relevant:
radial_distance (measured in km from body center) 
altitude_fromshape (measured in km from local surface, i.e. from the DTM or shape model at C1/C2)

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

Spatial_coordinate_description
Spatial_origin
These two parameters provide description of the spatial frame(s) in use, as introduced by the spatial_frame_type parameter. This is mostly relevant when this parameter is constant throughout the service.
Possible values are detailed in [RD17], which is partly adapted from STC [RD13].

Spatial_origin may be used to distinguish between altitude and distance from center when body coordinates are in use - TBC.
Examples (TBC)
BODY, Mars_IAU2000, ICRS
Geocenter 

This attribute states where the time is measured, and is expected to remain constant throughout the service. 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 (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.
Possible values for time_origin are:

Earth, (solar system bodies), (spacecraft)

Always UTC in data services (may be relaxed in computational services such as ephemeris) — from enumerated list.

The bib_reference parameter introduces an individual bibliographic reference at granule level. This may be required to provide the origin of the data, e. g., if the resource is a compilation of data from various origins.
This is best provided as a Bibcode (as used e. g. in ADS) or as a DOI.

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 should not be used in more usual cases.

The external_link parameter can be used to provide extra information that does not fit easily in the view, and is intended for human reading only. This may be an extended discussion about 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 can be linked with this parameter.

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 the only query parameter that is 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 the vertical abundances of many gaseous species with altitude. All columns are abundances and are described by the same measurement_type parameter. Only the use of the "species" parameter (together with the column name itself) allows identifying the various species and accessing the requested information.
If the data contain one column per species, it is recommended to also include the species in the column name (e.g., H2O_abundance).
If more elaborated compositional information must be included, the use of another parameter providing InChiKeys is recommended - TBC (inChiKey only related to molecule, including isotopes, but not physical state / phase; does not include #)

The feature_name parameter 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 name…) whereas target_name is reserved to describe the whole body (Mars, Moon, Ceres…). The best practice is to use the official features name defined by IAU [RD20] when relevant.
The target_region parameter (see below) also provides additional information on the target, but is aimed at indicating the global scope of a database (e.g., atmospheric layer, internal structure…).

This parameter optionally identifies the region of interest for the resource, in complement to target_name. This parameter only introduces generic regions, not specific local names, which must be handled using the feature_name parameter (see examples above).
The best practice is to take the values from standard sources:

 

Extensions

EPN-TAP extensions are subsets of optional parameters related to a specific field of data.
When the corresponding quantities are present, they must be introduced by these parameters.
All parameters of a subset must be present when the subset is in use - TBC (unlikely for spectroscopy)

 

9- Particle spectroscopy extension

This parameter and the following ones are related to the spectral distribution of particles only (see the spectral_* parameters for electro-magnetic waves).
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.
Conversions to the native unit are provided in Appendix A.

The particle_spectral_sampling_step parameters provide the spectral separation between measurements, in the same scale and unit as particle_spectral_range.
Conversions to the native unit are provided in Appendix A. 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 derived results).
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
Parameters mean_radius, equatorial_radius, and polar_radius are used to provide sizes (in km)
Parameters mass and sideral_rotation_period are also available (in kg and h)
Parameters semi_major_axis (in au), inclination, etc - to be reviewed

See discussion page: orbital parameters


When target_class = asteroid or dwarf_planet:

dynamical_class: introduces the class of small body, from enumerated 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 enumerated list
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?)
Values from MPC, unclear (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

Projection parameter needed, list of values TBD
How do we define arguments / properties?

 

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.

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

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

Experimental data services may use producer_name & producer_institute, etc - TBC
List TBD, see PVOL


13- Experimental spectroscopy

Specific parameters describe in particular the sample and the experimental setup. The list of parameters is based on the PDS spectral library and the Berlin Reflectance DataBase, often derived from PDS usage, then crossed with SSHADE needs. All are optional and may be absent.

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, units="" (VOunit standard)


producer_name, producer_institute: provide reference to who measured the sample

sample_classification: provides composition as group, class, sub-class, etc… of sample concatenated in a hash-list (which allows for flexible searches with LIKE and %; this is in practice the only way to ensure that we get all results). Should include 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).

grain_size_min, grain_size_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 above.

azimuth_min, azimuth_max: azimuth angle in degrees - see if negative values of angles can have a special meaning

pressure, temperature: experimental conditions, in bar and K

The type of measurement/scale (REFF, I_over_F, etc…) is provided as a UCD through measurement_type (to be defined in this case)

• All *_desc parameters introduce free descriptive strings in lower cases. They are not intended as search parameters (although they can be searched):

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 (formerly processing_desc)

geometry_type: such as bidirectional, biconical, directional-hemispherical, etc - see if this list can be frozen (not likely)

measurement_atmosphere: description of experimental conditions, free string. Measurements under vacuum are indicated here with the word "vacuum".

thumbnail_url provides a link to a small spectral plot - caution should be taken to have units / values readable in full size (will be reduced in VESPA portal)

• Links to external documents can be provided in extra parameters, e.g. containing chemical analysis or sample images (this is really the same granule, similar to e.g. bib_reference, and can be considered an extension of the table - as opposed to another data product which must be defined in a different granule). Parameter names need to end in _url for optimized post-processing in most TAP clients:
document_url (for chemical analizes, etc), image_url (for descriptive image of sample)…

• More general parameters have restricted usage in this case:

Target_class = 'sample', constant

Target_name provides an ID of the sample. 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).

Species is also available, see if usage can be enlarged (e.g., to InChiKeys)

• Other possible parameters, TBC:

Something 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

Optical constants: ~ two associated spectra


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

(Work in progress). Proposed to handle VOevents:

access_url, etc… are expected to link to a VOevent file (TBC) with dataproduct_type = ev ; access_format TBC (text/xml? or text/xml+voevent)

instrument_host_name, instrument_name are expected to be "simulation" + code reference, including version number (or standard use if observations)

for the time being: put all targets involved as a list in target_name (e.g., Sun#Earth); use same obs_id to associate related events

target_name and time_min/max describe the event location and time in all cases. Parameter event_mode says if this is a source event or a consequence (if the event propagates). Related events (cause and consequences) have the same granule_gid.

Alternatively: event_origin_target, event_origin_time: provide location and time of an initial event. If the event propagates in the Solar System (usual case), target_name and time_min/max provide the location and place where effects are observed. Related events (cause and consequences) have the same granule_gid.

event_type: provides a type of event from a pre-defined list (e. g., meteor_shower)

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

event_cite: can be "followup", "supersedes" or "retraction", TBC (alternative is to update the event lists)


16- Other extensions

Will be defined by topical working groups.


 

 

 

  • No labels

3 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