Schema description should include units.

[ijiraq]

The schema descriptions that appear in the TAP services should tell the user what UNITs quantities in the table are expressed in. e.g. Plane.energy_bounds_lower is described as: 'lower bound on energy axis (barycentric wavelength)' which is helpful, but without knowing what units those are (nm?) the user is left to guess.

One might thing that just declaring the entire table as following some convention (cgi? mks?) would be sufficient) but reminding the user with good column descriptions would be more friendly.

[pdowler]

The tap_schema.columns table has a column named unit that conveys the units for all columns where that is applicable.

We don't include units in the description because redundancy is the first step to inconsistency :-)

[ijiraq]

I guess the issue I was raising is that to make the TAP service useful to astronomers we need to make it clear how they can determine what units their queries should be in without making them hunt around for where things might be.

When using 'cadc-tap' to request the structure of that caom2.Observation table, for example, one gets the content below. I'm not sure how the user of the service is supposed to know that the units of Observation.targetPosition.coordinates.cval1 is expressed in degrees?

Also, why is the column called 'crval1' ? Doesn't that make an assumption about CRPIX1, perhaps the column is supposed to be 'longitude' ?

(base) pheonix:~ jjk$ cadc-tap schema -s argus caom2.Observation

caom2.Observation: the main CAOM Observation table

Name Type Index Description

---

observationURI caom2:Observation.uri Y unique URI for this observation
obsID caom2:Observation.id Y unique observation identifier
collection caom2:Observation.collection Y data collection this observation belongs to
observationID caom2:Observation.observationID Y collection-specific unique observation identifier
algorithm_name caom2:Observation.algorithm.name N algorithm that defines the observation( exposure for simple, grouping algorithm for composites)
type caom2:Observation.type N type of data collected (e.g. FITS OBSTYPE header)
intent caom2:Observation.intent N intended purpose of data (one of: science, calibration)
sequenceNumber caom2:Observation.sequenceNumber N sequence number assigned by the observatory
metaRelease caom2:Observation.metaRelease N date the metadata for an observation is public (UTC)
proposal_id caom2:Observation.proposal.id Y collection-specific unique proposal identifier
proposal_pi caom2:Observation.proposal.pi N proposal principal investigator
proposal_project caom2:Observation.proposal.project N project that created/acquired the observation
proposal_title caom2:Observation.proposal.title N proposal title
proposal_keywords caom2:Observation.proposal.keywords N proposal keywords (separated by |)
target_name caom2:Observation.target.name N name of intended target
target_type caom2:Observation.target.type N classification of intended target
target_standard caom2:Observation.target.standard N intended target is a standard (0=false, 1=true)
target_redshift caom2:Observation.target.redshift N redshift of intended target
target_moving caom2:Observation.target.moving N flag for moving target
target_keywords caom2:Observation.target.keywords N target keywords (separated by |)
targetPosition_coordinates_cval1 caom2:Observation.targetPosition.coordinates.cval1 N longitude of target position
targetPosition_coordinates_cval2 caom2:Observation.targetPosition.coordinates.cval2 N latitude of target position
targetPosition_coordsys caom2:Observation.targetPosition.coordsys N coordinate system for target position
targetPosition_equinox caom2:Observation.targetPosition.equinox N equinox of target position coordinate system
telescope_name caom2:Observation.telescope.name N name of telescope used to acquire observation
telescope_geoLocationX caom2:Observation.telescope.geoLocationX N x component of geocentric location of telescope
telescope_geoLocationY caom2:Observation.telescope.geoLocationY N y component of geocentric location of telescope
telescope_geoLocationZ caom2:Observation.telescope.geoLocationZ N z component of geocentric location of telescope
telescope_keywords caom2:Observation.telescope.keywords N telescope keywords (separated by |)
requirements_flag caom2:Observation.requirements.flag N flag describing satisfied proposal requirements (possible values: fail)
instrument_name caom2:Observation.instrument.name N name of instrument used to acquire observation
instrument_keywords caom2:Observation.instrument.keywords N instrument keywords (separated by |)
environment_seeing caom2:Observation.environment.seeing N atmospheric seeing (FWHM)
environment_humidity caom2:Observation.environment.humidity N humidity at telescope during observation
environment_elevation caom2:Observation.environment.elevation N elevation above horizon (0 to 90)
environment_tau caom2:Observation.environment.tau N zenith optical depth
environment_wavelengthTau caom2:Observation.environment.wavelengthTau N wavelength at which Tau has been measured
environment_ambientTemp caom2:Observation.environment.ambientTemp N ambient temperature telescope during observation
environment_photometric caom2:Observation.environment.photometric N conditions were photometric (0=false, 1=true)
members caom2:Observation.members N members of a composite observation (space-separated list of Observation URIs)
typeCode caom2:Observation.typeCOde N single character code to denote type: S(impleObservation) or C(ompositeOvservation)
lastModified caom2:Observation.lastModified N timestamp of last modification of this row
maxLastModified caom2:Observation.maxLastModified N timestamp of last modification of this observation
metaChecksum caom2:Observation.metaChecksum N checksum of the metadata in this entity (URI of the form :)
accMetaChecksum caom2:Observation.accMetaChecksum N checksum of the metadata in this entity+children (URI of the form :)

(45 rows affected)

Foreign Keys: Foreign Keys for table

Target Table Target Col From Column Description

---

caom2.ObservationMember compositeID obsID standard way to join caom2.Observation (CompositeObservation) and caom2.ObservationMember [join table]

(1 row affected)

On Nov 28, 2019, at 3:04 PM, Patrick Dowler notifications@github.com wrote:

The tap_schema.columns table has a column named unit that conveys the units for all columns where that is applicable.

We don't include units in the description because redundancy is the first step to inconsistency :-)

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or unsubscribe.

[pdowler]

On the above cadc-tap output, the "Type" column there is useless to normal users as it is not a type in the normal sense. That is the VO-DML ID so a reference to a specific field in the data model. The schema + table + column name has the same info as the model ID with a syntactic mapping to make valid database names.

It would be much better to tell users the datatype,arraysize,xtype from the tap_schema -- those 3 together are the VOTable and TAP "datatype".

[pdowler]

As for targetPosition_cval1 that is the name of the field in the Point class so the correct column name. It is cval (coordinate value) and not crval (coordinate reference value).

The units are specified in a "profile" and not in the model directly. We currently have the http://www.opencadc.org/caom2/interoperable-profile.html

The TAP service uses the interoperable profile and the units are available in the "unit" column of the tap_schema, so the above table info output should include that column along with the more useful datatype info.

[ijiraq]

@andamian : Do we have agreement then that we modify the information that cadc-tap provides along the lines that @pdowler suggests? Sounds right to me.

@pdowler : Separate question about the 'cval1' and 'cval2' colums. Are they well described (ie, what coordinate system them reference) in those other information provided in the tap_schema?

[andamian]

@ijiraq - easy-peasy - or it seems like. This can be closed as #130 is tracking it now.

[ijiraq]

I think we don't close this until https://github.com/opencadc/cadctools/issues/130 has been resolved. This issue contains the information about what is being asked for.

Still waiting to learn if the cval1/2 description is useful in tap_schema.