SSAmples

[Jonathan McDowell]

Markus wrote:
> Hello Doug and Jonathan,

Hi Markus, I have taken a look at your comments and modified

http://hea-www.harvard.edu/~jcm/vo/docs/spec.html

in an attempt to respond to them. Detailed replies below.
I have also modified the xml schema slightly and made an
XML instance example that is equivalent to the VOTABLE 
instance, in an attempt to show how one might perform
the equivalence mapping between the 'pure xml' and VOTABLE
representations both in this case and in a general way.
I'm not sure what I have done is even close to workable, so
I hope you and Doug and Tamas will take a good look.

I've tried to get my VOTABLE instance up to the latest definition.
I note in your sample example you use PARAMref; I don't see why this
is a good idea, it seems to be redundant since PARAM is allowed directly
within a GROUP, so I've stayed with not using PARAMref.


The older versions are now at

http://hea-www.harvard.edu/~jcm/vo/docs/spec040805.html
http://hea-www.harvard.edu/~jcm/vo/docs/spec040719.html

> 
> Also, the new STC was not taken into account and I'm open to suggestions how to 
> map it to VOTable speak. Nonetheless, there are a number of points that the 

I plan to look at this soon; let's defer that until we have the rest sorted out.



> I. Inconsistencies between DM V0.9 and SSA interface as of Boston in May
> ========================================================================

These are really mostly inconsistencies between DM V0.9 and
the "Data Model Summary (May 20)" in Doug's email which also summarized
the SSA interface.

 
> 1. Target.CreationType values {Archival, Dynamic, Custom} in DM differ from
>     SSA interface Sed.CreationType {Atlas, Virtual}. My sample sticks to the DM
>     assuming that "Atlas" maps to "Archival" and "Virtual" to "Dynamic+Custom".

Yes, I think Doug changed these names to the new (DM) values, possibly to 
better match SIAP?

> 2. Target.pos exists in the DM only. Presumably this is the search position, 
> whereas each segment has an actual pointing/object position?
> 6. DM has a Location object in each Segment rather than a global one in the 
> Target object. My SSAmple sticks to the DM.

Well, I would say the object has an actual position, and this is what I
intend by target.pos. It's true that as well as this, each segment has
an actual pointing position, or more accurately an actual pointing field
of view that we integrate over; these are given in the Coverage.Location
(and Coverage.Region) for each segment. As you imply, you can't
guarantee that the Location is the same for each Segment.

Another comment on Target: the whole first table giving the global info,
including Target, is only a table because you're not allowed to have
GROUP elements directly under RESOURCE. It would be cleaner if you could
just eliminate the first <TABLE> and </TABLE> and have those PARAM and
GROUP values directly under RESOURCE. Is the reason VOTable doesn't
allow this that GROUPs could potentially include FIELDS?


> 3. SNR is in object "Derived" in the DM and not in "Target"

Right. It was in "Target" in Doug's "Data Model Summary".
But it's really a derived data quantity, and when we get a catalog
data model we'll want that connection.

> 4. Flux.Npts is missing in the DM. We probably don't need it(?)

I agree - I think applications can derive it trivially.

> 5. SpectralCoord.deReddened and SpectralCoord.correlated are missing; These 
> things could go into a new object SpectralCoord.Quality or is this what 
> CustomParams is about?

The "dereddened" is a particularly significant issue, because it is one
of a whole family of possible annotations which really qualify the UCD.
It helps answer the question "What are these numbers", you can either
think of it as  "What corrections have been applied to the data" or you
might think of it as "Is this the SED as it hits the Earth's atmosphere
or is it the SED measured just outside the source?". The first way of
thinking is related to provenance, the second way of thinking is closer
to UCD. 

I propose that we NOT include these in version 1.0 of the SSAP, pending
further discussion of the bigger issue.

One important issue I pull out here:

> If Target is contained in the SED object then the utypes should be SED.Target.* 
> instead of Target.*

So, I have made the assumption that the syntax for UTYPE should be:

- we define a namespace, xmlns:NS=URI which defines a model for an object foo
  containing various subobjects
- a fully qualified utype is of the form
   NS:foo.a.b.c.d  where a,b,c,d are subobjects in the hierarchy
BUT (I propose)
- if a GROUP, RESOURCE or TABLE element has utype = NS:foo.a.b
  and if that element contains other elements (e.g. GROUP, PARAM, FIELD)
  and if those elements have a type   NS:c.d 
  whose leading element is not foo, then the context is taken
  from the enclosing element and NS:c.d is resolved to NS:foo.a.b.c.d
 
  Thus in the example given GROUP utype="sed:Target" is inside TABLE utype="sed:SED"
  and is understood to refer to that context, i.e. Target = SED.Target

Should we have this or a similar 'relative utype path' convention?
Is this good xml? Or do we require a full utype path for every utype?
I know Doug expressed a desire that the full path not be required.


