Space-Time Coordinates for the VO Metadata

Space-Time Coordinate Specification for VO Metadata

Arnold Rots, SAO/CXC

For a presentation that is easier to read, see this PDF document.

1 Scope

The objective is to provide a metadata description of the volume in space-time parameter space that is occupied by, available in, or requested by: a data set of any kind, a resource, or a query. The "space" part of this parameter space includes spatial coordinates of any kind: spherical coordinates, 2-D (e.g., detector coordinates) and 3-D Cartesian coordinates, one-dimensional coordinates. Also included are the time derivatives: velocities (space velocities and proper motions) and redshifts/Doppler velocities. The latter are treated separately since they are derived quantities based on a formalism, rather than physical velocities (i.e., the value depends on the formalism, which is not applicable to true velocities).

What this means for an image, for instance, is that the metadata describes very precisely and unambiguously what piece of space is represented or occupied by the image. However, a separate metadata object is still needed to specify how that spatial volume is projected onto a pixel array. After careful consideration it was decided that separating the information into two metadata objects (one that specifies the space-time coordinates associated with the data and another that specifies the projection onto a pixel array) is the correct way to model the metadata in this area.

We strongly emphasize that space and time metadata need to be encapsulated in a single metadata object. Although it is true that for the majority of the data that are moved around this is totally unimportant (very few people besides historians will care when a particular photograph of M81 was taken), there are a number of cases where is is crucially important (e.g., high time resolution pulsar observations). We feel that the link needs to be enforced from the outset; it will be very difficult to retrofit it later if it were initially neglected. In other words: we need to do this right.

Although the metadata model presented here is only applicable to space-time coordinates, we would submit that it is also suitable for application to other coordinates, in particular the wavelength/frequency/energy coordinate. This is true for the coordinate attributes as well as the separation of the location and projection objects.

The metadata structures are defined in the form of XML schemas:
stc.xsd, coords.xsd, region.xsd.

2 Overall design

There are three toplevel elements:

2.1 CoordSystem

Defines the spatial reference frame, allowing arbitrary, custom-defined (such as on the surface of an asteroid) coordinate frame, and includes reference (zero point) positions for space and for time, as well as redshift/Doppler definitions, if applicable, and information on the coordinates' "flavor": spherical, Cartesian, etc.

2.2 Coords

Any Coords element needs a reference to a CoordSys element.

2.2.1 Coords provides one or more of the following four coordinates:

2.2.1.1 Time
2.2.1.2 Spatial position
2.2.1.3 Velocity
2.2.1.4 Doppler velocity or redshift

The position and velocity coordinates may be scalar or vector of
length 2 or 3.

2.2.2 Each coordinate holds the following information:

2.2.2.1 Name (this might be a good place for a UCD)
2.2.2.2 Value
2.2.2.3 Error
2.2.2.4 Resolution
2.2.2.5 Size
2.2.2.6 Pixel size

In the case of vectors, the last four items may include position angles or may be represented by matrices.
Each item includes its own "unit" attribute; this is necessary for catalog applications. Units are controlled types, separate for position and time (hence velocities need both to constitute a velocity unit).
Items may be specified as actual values (doubles) or as references to other elements in the document; in particular, this allows referring to a field (column) in the VOTable.
Alternatively, Coords may point to a FITS file that contains the information, such as an orbit ephemeris file.

2.3 CoordArea

Specified by intervals in Time, Position, Velocity, and Redshift.
Intervals are specified by an lower and/or upper limit and attributes indicating whether the limits are to be included.
The Position area has more options and may be specified as:

2.3.1 An interval with lower and/or upper bound

2.3.2 A circle or sphere, with center and radius

2.3.3 A FITS region file

2.3.4 A Region element

This type of object will be described further below.

3 Application

Precise specification of a volume in space-time parameter space is required in four contexts:

3.1 Resource

The specification of the spatial and temporal coverage of a resource, with various associated attributes is achieved through:

3.1.1 CoordSys

3.1.2 CoordArea

