Skip to content

Commit 0436afe

Browse files
msdemleimsdemlei
committed
Review of species list addition.
Important: this changes the utype of the lines tables. This also adds registry considerations and a use case.
1 parent 724170f commit 0436afe

File tree

2 files changed

+89
-50
lines changed

2 files changed

+89
-50
lines changed

‎LineTAP.tex‎

Lines changed: 74 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -102,13 +102,15 @@ \section{Introduction}
102102
data through a VO service employing such a simplified relational
103103
mapping. The resulting table schema is presented in
104104
section~\ref{sect:quantities}, while the mapping between our columns and the
105-
VAMDC-XSAMS Data Model is given in section~\ref{sect:mapping}.
105+
VAMDC-XSAMS Data Model is given in section~\ref{sect:mapping}.
106106

107-
As the InChi number for referencing molecules can become complicated for use,
108-
a second table, the \textit{species table}, ist generated from the LineTap table
109-
containing the species InChiNumber, name and formula. This table can be searched
110-
before querying LineTap to find the corresponding InChi of a certain molecule. In
111-
Section \ref{sect:speciestable} a description of this table and it's use can be found.
107+
During the development of the standard, a major problem in molecular
108+
spectroscopy turned out to be species nomenclature. The core LineTAP
109+
table sidesteps this problem by identifying species using IUPAC standard
110+
InChIs, a choice unpopular with many practitioners. To facilitate the
111+
use of colloquial species designations (``ethyl alcohol''), this
112+
specification also defines a \textit{species table} associating common
113+
names and sum formulas with InChIs in section \ref{sect:speciestable}.
112114

113115
When accessed using the Table Access Protocol TAP
114116
\citep{2019ivoa.spec.0927D}, the tables can be queried using the
@@ -117,7 +119,7 @@ \section{Introduction}
117119
applications. Line databases accessible in this way can be registered
118120
in the VO Registry. The detailed rules for this registration, and
119121
recommendations for how to discover LineTAP services, are given in
120-
section~\ref{sect:regmatters}.
122+
section~\ref{sect:regmatters}.
121123

122124
\subsection{Role within the VO Architecture}
123125

@@ -226,6 +228,13 @@ \subsection{Credit}
226228
repository of line data, it should be as simple as possible for users to
227229
give credit to the contributors of line data.
228230

231+
\subsection{Resolution of Molecule Designation}
232+
\label{uc:resolution}
233+
234+
A researcher wants to find lines for the molecule they have been calling
235+
``Methyl Mercaptan'' or designated by a pseudo-structural formula like
236+
\verb|CH3SHv=0| for a long time.
237+
229238

230239
\subsection{Non-Use Cases}
231240

@@ -389,40 +398,45 @@ \section{Spectral Line Data}\label{sect:quantities}
389398
\section{Species Table}\label{sect:speciestable}
390399
\label{ref:speciestable}
391400

