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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4416 - (show annotations)
Tue Sep 26 20:48:43 2017 UTC (3 years, 10 months ago) by kriebe
File MIME type: application/x-tex
File size: 11565 byte(s)
Updated the conceptional UML diagram, renamed roles for hadMember/hadStep to entity/activity (instead of 'member'); close now to W3C naming convention

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

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