Specifies the coverage of the resource, with or without the use of the attribute fill_factor.

3.2.3 CoordSpec, an element of type coordsType

This element does not contain the coordinate values, but one or more of the other coordinate items to indicate typical values for the data in the resource, such as errors, resolution, and size ("Region of Regard").

3.2 Query

The specification of a region of interest in a query, as well as the space-time coordinate attributes desired for the requested data:

3.2.1 CoordSys

3.2.2 CoordArea

Specifies the region of interest

3.2.3 CoordSpec, an element of type coordsType

This element does not contain the coordinate values, but one or more of the other coordinate items to indicate desired data parameters, such as errors, resolution, and size ("Region of Regard").

3.3 Catalog data

The space-time coordinate information in returned catalog entry data:

3.3.1 CoordSys

3.3.2 Coords

If a table is returned, these will typically be references to table
columns that comtain the actual values.

3.3.3 CoordArea (optional)

The area covered by the catalog entries; important for completeness
considerations.

3.4 Observational data sets

The space-time metadata associated with data sets (observed or theoretical, images or event lists, ...)

3.4.1 ObservatoryPosition

This needs to be known, for instance for high-precision timing and near-field (solar system) observations.

3.4.1.1 CoordSys

3.4.1.2 Coords

Position of the observatory; may be an orbit ephemeris file.

3.4.2 ObservationPosition

3.4.2.1 CoordSys
3.4.2.2 Coords
3.4.2.3 CoordArea
The Field or View.

3.5 Other applications

In addition, the space-time coordinate metadata objects are available for use in related contexts:

astronTimeType is an XML type that gives a proper description of any astronomical time instance (though we would warn against careless use of it without an associated coordinate system definition); allowed formats are JD, MJD, ISO-8601 (but only the yyyy-mm-ddThh:mm:ss.sss... part), and elapsed time (relative to a specific time instance in JD, MJD, or ISO 8691)
coordsType is an XML type that allows one to specify any space-time coordinate position
regionType is a very general definition of regions and allows specifying spatial regions in a variety of context: sky coverage, bad detector areas, source regions, background regions, etc.

4 Region

In keeping with the space-time coordinate metadata model, all regions are defined in world coordinates, not in projected coordinates. Simply put, a region consists of a shape or the result of an operation performed on one or more regions. There is a limited list of enumerated shapes and operations. A region may have a fill_factor element (with a value between 0.0 and 1.0) indicating what proportion of the region is actually filled (the meaning of which depends on the context); the default is 1.0.

4.1 Shapes

Boundaries of shapes are considered to be part of the shapes.

4.1.1 Polygon

Specified by a list of vertices. A vertex is specified by a coordsType element and an optional small-circle element which has meaning only for spherical coordinate systems. The presence of the smallCircle element indicates that the polygon side between this vertex and its predecessor is to be a smallcircle, rather than the default greatcircle. Optionally, the pole of the smallcircle system may be specified; if absent, the pole of the referenced CoordSys is assumed. Obviously, one has to take care that the two vertices actually lie on the same smallcircle. The last vertex in the list is the predecessor of the first vertex. The inside of the polygon is circled counter-clockwise. Polygons may be concave, but should not be self-intersecting.

4.1.2 Circle

Specified by a center and a radius.

4.1.3 Ellipse

Although strictly speaking the circle is a special case of an ellipse, we derive the ellipse from the circle by adding a semi minor axis and a position angle element.

4.1.4 Sector

A sector between two half-lines, extending from a particular point, is selected. Specified by a position and two position angles.

4.1.5 Constraint (spherical coordinates only)

