EPN-TAP V2.0 parameters

List of EPN-TAP parameters
(refreshed April 2019) (SE)

EPN-TAP

EPN-TAP is a VO access protocol dedicated to Planetary Science data. It is based on the TAP mechanism from IVOA, completed with sets of parameters and associated lists of values. In this regard, it is similar to ObsTAP but with a different scope.
EPN-TAP version 2 is a major update of the protocol to accommodate larger services and simplify setup and use of data services. All parameters are described here.

Thematic extensions

Some science fields will require optional parameters, which need to be used consistently between services addressing the same field. Such extensions have to be designed by sub-groups involved in the corresponding data services, either as providers or users. This includes:

Lab spectroscopy: parameters to describe mineralogical samples (and possibly other samples)
Orbital/rotational parameters and physical properties of Solar System bodies
Results of planetary 3D modelling run
Exoplanets / planetary systems properties
Bibliographic entries? May be manageable otherwise, through bibcode / doi interpretation

Parameters which must be provided

are now clearly identified - those are not only mandatory, they also must provide a value.
They are mostly related to service description and granule identification.

For Utypes : see epntap mixin v2 for standard parameters (grab them from an existing service)

+ See notes below the table.

Name, v2	Must be filled?	SQL type	Unit / Format / Range	Description	UCD Please comment!	UCD in Obscore 1.1 (30/3/2016 version)	Utype (tentative)	Comments / UCD
EPNCore mandatory parameters (Must be present, possibly empty)					Current value current but dubious or undefined possible alternative but undefined	— ? : closest sense _ : N/A in ObsCore	from epntap v2 mixin (aug 2017) equivalent/close in ObsCore doc 1.1
granule_uid	Y	Text		Internal table row index Unique ID in data service. Can be alphanum.	meta.id meta.id;meta.dataset	meta.id
granule_gid	Y	Text		Common to granules of same type (e.g. same map projection, or geometry data products). Can be alphanum.	meta.id	meta.id
obs_id	Y	Text		Associates granules derived from the same data (e.g. various representations / processing levels). Can be alphanum., may be the ID of original observation.	meta.id;obs	meta.id	obscore:DataID.observationID
dataproduct_type	Y	Text		Organization of the data product, from enumerated list	meta.code.class	meta.id	Epn.dataProductType obscore:ObsDataset.dataProductType
target_name	(services with no target_name do exist)	Text		Standard IAU name of target (from a list related to target class), case sensitive	meta.id;src	meta.id;src	Epn.TargetName
target_class	Y	Text		Type of target, from enumerated list	src.class	src.class	Epn.TargetClass
time_min		Double	d (date as JD)	Acquisition start time (in JD). UTC measured at time_origin location (default is observer's frame)	time.start;obs time.start;obs.exposure (if exposed?)	time.start;obs.exposure	Char.TimeAxis.Coverage.Bounds.Limits.Interval.StartTime TBD (from ObsCore)
time_max		Double	d (date as JD)	Acquisition stop time (in JD). UTC measured at time_origin location (default is observer's frame)	time.end;obs time.end;obs.exposure (if exposed?)	time.end;obs.exposure	Char.TimeAxis.Coverage.Bounds.Limits.Interval.StopTime TBD (from ObsCore)
time_sampling_step_min		Double	s	Min time sampling step	time.interval;stat.min	time.resolution — ?	Epn.Time.Time_sampling_step_min
time_sampling_step_max		Double	s	Max time sampling step	time.interval;stat.max		Epn.Time.Time_sampling_step_max
time_exp_min		Double	s	Min integration time	time.duration;obs.exposure;stat.min	time.duration;obs.exposure	Epn.Time.Time_exp_min
time_exp_max		Double	s	Max integration time	time.duration;obs.exposure;stat.max		Epn.Time.Time_exp_max
spectral_range_min		Double	Hz	Min spectral range (frequency)	em.freq;stat.min	em.wl;stat.min (always as wl)	Epn.Spectral.Spectral_range_min	Always as freq
spectral_range_max		Double	Hz	Max spectral range (frequency)	em.freq;stat.max	em.wl;stat.max	Epn.Spectral.Spectral_range_max
spectral_sampling_step_min		Double	Hz	Min spectral sampling step	em.freq.step;stat.min	meta.number	Epn.Spectral.Spectral_sampling_step_min
spectral_sampling_step_max		Double	Hz	Max spectral sampling step	em.freq.step;stat.max	meta.number	Epn.Spectral.Spectral_sampling_step_max
spectral_resolution_min		Double	Hz	Min spectral resolution	spect.resolution;stat.min	spect.resolution	Epn.Spectral.Spectral_resolution_min
spectral_resolution_max		Double	Hz	Max spectral resolution	spect.resolution;stat.max		Epn.Spectral.Spectral_resolution_max
c1min		Double	(1) Longitude from 0. to 359.9999 RA from 0. to 23.9999	Min of first coordinate	pos;stat.min pos.distance;stat.min (bof) or pos.radius;stat.min (does not exist) for spherical & cylindrical pos.eq.ra;stat.min for celestial pos.bodyrc.lon;stat.min for body pos.cartesian.x;stat.min for Cartesian pos.healpix for healpix (with 2 parameters? - weird) - TBC empty ("") for none (and no unit)	pos.eq.ra	Epn.Spatial.Spatial_range.c1min
c1max		Double	(1)	Max of first coordinate	pos;stat.max, etc		Epn.Spatial.Spatial_range.c1max
c2min		Double	(1) Latitude from -89.9999 to +89.9999	Min of second coordinate	pos;stat.min pos.angDistance;stat.min or pos.az.zd;stat.min (for zenithal distance) for spherical or pos.az.azi;stat.min (for azimuth) for cylindrical pos.eq.dec;stat.min for celestial pos.bodyrc.lat;stat.min for body pos.cartesian.y;stat.min for Cartesian empty ("") for none (and no unit)	pos.eq.dec	Epn.Spatial.Spatial_range.c2min
c2max		Double	(1)	Max of second coordinate	pos;stat.max, etc		Epn.Spatial.Spatial_range.c2max
c3min		Double	(1)	Min of third coordinate	pos;stat.min pos.AngDistance;stat.min or pos.az.azi;stat.min (for azimuth) for spherical pos.distance;stat.min for cylindrical pos.distance;stat.min for celestial pos.bodyrc.alt;stat.min for body? (from surface only, implicitly from reference level) or pos.distance;pos.bodyrc;stat.min for body (from center)? pos.cartesian.z;stat.min for Cartesian empty ("") for none (and no unit)		Epn.Spatial.Spatial_range.c3min
c3max		Double	(1)	Max of third coordinate	pos;stat.max, etc		Epn.Spatial.Spatial_range.c3max
s_region		spoly	PgSphere spoly	ObsCore-like footprint,valid for celestial, spherical, or body-fixed frames.	phys.outline;obs.field (was initially instr.fov, to be corrected)	phys.outline;obs.field	obscore:Char.SpatialAxis.Coverage.Support.Area	ObsCore value recently updated (was phys.angArea;obs) Frame may be identified in q.rd (UNKNOWNFrame) Do we need another param for GIS interface?
c1_resol_min		Double	(1)	Min resolution in first coordinate	pos.resolution;stat.min pos.angResolution;stat.min if angular	pos.angResolution;stat.min	Epn.Spatial.Spatial_resolution.c1_resol_min	(UCD is deprecated, but needed!)
c1_resol_max		Double	(1)	Max resolution in first coordinate	pos.resolution;stat.max	pos.angResolution;stat.max	Epn.Spatial.Spatial_resolution.c1_resol_max	(UCD is deprecated, but needed!)
c2_resol_min		Double	(1)	Min resolution in second coordinate	pos.resolution;stat.min pos.angResolution;stat.min if angular		Epn.Spatial.Spatial_resolution.c2_resol_min	(UCD is deprecated, but needed!)
c2_resol_max		Double	(1)	Max resolution in second coordinate	pos.resolution;stat.max		Epn.Spatial.Spatial_resolution.c2_resol_max	(UCD is deprecated, but needed!)
c3_resol_min		Double	(1)	Min resolution in third coordinate	pos.resolution;stat.min pos.angResolution;stat.min if angular (spherical only)		Epn.Spatial.Spatial_resolution.c3_resol_min	(UCD is deprecated, but needed!)
c3_resol_max		Double	(1)	Max resolution in third coordinate	pos.resolution;stat.max		Epn.Spatial.Spatial_resolution.c3_resol_max	(UCD is deprecated, but needed!)
spatial_frame_type	Y	Text	(1) Use "none" if undefined	Flavor of coordinate system, defines the nature of coordinates. From enumerated list	meta.code.class;pos.frame	_		A value is required by DaCHS (query will return errors if empty)
incidence_min		Double	deg	Min incidence angle (solar zenithal angle)	pos.;stat.min pos.incidenceAng;stat.min posAng	_	Epn.View_angle.Incidence_angle_min
incidence_max		Double	deg	Max incidence angle (solar zenithal angle)	pos.posAng;stat.max pos.incidenceAng;stat.max	_	Epn.View_angle.Incidence_angle_max
emergence_min		Double	deg	Min emergence angle	pos.posAng;stat.min pos.emergenceAng;stat.min	_	Epn.View_angle.Emergence_angle_min
emergence_max		Double	deg	Max emergence angle	pos.posAng;stat.max pos.emergenceAng;stat.max	_	Epn.View_angle.Emergence_angle_max
phase_min		Double	deg	Min phase angle	pos.phaseAng;stat.min		Epn.View_angle.Phase_angle_min
phase_max		Double	deg	Max phase angle	pos.phaseAng;stat.max		Epn.View_angle.Phase_angle_max
instrument_host_name		Text		Standard name of the observatory or spacecraft	meta.id;instr.obsty	meta.id;instr.tel	Provenance.ObsConfig.Facility.name
instrument_name		Text		Standard name of instrument	meta.id;instr	meta.id;instr	Provenance.ObsConfig.Instrument.name
measurement_type		Text		UCD(s) defining the data	meta.ucd	meta.ucd	Epn.Measurement_type
processing_level		Integer		CODMAC calibration level in v1	meta.calibLevel	meta.code;obs.calib	~ obscore:ObsDataset.calibLevel	To be replaced by PDS4 values in v2?
creation_date	Y	Timestamp	(ISO-8601 String)	Date of first entry of this granule	time.creation	time;meta.dataset
modification_date	Y	Timestamp	(ISO-8601 String)	Date of last modification (used to handle mirroring)	time.update time.processing? (not quite this)
release_date	Y	Timestamp	(ISO-8601 String)	Start of public access period (set to creation_date if no proprietary period)	time.release	time.release	obscore:Curation.releaseDate
service_title	Y	Text		Title of resource (an acronym really, will be used to handle multiservice results)	meta.title
Optional parameters
access_url		Text		URL of the data file, case sensitive. Can point to a script. If present, next 2 parameters must also be present.	meta.ref.url;meta.file	meta.ref.url	Obs.Access.Reference	Use this to link data! Can accommodate a datalink if access_format = 'application/x-votable+xml;content=datalink' (UCD from ObsCore)
access_format		Text	(mime type in lowercase)	File format type	meta.code.mime	meta.code.mime	Obs.Access.Format
access_estsize		Integer	kbyte	Estimate file size in kbyte (with this spelling)	phys.size;meta.file	phys.size;meta.file	Obs.Access.Size
access_md5		Text		MD5 Hash for the file when available (real file, not script)	meta.checksum;meta.file
thumbnail_url		Text		URL of a thumbnail image with predefined size (png ~200 pix, for use in a client only)	meta.ref.url;meta.preview
file_name		Text		Name of the data file only, case sensitive	meta.id;meta.file	meta.title;obs — ?		ObsCore obs_title is for a short free text string describing the granule. Do we want this?
datalink_url		Text	(url)	Provides links to files or services on the server	meta.ref.url;meta.datalink
species		Text		Identifies a chemical species, case sensitive	meta.id;phys.atmol
filter		Text		Identifies a filter in use (e.g. imaging)	meta.id;instr.filter			Informative only, free format (no list). Search can only rely on spectral range, as ObsCore does.
alt_target_name		Text	can be a list	Provides alternative target name if more common (e.g. comets)	meta.id;src
target_region		Text		Type of region of interest	obs.field
feature_name		Text		Secondary name (can be the standard name of a region of interest)	obs.field
publisher		Text		Resource publisher	meta.name meta.curation?	meta.ref.url;meta.curation — ?	~ obscore:Curation.publisherID
bib_reference		Text		Bibcode preferred if available, doi, or other biblio id, URL…	meta.bib meta.bib.bibcode (if bibcode)	meta.bib.bibcode (always as bibcode)	obscore:Curation.reference
internal_reference		Text		List of granule_uid(s) in the current service	meta.id.cross			Use to link one granule to a set of other granules. Only to solve situations that would otherwise require several tables
external_link		Text	(url)	Link to a web page providing more details on the granule.	meta.ref.url			Link to an individual page in a web site associated to the database, e.g., a planet page in Exoplanets service. This is a way to provide extra granule information which cannot be accommodated in the table.
spatial_coordinate_description		Text		ID of specific coordinate system and version / properties (~COOSYS)	meta.code.class;pos.frame			still TBD. Discussion in progress here: EPN-TAP v2: Current discussion topic
spatial_origin		Text		Defines the frame origin	meta.ref;pos.frame
time_origin		Text		Defines where the time is measured (e. g., ground vs spacecraft) [target_time is of course always on target].	meta.ref;time.scale or pos;time.scale ?			TBC
time_scale		Text		Always UTC in data services (may be relaxed in computational services such as ephemeris) - from enumerated list	time.scale
subsolar_longitude_min		Double	deg	Min sub-solar point	pos.bodyrc.lon;stat.min			Provided in the most natural body-related coordinate frame, E-handed - seems to require 'body'
subsolar_longitude_max		Double	deg	Max sub-solar point	pos.bodyrc.lon;stat.max			Provided in the most natural body-related coordinate frame, E-handed - seems to require 'body'
subsolar_latitude_min		Double	deg	Min sub-solar point	pos.bodyrc.lat;stat.min			_
subsolar_latitude_max		Double	deg	Max sub-solar point	pos.bodyrc.lat;stat.max			_
subobserver_longitude_min		Double	deg	Min sub-observer point (sub-Earth for ground based observations)	pos.bodyrc.lon;stat.min			_
subobserver_longitude_max		Double	deg	Max sub-observer point (sub-Earth for ground based observations)	pos.bodyrc.lon;stat.max			_
subobserver_latitude_min		Double	deg	Min sub-observer point (sub-Earth for ground based observations)	pos.bodyrc.lat;stat.min			_
subobserver_latitude_max		Double	deg	Max sub-observer point (sub-Earth for ground based observations)	pos.bodyrc.lat;stat.max			_
ra		Double	deg only (like ObsCore)	Right ascension (not hour angle!)	pos.eq.ra;meta.main
dec		Double	deg	Declination	pos.eq.dec;meta.main
radial_distance_min		Double	km	Min distance from center (in body-fixed frame)	pos.distance;pos.bodyrc;stat.min
radial_distance_max		Double	km	Max distance from center (in body-fixed frame)	pos.distance;pos.bodyrc;stat.max
altitude_fromshape_min		Double	km	Min altitude above shape model / DTM (in body-fixed frame)	pos.bodyrc.alt;stat.min
altitude_fromshape_max		Double	km	Max altitude above shape model / DTM (in body-fixed frame)	pos.bodyrc.alt;stat.max
solar_longitude_min		Double	deg	Min Solar longitude Ls (location on orbit / season)	pos.posang pos.bodyrc.lon;pos.heliocentric;stat.min (posang means something else)
solar_longitude_max		Double	deg	Max Solar longitude Ls (location on orbit / season)	pos.posang pos.bodyrc.lon;pos.heliocentric;stat.max (posang means something else)
local_time_min		Double	h	Local time at observed region	time.period.rotation;time.phase;stat.min
local_time_max		Double	h	Local time at observed region	time.period.rotation;time.phase;stat.max
target_distance_min		Double	km	Observer-target distance	pos.distance;stat.min
target_distance_max		Double	km	Observer-target distance	pos.distance;stat.max
target_time_min		Double	d	Observing time in target frame	time.start			(simplest way to look for coordinated observations)
target_time_max		Double	d		time.end
earth_distance_min		Double	au	Earth-target distance	pos.distance;stat.min
earth_distance_max		Double	au		pos.distance;stat.max
sun_distance_min		Double	au	Sun-target distance	pos.distance;stat.min
sun_distance_max		Double	au		pos.distance;stat.max
Parameters from extensions
mass		Double	kg		phys.mass			Solar System Objects extension (generic values in catalogues, not observations)
sideral_rotation_period		Double	h		time.period.rotation
mean_radius		Double	km		phys.size.radius
equatorial_radius		Double	km		phys.size.radius
polar_radius		Double	km		phys.size.radius
semi_major_axis		Double	au
dynamical_class		text
dynamical_type		text


particle_spectral_type		Text			Use phys.particle?			Particle spectroscopy extension
particle_spectral_range_min		Double			Use phys.particle?
particle_spectral_range_max		Double			Use phys.particle?
particle_spectral_sampling_step_min		Double			Use phys.particle?
particle_spectral_sampling_step_max		Double			Use phys.particle?
particle_spectral_resolution_min		Double			spect.resolution;stat.min Use phys.particle?
particle_spectral_resolution_max		Double			spect.resolution;stat.max Use phys.particle?

(1): depending on context (as given by spatial_frame_type). Please comment here: EPN-TAP v2: Current discussion topic

Beware that datatypes apply to the epn_core view, not to the q.rd file where they can be different

Example table for IDs:

File name-type	granule_uid	granule_gid	obs_id
A-Raw	1	native	A
A-Calib	2	calibrated	A
A-geom	3	geometry	A
A-proj	4	projected	A
B-Raw	5	native	B
B-Calib	6	calibrated	B
B-geom	7	geometry	B
B-proj	8	projected	B

Syntax

• multivalued lists = first entry#second entry#…#last entry, or scalar (with no #)
Values separator = #
No quotes around the list

This can be parsed by ADQL/RegTAP function ivo_hashlist_has like this:
select * from vvex.epn_core where 1 = ivo_hashlist_has(lower(target_name),'Venus')

Where the lower function is mandatory to handle values possibly containing upper cases (this is implicit on the 2nd argument)

Beware that only complete elements between separators will be found. The provider has to split the string according to expected searches, e.g.:
Composite Infrared Spectrometer#CIRS
not ~~Composite Infrared Spectrometer (CIRS)~~

Parameters supporting multivalued lists include:
dataproduct_type (this one is best avoided when possible)
target_name
alt_target_name
target_class
instrument_host_name
instrument_name
measurement_type
bib_reference
processing_level

• Defaut values (to be reviewed):
NULL/void: will never return an answer to a query using this parameter (TBC, seems ADQL-related. To be corrected if it is a limitation of the client)
For float / double : -inf for *_min +inf for *_max – still TBC (NaN won't do). To be tested on a real case.
Not needed for strings? (i.e. NULL/void is OK?)
Default behavior looks OK in fact. If we need to preserve the NULL values on queried parameters (ie, when NULL is considered as "I don't know"), this can be done with OR param = NULL (on option in the client? This is feasible manually on TapHandle)

• UCDs: to be reviewed against PDS4 and IPDA, and completed (ObsCore checked)

• Processing levels: to be reviewed against PDS4 (again- mostly related to geometry, considered as derived in PDS4)

• min vs max:
if only one value available, it must appear in both fields

• Optional parameters: they come in sets that are logically related; if one is present, the related ones must be present also (e.g., 3 access_* parameters)

• Granule_gid: any general indication to providers? I.e.: preview, native, calibrated, geometry…
A client should be able to display the values present in a service, TBC

• Reshuffle previous "service parameters":

Mandatory :
processing_level -mandatory
service_title –mandatory
publisher -mandatory???
Optional - TBC
spatial_coordinate_description (default = none)
spatial_origin (default = body center or SS barycenter? Or observer location)
time_origin (default = observer)
time_scale (default = UTC – no other values allowed in data services? [only in computational services, e.g. ephemeris])
Same values to be used in registry declaration

• Support for PDS3 detached labels (proposal)

Solution with datalink seems OK: detached labels provided under datalink_url in a table - although no attempt made to read them from the portal, yet.

• Utypes

Need to clean up current doc (2.0). Utypes are = DM fields. They are supposedly used to identify the meaning of parameters and help e.g. tools to grab required quantities - This will not work in some areas though, e. g. with spectral tools as they currently use UCD instead of Utype for this purpose (not many tools appear to actually rely on Utype in fact). See discussion here for usage (a bit old?): http://www.ivoa.net/documents/Notes/UTypesUsage/20130213/NOTE-utypes-usage-1.0-20130213.html

To handle this in practice:

Associate each parameter to a specific Utype in EPNCore - all names need to start with the epncore: prefix/namespace.
Then map epncore Utype to other DM (find equivalent parameter, or trace back the original templates of EPNCore parameters - often from ObsCore)
Reuse Utype from other DM each times it makes sense - TBC: the epncore: namespace is still required (even when using Utypes from other DM)
This allows tools to handle EPNCore parameters like existing parameters from other DM, i.e., with no specific implementation
Pb is that small differences in the use of parameters may preclude reusing the same Utype (TBC: does that applies to units also?)
Cross our fingers: known Utype (from other DMs) may be usable in existing tools (e.g. a tool supporting Provenance would grab equivalent info in EPN-TAP services transparently)
Unclear if the use of the namespace makes it more complicated in tools.

Example of V2 with APIS database:

EPNcore Table v2

granule_uid	granule_gid	obs_id	access_url	access_format	thumbnail_url
o5g202x4q_x2d	original_data	o5g202x4q	o5g202x4q_x2d.fits	image/fits	o5g202x4q_x2d_small.jpg
o5g202x4q_x2d_prev	original_data_preview	o5g202x4q	o5g202x4q_x2d.jpg	image/jpg	o5g202x4q_x2d_small.jpg
o5g202x4q_proc	processed_data	o5g202x4q	o5g202x4q_proc.fits	image/fits	o5g202x4q_proc_small.jpg
o5g202x4q_proc_prev	processed_data_preview	o5g202x4q	o5g202x4q_proc.jpg	image/jpg	o5g202x4q_proc_small.jpg
o5g202x4q_cyl	cylindrical_projection	o5g202x4q	o5g202x4q_cyl.jpg	image/jpg	o5g202x4q_cyl_small.jpg
o5g202x4q_pol_n	polar_projection_north	o5g202x4q	o5g202x4q_pol_n.jpg	image/jpg	o5g202x4q_pol_n_small.jpg
o5g202x4q_pol_s	polar_projection_south	o5g202x4q	o5g202x4q_pol_s.jpg	image/jpg	o5g202x4q_pol_s_small.jpg

Page tree