> II. Further Comments/Errata
> ===========================
> 
> a)
> the value attribute of a PARAM element is supposed to contain the datum; hence 
> the value attribute is mandatory; all PARAM elements need to be modified 
> accordingly

Fixed


> b)
> a vector can be expressed as a space separated list but not comma separated as 
> in PARAM Coverage.Location.Sky

Fixed

> 
> c)
> GROUPing works differently: use PARAMref and FIELDref; all GROUP elements need 
> to be modified accordingly

Fixed

> 
> d)
> in VOTable examples UCD words are colon separated instead of semicolon separated

Fixed.

> 
> e)
> Coverage.Extent.Time is given as time.expo in table 5.1 and time.interval in 
> the sample VOTable
> One could allow both, of course: time.expo for the net exposure time and 
> time.interval denotes the difference between start time of the first exposure 
> and the end time of the last subexposure.

Settled on time.expo.

> 
> f)
> Why are "Sky" and "Time" encoded as subGROUPs in object "Coverage.Location" 
> instead of PARAM elements? In other words, why does Extent and Location have a 
> different substructure although they are similarly defined in table 5.1?

The idea was that these would be later extended to have accuracy values.
But we'll keep them PARAM for now to be consistent with the xsd schema.


> 
> g)
> DataID.Date: append "Z" for UT to time string; according to ISO standard it's 
> considered local time otherwise

ok

> 
> h)
> If Target is contained in the SED object then the utypes should be SED.Target.* 
> instead of Target.*

See discussion above.


> i)
> Was it intentional to define Target.VarAmpl (src.var.amplitude) as well as 
> Derived.VarAmpl (stat.ampl)?

Yes (I think). The first is from some external source giving background
context to the obs, the second is from the current dataset saying
what the variation is in *this* data.

> 
> j)
> How about defining Flux.Quality using the VALUES/OPTION element (see example)?
> Given this encoding is there really a need for Flux.Quality.N with n={0,1, 
> ...}? Or, is the intention to combine quality flags? If so, how?

I'm not enthusiastic about the use of the VALUES/OPTION, personally.
Particularly for things like BARYCENT it seems like overkill to list all the options
in each document instance.  

In the particular case of Quality, I'm not sure what you mean by "combine quality
flags". But I think the intention is to have

<GROUP utype="Quality">
 <PARAM name="WaveQuality" utype="Quality.1" ucd="meta.code.qual;em.wl" value="1">
  <DESCRIPTION>Quality flag for wavelength value</DESCRIPTION>
 <PARAM name="AstrometricQuality" utype="Quality.2" ucd="meta.code.qual;pos.eq" value="4">
  <DESCRIPTION>Quality flag for astrometric solution</DESCRIPTION>
</GROUP>

with no overall single integer "quality value".

> 
> k)
> We do lack suitable utypes for the TABLE element in order to define the type of 
> Segment that follows: { Sed, Spectrum, TimeSeries }
> "Spectrum" as the utype of the 1st table is ambiguous since the root object is 
> SED in the DM diagram

The utype is  SED.Spectrum; the model is the same for spectrum, photometry, time series
so the utype is the same. We should use a UCD or an attribute to distinguish the cases. 
I have added a SegmentType parameter to the Segment object.

> 
> l)
> Does the percent "%" in %Contact and %Contact.Email have a particular meaning?
> Can we remove the dot in Contact(.)Email ?

The percent came from some earlier version of the registry doc. The new version
of the doc has Contact as an object with two sub members and I have made this fix.

> 
> m)
> More generally, how about removing dots in field names?
> SED.Bandpass.Min => SED.BandpassMin
> SED.Bandpass.Max => SED.BandpassMax

There's a real difference here: SED.Bandpass.Min implies that there
is an SED.Bandpass object which may have new fields added to it later.
I've changed it to BandpassMin since we don't have such an object yet.

> 
> n)
> The closing TR elements are missing in TABLEDATA of the DM sample

ok


> 
> o)
> replace "Barycentric" by 8-char tag "Barycent" in sample VOTable in the DM doc

ok

> 
> 
> III. Suggestions for assignment of UCDs
> =======================================
> SED.NSegments		  meta.number (instead of arith.factor)

ok 

> SED.SegmentType	          meta.code

ok

> # move CreationType to DataID object, otherwise model and observational data 
> cannot be combined in one VOTable doc.

OK

> SpectralCoord.deReddened  meta.code.qual
> SpectralCoord.correlated  meta.code.qual

ok, modulo issues about the items themselves.

> Spatial.Resolution	  instr.ang-res

ok - although it may not be instrumental resolution (could be resampled)

> Time.Accuracy.BinSize	  time.period

oooh... I know what you are saying but UCD=time.period doesn't make me think
of a bin size. Perhaps I could live with  "time.period;instr".

Thanks!!
 Jonathan