A plane is defined by a unit vector that is its normal and by the distance (offset) between the origin and the intersection of the normal and the plane (if negative: in the opposite direction of the normal vector). All points on the surface of the unit sphere that lie beyond the intersection of that plane with the unit sphere in the direction of the normal vector are selected. This means:
    offset > 1.0:            no intersection, resulting in an empty shape
    offset = 1.0:            tangent plane, resulting in a single point
    1.0 > offset > 0.0:    intersection a smallcircle, resulting in less than a hemisphere
    offset = 0.0:            intersection a greatcircle, resulting in a hemisphere
    0.0 > offset > -1.0: intersection a smallcircle, resulting in more than a hemisphere
    offset = -1.0:        tangent plane, resulting in the entire sphere
    offset < -1.0:           no intersection, resulting in the entire sphere

4.1.6 Convex

A convex polygon, or set of convex polygons, resulting from two or more constraints.
Note that convexes and polygons can easily be converted into each other, with the proviso that a set of constraints resulting in multiple disconnected regions needs to be translated into a union of multiple polygons, while a concave polygon needs to be translated into a union of convexes.

4.1.7 Convex hull

Specified by a set of points, this is the smallest convex that will include all those points.

4.2 Operations

This is, on purpose, a minimum but sufficient set of operations. Additional operations (such as XOR or difference) may be constructed by combining any of these three.

4.2.1 Negation

Unary operator. All of space is selected, except the region that is the operand. The boundary is probably also excluded. Logical NOT operation.

4.2.2 Union

Operand: two or more regions. All points that lie in one or more of the operands are selected; logical OR operation.

4.2.3 Intersection

Operand: two or more regions. Only points that lie in all of the operands are selected; logical AND operation. Here one has to be careful about boundaries: two regions that only share a boundary should probably have an empty intersection.

4.3 Desirable functions

Applications dealing with regions need tools to perform the following operations on regions:

4.3.1 Logical operations:

- is a point inside a region?
- is a point outside a region?
- is a region wholly contained in another region?
- are two regions disjoint?

4.3.2 Information on a single region:

- exterior extent: smallest (unrotated) rectangle/circle containing a region
- interior extent: largest (unrotated) rectangle/circle fitting inside a region
- the area of a region

4.3.3 Interface operations:

- convert region to pixel mask
- generate pixel list

5 Projection Object

As a placeholder, we can define the following projection element type. I think it contains the basic information but will undoubtedly need to be extended.

        <xs:simpleType name="projectionType">
            <xs:restriction base="xs:string">
            <xs:enumeration value="TAN"/>
          <xs:enumeration value="SIN"/>
            <xs:enumeration value="STG"/>
              <xs:enumeration value="CAR"/>
          </xs:restriction>
        </xs:simpleType>
      <complexType name="coordProjectionType">
<sequence>
       <element name="Projection" type="projectionType"/>
          <element name="RefPos" type="IDREF"/>
          <element name="RefPix" type="crd:doubleArrayType"/>
      <choice>
              <xs:element name="CoordPixsize" type="crd:coordValueType"/>
            <xs:element name="CoordPixsize" type="crd:coord2SizeType"/>
    <xs:element name="CoordPixsize" type="crd:coord3SizeType"/>
         </choice>
    </sequence>
      </complexType>

6 Some more specifics

The following table attempts to explain the various elements in the Space-Time Schemas (src.xsd, coords.xsd, region.xsd) and their use in each of the five areas of application:

Resource description (especially the coverage portion)
The query (search location/area)
A table of catalog data
The observation location part of retrieved observational data
The observatory location part of retrieved observational data

The toplevel element, STCmetadata contains a choice of elements: 1 or 2 or 3 or 4+5.
R means "Required", O means "Optional", N/A means "Not Applicable". FOV is "Field Of View".
"-->" indicates a sub-element contained in the present sub-element.
There is an example of a resource description (Chandra Data Archive) and an ObservationLocation+ObservatoryLocation (Chandra observation 770). The VO region format is now included in the Schema.
Note also that something like the posScalarType is very well suited, too, to describe other data space axes, e.g., frequency/wavelength/energy.
Full documentation may be found at STC.html.

