/[volute]/trunk/projects/dm/provenance/description/ProvenanceDM.tex
ViewVC logotype

Annotation of /trunk/projects/dm/provenance/description/ProvenanceDM.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4377 - (hide annotations)
Thu Sep 21 10:48:15 2017 UTC (4 years ago) by mnullmei
File MIME type: application/x-tex
File size: 11257 byte(s)
remaining -- minimal -- grammar, style, and TeX fixes for Section 1
1 volute@g-vo.org 2965 \documentclass[11pt,a4paper]{ivoa}
2     \input tthdefs
3    
4     \usepackage[utf8]{inputenc}
5 kriebe 3457 \usepackage{booktabs, tabulary} % for nicer tables
6 kriebe 4287 \usepackage[titletoc,toc,title]{appendix}
7 volute@g-vo.org 2965
8 kriebe 3757 % make the text in pdf properly searchable
9     \usepackage{lmodern}
10    
11 kriebe 3792 % use listings for including text files and code snippets
12     \usepackage{listings}
13 mir.louys 4317 \usepackage{color}
14 kriebe 4367 \usepackage[nottoc]{tocbibind}
15 kriebe 3792
16 mir.louys 4317 \definecolor{mygreen}{rgb}{0,0.6,0}
17     \definecolor{mygray}{rgb}{0.5,0.5,0.5}
18     \definecolor{mymauve}{rgb}{0.58,0,0.82}
19 volute@g-vo.org 2965
20 mir.louys 4317
21 volute@g-vo.org 2965 \ivoagroup{DM}
22    
23     \author{Kristin Riebe}
24 kriebe 3628 \author{Mathieu Servillat}
25 kriebe 3641 \author{François Bonnarel}
26     \author{Mireille Louys}
27 volute@g-vo.org 2965 \author{Florian Rothmaier}
28 kriebe 3641 \author{Michèle Sanguillon}
29     \author{IVOA Data Model Working Group}
30 volute@g-vo.org 2965
31 kriebe 3641 \editor{Kristin Riebe}
32     \editor{Mathieu Servillat}
33    
34 volute@g-vo.org 2965 % \previousversion[????URL????]{????Funny Label????}
35 kriebe 3765 \previousversion[http://www.ivoa.net/documents/ProvenanceDM/20161121/]{WD-ProvenanceDM-1.0-20161121.pdf}
36 kriebe 3533 \previousversion[http://volute.g-vo.org/svn/trunk/projects/dm/provenance/description/ProvDM-0.2-20160428.pdf]{ProvDM-0.2-20160428.pdf}
37     \previousversion[http://volute.g-vo.org/svn/trunk/projects/dm/provenance/description/ProvDM-0.1-20141008.pdf]{ProvDM-0.1-20141008.pdf}
38 volute@g-vo.org 2965
39 kriebe 3457
40 kriebe 3055 % own definitions
41 kriebe 3320 \definecolor{todocolor}{rgb}{1,1,0.8}
42     \definecolor{darkred}{rgb}{0.6,0,0}
43     \definecolor{rose}{rgb}{1.0,0.88,0.88}
44     \definecolor{darkgrey}{rgb}{0.35,0.35,0.35}
45     %\newcommand{\TODO}[1]{%
46     % \noindent%
47     % \textcolor{todocolor}{\sffamily [\textbf{TODO:} #1]}%
48     %}
49    
50     \newcommand{\TODO}[1]{%
51     \noindent%
52     \colorbox{todocolor}{%
53     \parbox{0.85\linewidth}{\sffamily \textbf{TODO:}\\
54     #1}
55 kriebe 3473 }%
56 kriebe 3320 \vspace{2pt}
57    
58     }
59    
60 kriebe 3663 \newcommand{\note}[1]{%
61 kriebe 3320 \noindent%
62 kriebe 3984 \textcolor{darkgrey}{{\sffamily Note:} \emph{#1}}%
63 kriebe 3320 }
64    
65 kriebe 4208 \newcommand{\comment}[1]{%
66     \noindent%
67     \textcolor{red}{{\sffamily Comment:} \emph{#1}}%
68     }
69 kriebe 3320
70 kriebe 4208
71 kriebe 3055 \newcommand{\paragraphlb}[1]{\paragraph{#1}\mbox{}\\} % paragraph with line break
72    
73 kriebe 3320 \setlength{\fboxsep}{5pt}
74     %\setlength{\fboxrule}{1.5pt}
75     \newcommand{\warning}[1]{%
76     \vspace{\baselineskip}
77     \noindent
78     \parbox{\linewidth}{%
79     \colorbox{darkred}{%
80     \parbox{0.7\linewidth}{\large \sffamily \textcolor{white}{Warning}}%
81     }\\[-1pt]
82     \noindent%
83     \fcolorbox{darkred}{rose}{%
84     \parbox{0.7\linewidth-2\fboxrule}{#1}%
85     }%
86     }%
87     \vspace{\baselineskip}
88     }%
89    
90 kriebe 3457 % for nicer tables:
91     \renewcommand{\arraystretch}{1.3}
92     \newcommand{\head}[1]{\textbf{#1}}
93    
94 kriebe 3473
95 kriebe 4250 % smaller font in verbatim:
96     \usepackage{verbatimbox}
97    
98    
99 kriebe 4229 % define new command for classes and other stuff, in case we decide later on for a different style
100 kriebe 3984 \newcommand{\class}[1]{\emph{#1}}
101 kriebe 4338 \newcommand{\attribute}[1]{\texttt{#1}}
102     \newcommand{\attr}[1]{\texttt{#1}} % equivalent to \attribute
103    
104 kriebe 4229 \newcommand{\urlparam}[1]{{\scriptsize{#1}}}
105     \newcommand{\urlvalue}[1]{{\scriptsize{#1}}}
106 kriebe 3473
107 mnullmei 4377 % from https://tex.stackexchange.com/questions/121955/help-on-dealing-with-items-divided-with-slash
108     \renewcommand{\slash}{/\penalty\exhyphenpenalty\hspace{0pt}}
109    
110 volute@g-vo.org 2965 \begin{document}
111 kriebe 3984 \newcolumntype{Y}{>{\raggedright\arraybackslash}X}
112 kriebe 3457
113 mir.louys 4317 % define listing parameters
114     \lstdefinestyle{customc}{
115     belowcaptionskip=1\baselineskip,
116     breaklines=true,
117     frame=L,
118     %xleftmargin=\parindent,
119     language=XML,
120     showstringspaces=false,
121     basicstyle=\footnotesize,
122     keywordstyle=\bfseries\color{green!40!black},
123     %morekeywords={entity,activity, agent, used, wasGeneratedBy,prefix, ...},
124     morekeywords={agent, used, wasGeneratedBy,prefix, ...},
125     commentstyle=\color{purple!40!black},
126     identifierstyle=\color{blue},
127     %stringstyle=\color{orange},
128     stringstyle=\color{mymauve},
129     rulecolor=\color{black}
130     }
131     \lstset{escapechar=@,style=customc}
132    
133    
134     \title{IVOA Provenance Data Model}
135    
136 volute@g-vo.org 2965 \begin{abstract}
137 mathieu.servillat 3708 This document describes how provenance information for astronomical datasets
138     %(with the focus on observational data)
139 mathieu.servillat 3709 can be modeled, stored and exchanged within
140 kriebe 3663 the astronomical community in a standardized way.
141 kriebe 3734 We follow the definition of provenance as proposed by the W3C\footnote{\url{https://www.w3.org/TR/prov-overview/}}, i.e. that provenance is information about entities, activities, and people involved in producing a piece of data or thing, which can be used to form assessments about its quality, reliability or trustworthiness.
142 mathieu.servillat 3708 Such provenance information in astronomy is important to enable any scientist to trace back
143 kriebe 3663 the origin of a dataset (e.g. an image, spectrum, catalog or single points in a
144     spectral energy distribution diagram or a light curve), learn about the people and
145     organizations involved in a project and assess the quality of the dataset as well
146     as the usefulness of the dataset for her own scientific work.
147 volute@g-vo.org 2965 \end{abstract}
148    
149    
150     \section*{Acknowledgments}
151    
152     This document has been developed in part with support from the German
153 kriebe 3727 Astrophysical Virtual Observatory, funded by BMBF Bewilligungsnummer 05A14BAD and 05A08VHA.
154 mir.louys 4339 The Provenance Working Group acknowledges support from the Astronomy ESFRI and Research Infrastructure Cluster – ASTERICS project, funded by the European Commission under the Horizon 2020 Programme (GA 653477).
155 volute@g-vo.org 2965
156 mnullmei 4358 Thanks for fruitful discussions to: Catherine Boisson and Karl Kosak for the
157 kriebe 4367 binding to the Cerenkov Telescope Array (CTA) project, Gerard
158     Lemson and Laurent Michel for the VODML expression of the data model, Markus Demleitner,
159     Markus Nullmeier, Harry Enke, Jochen Klar, Ole Streicher, Anastasia Galkin and Adrian Partl
160     for fruitful discussions, remarks and comments during the different stages of this
161 mnullmei 4358 specification.
162 volute@g-vo.org 2965
163     \section*{Conformance-related definitions}
164    
165     The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
166     ``OPTIONAL'' (in upper or lower case) used in this document are to be
167     interpreted as described in IETF standard, \citet{std:RFC2119}.
168    
169     The \emph{Virtual Observatory (VO)} is
170 kriebe 3055 a general term for a collection of federated resources that can be used
171 volute@g-vo.org 2965 to conduct astronomical research, education, and outreach.
172     The \href{http://www.ivoa.net}{International
173     Virtual Observatory Alliance (IVOA)} is a global
174     collaboration of separately funded projects to develop standards and
175     infrastructure that enable VO applications.
176    
177    
178     \section{Introduction}
179 kriebe 3447 \input{intro-general}
180 kriebe 3641 \input{intro-requirements}
181 kriebe 3447 \input{intro-VOarchitecture}
182     \input{intro-previousefforts}
183 volute@g-vo.org 2965
184 kriebe 3984
185 kriebe 3447 \section{The provenance data model}
186 kriebe 4287 \label{sec:datamodel}
187 kriebe 3447 \input{datamodel-description}
188 volute@g-vo.org 2965
189    
190 kriebe 4071 % make sure that images/tables of the previous section are printed
191 kriebe 4277 % before starting the new section -- comment out, if not needed
192     % \clearpage
193 kriebe 3692 %\section{Applying provenance -- Interactions with other Data models}\label{sec:dmlinks}
194 kriebe 3984 \section{Links to other data models}
195     \label{sec:dmlinks}
196     \input{datamodel-links}
197 kriebe 3755
198    
199 kriebe 4071 % make sure that images/tables of the previous section are printed
200     % before starting the new section
201     \clearpage
202 kriebe 4287 \section{Serialization of the provenance data model}
203     \label{sec:serialisations}
204     \input{serializations}
205 mnullmei 4335 %\subsection{Serializing of the data model core}
206 kriebe 4287 %\label{sec:intro-serialization}
207     %\input{serialisation-intro}
208 kriebe 3447 \section{Accessing provenance information}
209 kriebe 4307 \label{sec:provaccess}
210 kriebe 3447 \input{provaccess}
211 volute@g-vo.org 2965
212 kriebe 3984
213 kriebe 4250 \section{Use cases -- applying the data model}
214     %Implementations of the data model for specific use cases}
215 kriebe 3984 \label{sec:usecases-implementations}
216 kriebe 3447 \input{usecases-implementations}
217 volute@g-vo.org 2965
218 kriebe 4287 \begin{appendices}
219     %\appendix
220 kriebe 4372
221 kriebe 4287 \section{Serialization Examples}
222     \label{sec:appendix-serialization-examples}
223     \input{AppendixA-ML}
224 volute@g-vo.org 2965
225 kriebe 4372
226 kriebe 4330 \section{PROV-VOTable serialisation and ProvTAP TAP schema}
227 kriebe 4324 \label{sec:appendix-prov-votable}
228 kriebe 4329 \input{PROV-VOTABLE}
229 kriebe 4250
230 volute@g-vo.org 2965 \section{Changes from Previous Versions}
231 kriebe 3473 % No previous versions yet.
232 volute@g-vo.org 2965 % these would be subsections "Changes from v. WD-..."
233     % Use itemize environments.
234 kriebe 3765 \subsection{Changes from WD-ProvenanceDM-1.0-20161121}
235     \begin{itemize}
236 kriebe 4307 %\item New appendix sections for ProvTAP added
237     \item Corrected and extended attribute tables and mapping tables for links with DatasetDM and SimDM.
238     \item Restructured Accessing provenance section by splitting it in two: Section~\ref{sec:serialisations} for explaining the different serialization formats and differences to W3C serializations, Section~\ref{sec:provaccess} for describing the access protocols ProvDAL and ProvTAP.
239     \item Removed discussion section, since now all the topics are addressed in the main text.
240     \item Added paragraph on how to use the model in Section~\ref{sec:usecases-implementations}.
241     \item Shortened serialization examples, partially moved them to appendix.
242     \item Added paragraph on VOSI interface.
243     \item Added a proposed serialization of description classes.
244 mathieu.servillat 4239 \item Modified text on the content of EntityDescription, now seen as Entity attributes known before the Entity instance exists.
245 kriebe 4307 \item Renamed Section~\ref{sec:usecases-implementations} to stress that it explains applications of the model (use cases); implementation details and code examples can be found in Implementation Note \citep{std:ProvenanceImplementationNote}.
246 kriebe 4277 \item Complete rewrite of the ProvDAL section in Section~\ref{sec:access_protocols}; new parameters, new figure and examples added.
247 kriebe 4204 \item Added additional figure for entity-activity relations.
248 kriebe 4071 \item Moved the figure showing relations between Provenance.Agent and Dataset.Party into Section~\ref{sec:dmlinks}.
249 kriebe 4027 \item Extended the entity role examples in table \ref{tab:entity-roles}.
250 kriebe 4277 \item Added links to provn and votable-serialization for HiPS-use case, added first part of provn as example in the HiPS-use case section.
251     \item More explanations on links to data models in Section~\ref{sec:dmlinks}, introduced subsections, added table with SimDM-mapping.
252 kriebe 4135 \item Moved detailed implementation section from appendix to a separate document (implementation note), shortened the use cases \& implementation section.
253 kriebe 4277 \item Attribute/class updates:
254     \begin{itemize}
255     \item Added optional attributes \emph{Entity.creationTime} and \emph{EntityDescription.category}
256     \item Added optional attributes \emph{Parameter.min}, \emph{Parameter.max}, \emph{Parameter.option}
257     \item Removed the obscore/dataset attributes from EntityDescription, since they are specific for observations only and are not applicable to configuration entities etc.
258     \item Use voprov:type and voprov:role in Table~\ref{tab:agent-roles} with example agent roles, i.e. replaced prov:person by Individual and prov:organization by Organization.
259     \item Renamed \emph{label} attribute to \emph{name} everywhere, for more consistency with SimDM naming scheme (\emph{label} is reserved there for SKOS labels).
260     \item Renamed attribute \emph{Entity.access} to \emph{Entity.rights} for more consistency with DatasetDM etc.
261     \item Avoid double-meaning of \emph{description} (as reference and free-text description) by renaming the free-text description to \emph{annotation}. No need for an additional description-attribute for reference to the corresponding description class, since it's expressed by the corresponding link in the model anyway.
262     \item Applied similar naming scheme to \emph{Parameter} and \emph{ParameterDescription}-classes
263     \item Renamed \emph{docuLink} to \emph{doculink}
264     \item Corrected attribute names in Table~\ref{tab:datasetmapping}.
265     \end{itemize}
266 volute@g-vo.org 2965
267 kriebe 4277
268 kriebe 3765 \end{itemize}
269    
270 kriebe 4287 \end{appendices}
271 kriebe 3765
272 kriebe 4367 \listoffigures
273    
274     \listoftables
275 volute@g-vo.org 2965
276     \bibliography{ivoatex/ivoabib,prov-refs}
277    
278    
279     \end{document}

msdemlei@ari.uni-heidelberg.de
ViewVC Help
Powered by ViewVC 1.1.26