392-
The Species Table, listed in Table~\ref{tab:spcols}, is used to facilitate the
393-
referencing of molecules. As formulas and names can be ambiguous, LineTAP
394-
uses InChi/InChIkey so they are uniquely identified. But it's not quite human readable.
395-
The Species Table contains a mapping between common names and formulas and
396-
InChI numbers. It should be generated by the data providers on all the species
397-
contained in the LineTap tables. It is also a list of all species that are provided by
398-
the LineTap service, so a client can search this table first to find out if this service contains a
399-
certain molecule.
401+
The species table is used to facilitate the referencing of molecules. As
402+
there are many summary formulas and colloquial molecule names for common
403+
species (and more than one species may correspond to a given summary
404+
formula and even colloquial name), the resolution of such identifiers to
405+
InChIs is generally non-trivial.
406+
407+
LineTAP's species table contains a mapping between common names and
408+
summary formulas and InChIs. It should be populated by data providers
409+
publishing molecule data to the best of their knowledge. It is
410+
explicitly possible to associate multiple names with a single InChI.
411+
There is no explicit relationship between a species table and LineTAP
412+
tables on a given service, i.e., the presence of a species in the the
413+
species table is not a guarantee that data on it is available from any
414+
table in the service.\todo{Is there a use case for having InChI in here?
415+
I'd say InChIKey is good enough.}
400416

401417
\begin{table}[hpt]
402418
\hskip -0.05\linewidth
403419
\begin{tabular}{p{0.43\linewidth}cp{0.5\linewidth}}
404420
\sptablerule
405421
\textbf{Name [Unit]} \ucd{UCD}&\textbf{Type}&\textbf{Description}\\
406422
\sptablerule
407-
% GENERATED: python3 make-columns-table.py
423+
% GENERATED: python3 make-species-table.py
408424
\texttt{inchikey} \hfil\break\ucd{} & text & \raggedright InChIKey of this species\tabularnewline
409425
\rowsep
410426
\texttt{inchi} \hfil\break\ucd{} & text & \raggedright InChI of this species\tabularnewline
411427
\rowsep
412428
\texttt{name} \hfil\break\ucd{} & text & \raggedright A common name of this species\tabularnewline
413429
\rowsep
414-
\texttt{formula} \hfil\break\ucd{} & text & \raggedright Chemical formula of this species\tabularnewline
415-
\rowsep
416-
\texttt{stoichiometricformula} \hfil\break\ucd{} & text & \raggedright Chemical formula of this species\tabularnewline
430+
\texttt{formula} \hfil\break\ucd{} & text & \raggedright Chemical formula of this species in some free-ish notation\tabularnewline
417431
\rowsep
418432
\texttt{source\_id} \hfil\break\ucd{} & text & \raggedright VAMDC identifier of the origin of this mapping\tabularnewline
433+
419434
% /GENERATED
420435
\sptablerule
421436
\end{tabular}
422437
\caption{The columns that make up the Species Table. }
423438
\label{tab:spcols}
424439
\end{table}
425-
The columns inchikey, name and formula are indexed to the columns of same name in the LineTap table.
426440

427441

428442
\section{Protocol}
@@ -473,7 +487,6 @@ \subsection{Use Case Examples}
473487

474488
In this section, we give queries addressing the use cases from
475489
section~\ref{sect:use-cases}.
476-
\todo{add example using species table}.
477490

478491
\subsubsection{Identifying a Single Line}
479492

@@ -587,6 +600,24 @@ \subsubsection{Characterising a Service's Data Holdings}
587600
GROUP BY inchi
588601
\end{lstlisting}
589602

603+
\subsubsection{Searching With Trivial Molecule Names}
604+
605+
Searching with trivial names as discussed in use
606+
case~\ref{uc:resolution} would often be a two-step process where clients
607+
ask the researcher which InChI would correspond the the species they
608+
were looking for. In simple cases, however, a single joined query can be
609+
run, too.
610+
611+
% please-run-a-test
612+
\begin{lstlisting}[language=SQL]
613+
SELECT
614+
*
615+
FROM casa_lines.line_tap
616+
JOIN species.main as s USING (inchikey)
617+
WHERE s.name='Methylidynium'
618+
\end{lstlisting}
619+
620+
590621
\section{Mapping from VAMDCXSAMS}
591622
\label{sect:mapping}
592623

@@ -711,16 +742,13 @@ \section{LineTAP and the VO Registry}
711742

712743
\subsection{Registering LineTAP-conforming Tables}
713744

714-
LineTAP tables are registered using VODataService \citep{2021ivoa.spec.1102D}
745+
LineTAP line tables are registered using VODataService \citep{2021ivoa.spec.1102D}
715746
tablesets, where the table utype is set to
716-
$$\hbox{\verb|ivo://ivoa.net/std/linetap#table-1.0|}.$$
747+
$$\hbox{\verb|ivo://ivoa.net/std/linetap#lines-1.0|}.$$
717748

718-
The tableset is normally contained in a VODataService \xmlel{CatalogService}
719-
record with a TAP capability, and this capability normally is an auxiliary
720-
capability as per DDC \citep{2019ivoa.spec.0520D}. For one-table
721-
services a full TAPRegExt \citep{2012ivoa.spec.0827D} capability is also
722-
allowed; other resource types can be used for registration as
723-
appropriate.
749+
The tableset is contained in a VODataService \xmlel{CatalogResource}
750+
record with a TAP auxiliary capability
751+
as per DDC \citep{2019ivoa.spec.0520D}.
724752

725753
Further capabilities, for instance for full VAMDC or legacy SLAP
726754
services, may be given in the same record.
@@ -760,7 +788,7 @@ \subsection{Registering LineTAP-conforming Tables}
760788
<name>toss.ivoa_lines</name>
761789
<title>TOSS</title>
762790
<description> The LineTAP version of...</description>
763-
<utype>ivo://ivoa.net/std/linetap#table-1.0</utype>
791+
<utype>ivo://ivoa.net/std/linetap#lines-1.0</utype>
764792
...
765793
</table>
766794
\end{lstlisting}
@@ -772,6 +800,12 @@ \subsection{Registering LineTAP-conforming Tables}
772800
and is thus to be expected in most registrations of this type. Clients
773801
are advised to use the resource description for full text searches.
774802

803+
Species tables are registered in exactly the same way, except their
804+
utype is
805+
$$\hbox{\verb|ivo://ivoa.net/std/linetap#species-1.0|}.$$
806+
Data providers should only register line and species tables in one
807+
resource record if the species table really has the same metadata
808+
(description, author, source, etc) as the line table.
775809

776810
\subsection{Discovering LineTAP services}
777811

@@ -784,35 +818,34 @@ \subsection{Discovering LineTAP services}
784818
would return TAP access URLs and the table names:
785819

786820
\begin{lstlisting}[language=SQL]
787-
SELECT DISTINCT table_name, access_url
821+
SELECT table_name, access_url
788822
FROM rr.res_table
789823
NATURAL JOIN rr.capability
790824
NATURAL JOIN rr.interface
791825
WHERE
792-
table_utype LIKE 'ivo://ivoa.net/std/linetap#table-1.%'
826+
table_utype LIKE 'ivo://ivoa.net/std/linetap#lines-1.%'
793827
AND standard_id LIKE 'ivo://ivoa.net/std/tap%'
794828
AND intf_role='std'
829+
AND res_type='vs:catalogresource'
795830
\end{lstlisting}
796831

797-
The \texttt{DISTINCT} in the main query is a rough filter that removes
798-
entries duplicated because their tables are registred both in the main
799-
TAP record and in an auxiliary capability.
800-
801832
The regular expression in the utype match is to make sure minor version
802833
increments do not prevent service discovery; by IVOA versioning rules,
803834
all LineTAP services of minor version 1 can be operated by all LineTAP
804835
clients of version 1. We do not constrain the version of the TAP
805836
service. Clients may want to adapt the TAP discovery pattern to match
806837
their specific needs.
807838

808-
839+
Adapting the utype, this query will work analogously for species tables.
809840

810841
\appendix
811-
\section{Changes from Previous Versions}
842+
\section{Changes from WD-2023-03-23}
812843

813-
No previous versions yet.
814-
% these would be subsections "Changes from v. WD-..."
815-
% Use itemize environments.
844+
\begin{itemize}
845+
\item Adding the species table
846+
\item Changing the line table utype to \dots lines-1.0 (rather than
847+
\dots table-1.0 before).
848+
\end{itemize}
816849

817850

818851
\bibliography{ivoatex/ivoabib,ivoatex/docrepo, localrefs}

‎linetap.vor‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
<ri:Resource
2-
xsi:type="vstd:Standard"
3-
created="2020-10-26T11:44:00"
1+
<ri:Resource
2+
xsi:type="vstd:Standard"
3+
created="2020-10-26T11:44:00"
44
updated="2020-10-26T11:44:00"
55
status="active"
6-
xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
7-
xmlns:vstd="http://www.ivoa.net/xml/StandardsRegExt/v1.0"
8-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
6+
xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
7+
xmlns:vstd="http://www.ivoa.net/xml/StandardsRegExt/v1.0"
8+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
99
xmlns:ri="http://www.ivoa.net/xml/RegistryInterface/v1.0"
1010
xsi:schemaLocation="http://www.ivoa.net/xml/VOResource/v1.0
1111
http://www.ivoa.net/xml/VOResource/v1.0
@@ -16,7 +16,7 @@
1616

1717
<title>IVOA Relational model for Spectral Lines (LineTAP)</title>
1818
<shortName>linetap</shortName>
19-
<identifier>ivo://ivoa.net/std/linetap</identifier>
19+
<identifier>ivo://ivoa.net/std/linetap</identifier>
2020
<curation>
2121
<publisher>IVOA</publisher>
2222

@@ -61,8 +61,14 @@
6161
<endorsedVersion status="wd">1.0</endorsedVersion>
6262

6363
<key>
64-
<name>table-1.0</name>
65-
<description>The LineTAP table schema as of version 1.0.
64+
<name>lines-1.0</name>
65+
<description>The LineTAP lines table schema as of version 1.0.
66+
</description>
67+
</key>
68+
69+
<key>
70+
<name>species-1.0</name>
71+
<description>The LineTAP species table schema as of version 1.0.
6672
</description>
6773
</key>
6874

0 commit comments

Comments
 (0)