Element	Sub-element	Attribute	Data Type	Allowed Values	Default	Resource Description	Query	Catalog Table	Data: Observation	Data: Observatory
CoordSystem		ID	ID			R
	CoordFrame	coord_ref_frame	string		ICRS	R For casual use this does not matter (if the value is ICRS, FK5 or even FK4), but for serious use it should be provided; this attribute specifies the coordinate system (equatorial, ecliptic, galactic, etc.); if AZ_EL the position of the (ground-based) observatory is needed, or course; SPHERICAL_BODY allows specification of a longitude-latitude coordinate system on a solar system body specified by CoordRefPosition This element contains CoordEquinox and ((RefSystem and StandardPole) or (Pole_Zaxis and Xaxis))				R Should be EARTH for ground-based observatories when time is given in LST or coordinates in AZ_EL
	--> CoordEquinox		string	B or J, followed by a year	J2000.0	O Part of CoordFrame Should be generally J2000 for observations, but should be absent for ICRS Pre-1984 dates should be combined with B and FK4 and earlier; post-1984 dates with J and FK5 or ICRS
	--> RefSystem	bodyname	string	ICRS FK5 FK4	ICRS	R The reference frame
	--> StandardPole		string	EQUATORIAL ECLIPTIC GALACTIC SUPERGALACTIC	EQUATORIAL	O The known Pole definitions
	--> Pole_Zaxis		coords			R The position of the pole (in a known coordinate frame), for a newly defined reference system
	--> Xaxis		coords			R The coordinates of the origin of longitude (only in combination with PolePos)
	CoordRefPosition		refPositionType			R Either RefPos or CoordOrigin
	--> RefPos		string	GEOCENTER BARYCENTER HELIOCENTER TELESCOPE MOON EMBARYCENTER MERCURY VENUS ...	TELESCOPE	R In most cases it will not matter; exceptions: 1) observations of objects in the near field (i.e., solar system) for a telescope that moves far from the earth; 2) value TELESCOPE is required for data in AZ_EL coordinate systems 3) coordinate systems on other solar system bodies				O Will be GEOCENTER in most cases; exceptions for observatories located on other solar system bodies
	--> CoordOrigin		coords			R Coordinates of reference frame origin
	TimeScale		string	TT TDT ET TDB TCG TCB TAI IAT UTC LST	TT	R TT is the preferred time_scale, though UTC may be more common; it is recommended that this attribute be specified; LST requires special care: the observatory position should be properly specified; use of TCG and TCB is unlikely in the near future. The presence of TimeScale in CoordSystem is purely informational, since it is included in AstronTime as well.
	TimeRefPosition		refPositionType	See: CoordRefPosition		R Not important for resource description	R	R Important for high time precision; it makes sense to combine BARYCENTER only with time_scale TDB or TCB
	PlanetaryEphem		string	JPL-DE200 JPL-DE405		O Only needed when transformations across the solar system are made, such as barycenter corrections
	CoordFlavor	coord_naxes	int	1 2 3	2	R This indicates how many spatial coordinate axes to expect, exclusive of time, velocities, and Doppler velocity or redshift
		coord_type	string	SPHERICAL CARTESIAN UNIT_SPHERE	SPHERICAL	R This indicates what coordinates to expect in the Coords element; 3D_SPHERICAL is a longitude and latitude, combined with a radius, such as RA, Dec, and distance, or geographic longitude and latitude and distance from the GEOCENTER
		coord_vel	boolean	true false	false	O Velocities are expected to be present for all spatial coordinates (coord_naxes) when specified
	--> Doppler	value_type	string	VELOCITY REDSHIFT		R Part of CoordType, indicating presence of Doppler velocity or redshift as the last coordinate; note that Doppler velocity is not the same as velocity along the radial coordinate
	---> DopplerDefinition		string	OPTICAL RADIO RELATIVISTIC	OPTICAL	R Doppler velocity is not (necessarily) a physical velocity, but a formalism to express a red- or blueshift as something like a radial velocity; most, but not all, Doppler velocities use the optical convention (delta-lambda/lambda0); if one sees LSR it's more likely to be the radio convention (delta-nu/nu0)
	---> DopplerReference		string	OBSERVATORY GEOCENTER HELIOCENTER BARYCENTER LSR GALACTIC- _CENTER SUPER- _GALACTIC- _CENTER	BARYCENTER	R These references attempt to correct the measured Doppler velocity for the observer's motion with respect to these various standards of rest; and they are just that: an agreed upon standard of rest; hence they should not be foolishly used, such as supergalactic Doppler velocities for Galactic objects
AstronTime						A general purpose astronomical time type that consists of (ISOTime or JDTime or MJDTime or RelativeTime or Reference) and TimeScale. A RelativeTime must be accompanied by (ISORefTime ot JDRefTime or MJDRefTime); a Reference may be acompanied by one of those.
	ISOTime		dateTime			Date and time in ISO8601 format (restricted to yyyy-mm-ddThh:mm:ss.sss)
	JDTime		double			Julian date
	MJDTime		double			Modified Julian date
	RelativeTime		double			Relative time, must be accompanied by ISORefTime or JDRefTime or MJDRefTime
		unit	string	s d
	ISORefTime		dateTime			Zero point for RelativeTime
	JDRefTime		double			Zero point for RelativeTime
	MJDRefTime		double			Zero point for RelativeTime
	Reference		IDREF			Reference to a time field, must be accompanied by ISORefTime or JDRefTime or MJDRefTime if time_base=relative
		time_base	string	ISO8601 JD MJD relative		Indicates the format of Reference
		unit	string	s d
	ISORefTime		dateTime			Zero point for Reference
	JDRefTime		double			Zero point for Reference
	MJDRefTime		double			Zero point for Reference
	TimeScale		string	TT TDT ET TDB TCG TCB TAI IAT UTC LST	TT	TimeScale for AstronTime
Coords		ID	ID			R This element is needed with actual coordinate values when the area or coverage is defined by CircleOrSphere; a second instance, CoordSpec is required without coordinate values, to set resolutions and errors		R It consists of either a CoordFile or a sequence of Time, Space, Velocity, Redshift, where Space is a choice of PosScalar, Pos2Vector, Pos3Vector, and Velocity is a choice of VelScalar, Vel2Vector, Vel3Vector; the exact configuration is controlled by CoordFlavor in CoordSys
		coord_system_id	IDREF			R
	CoordFile		FITS			O The columns in the FITS CoordFile will be expected to correspond to CoordType and Time needs to be included				O Most likely use is here as an orbit ephemeris file
	Time		coordTimeType			O May be omitted if not relevant		O Required if CoordFile not used; it contains at least one of Name, CoordValue, CoordError, CoordResolution, CoordSize, CoordPixSize; not that each of these has its own unit attribute
	--> Name		string			O Place holder (for UCD?)
	--> CoordValue		astronTimeType			N/A	N/A	O Actual value
	--> CoordError		coordTimeValueType			O Typical error or uncertainty in Time for data in the resource	O Desired error or uncertainty in Time	O Typical error in Time
	---> Value	unit	double			R coordTimeValueType is a Value or a Reference; attribute unit is "s" or "d"
	---> Reference	unit	IDREF
	--> CoordResolution		coordTimeValueType			O Typical ime resolution for data in resource	O Desired time resolution	O Typical ime resolution
	--> CoordSize		coordTimeValueType			O Typical extent in Time if applic	O Desired extent in Time	O Extent in Time
	--> CoordPixsize		coordTimeValueType			O Typical time pixel size	O Desired time pixel size	N/A	O Time pixel size if applicable	N/A
	PosScalar		coordScalarType			O A 1-D coordinate; consists of at least one of Name, CoordValue, CoordError, CoordResolution, CoordSize, CoordPixsize; note that each of these has its own unit attribute
	--> Name		string			O Place holder (for UCD?)
	--> CoordValue		coordValueType			R Only required for CircleOrSphere		R Actual coordinate value
	---> Value		double			The choice between Value, Value60 (sexagesimal string), and Reference makes up the coordValueType
	---> Value60		string
	---> Reference		IDREF
	--> CoordError		coordValueType			O Typical absolute uncertainty (1 sigma) in this coordinate for data in this resource	O Maximum absolute uncertainty permitted	O Absolute uncertainty (1 sigma) in CoordValue
	--> CoordResolution		coordValueType			O Typical resolution (FWHM) in this coordinate for data in this resource	O Query is for information with resolution in this coordinate that is no worse than CoordResolution	N/A	Resolution (FWHM) in this coordinate	N/A
	--> CoordSize		coordValueType			O Typical FOV size in this coordinate for image data in this resource	O For image data queries: minimum FOV size in this coordinate	O Measured object size (FWHM) in this coordinate, usually assuming an elliptical Gaussian	N/A
	--> CoordPixsize		coordValueType			O Typical coord pixel size. if applicable	O Desired coord pixel size	N/A	O Coord pixel size, if applicable	N/A
	Pos2Vec		coord2VectorType			O Identical to PosScalar, except that all doubles are now lists of two doubles and strings are lists of two strings; errors, resolutions, and sizes may have position angles, or may be expressed by 2x2 matrices
	Pos3Vec		coord3VectorType			O Identical to PosScalar, except that all doubles are now lists of three doubles and strings are lists of three strings; errors, resolutions, and sizes may have position angles, or may be expressed by 2x2 matrices
	VelScalar		coordScalarType			O 1-D velocity
	Vel2Vec		coord2VectorType			O 2-D velocity vector
	Vel3Vec		coord3VectorType			O 3-D velocity vector
	Redshift		coordScalarType			O Redshift or Doppler velocity (depending on Doppler in CoordFlavor)
CoordArea						R Resource coverage: This element describes the coverage of the resource; the meaning is that OUTSIDE this area there is a guarantee that NO DATA will be found	R Search area: This element describes the area over which the resource is to be searched for data	O Catalog coverage: When catalog data are returned, this element may indicate the area over which the data are complete	R FOV: This element describes the FOV of the data returned	N/A
		ID	ID			R A CoordArea will consist of a TimeInterval plus: a RegionFile or: a Region object or: a CoordInterval for each spatial coordinate or: a CircleOrSphere element for the spatial coordinates Intervals for (Doppler) velocities may optionally be added
		coord_system_id	IDREF			R				N/A
	TimeInterval					R Specify the Time part of the Space-Time CoordArea				N/A
		start_include	boolean	true false	true	O Include the start time?				N/A
		stop_include	boolean	true false	true	O Include the stop time?				N/A
	--> StartTime		astronTimeType			O Start time of interval				N/A
	--> StopTime		astronTimeType			O Stop time of interval				N/A
	RegionFile		FITS			O The spatial part of the CoordArea is defined in a FITS Region File				N/A
	CoordInterval					O Specify the CoordArea interval for spatial coordinates; in one, two, or three coordinates				N/A
		lo_include	boolean	true false	true	O Include lower limit?				N/A
		hi_include	boolean	true false	true	O Include upper limit?				N/A
	--> LoLimitScalar		coordValueType			O Lower limit of interval for single coordinate				N/A
	--> HiLimitScalar		coordValueType			O Upper limit of interval for single coordinate				N/A
	--> LoLimit2Vec		coord2ValueType			O Lower limit of interval for two coordinates				N/A
	--> HiLimit2Vec		coord2ValueType			O Upper limit of interval for two coordinates				N/A
	--> LoLimit3Vec		coord3ValueType			O Lower limit of interval for three coordinates				N/A
	--> HiLimit3Vec		coord3ValueType			O Upper limit of interval for three coordinates				N/A
	CircleOrSphere					O Specify the spatial part of a CoordArea as a circle (2D) or sphere (3D)				N/A
		radius_unit	string			R Units of the circle or sphere radius				N/A
	--> Radius		double			R Radius of circle or sphere				N/A
	--> Center		coordsType			R Center of the circle or sphere				N/A