# Diff of /trunk/projects/dm/provenance/description/datamodel-description.tex

revision 4237 by mathieu.servillat, Wed Aug 30 13:41:01 2017 UTC revision 4238 by mathieu.servillat, Mon Sep 11 14:33:33 2017 UTC
# Line 126  Line 126
126
127
128  \subsubsection{Entity and EntityDescription}  \subsubsection{Entity and EntityDescription}
129
130  Entities in astronomy are usually astronomical or astrophysical datasets in the  Entities in astronomy are usually astronomical or astrophysical datasets in the
131  form of images, tables, numbers, etc. But they can also be observation or  form of images, tables, numbers, etc. But they can also be observation or
132  simulation log files, files containing system information, environment variables, names and versions of packages, ambient conditions or, in a wider sense, also observation proposals, scientific  simulation log files, files containing system information, environment variables, names and versions of packages, ambient conditions or, in a wider sense, also observation proposals, scientific
133  articles, or manuals and other documents.  articles, or manuals and other documents.
134
135  An entity is not restricted to being  An entity is not restricted to being a file.
a file.
136  It can even be just a number in a table, depending on how fine-grained the  It can even be just a number in a table, depending on how fine-grained the
137  provenance shall be described.  provenance shall be described.
138
# Line 144  Line 144
144  \label{fig:entity-details}  \label{fig:entity-details}
145  \end{figure}  \end{figure}
146
147  Entities in the VO are often called dataset'', which could mean a single  The VO concept closest to Entity is the notion of Dataset'', which could mean a single
148  table, an image or a collection of them. The Dataset Metadata Model  table, an image or a collection of them. The Dataset Metadata Model
149  \citep{std:DatasetDM} specifies an IVOA Dataset'' as a file or files which  \citep{std:DatasetDM} specifies an IVOA Dataset'' as a file or files which
150  are considered to be a single deliverable''.  are considered to be a single deliverable''.
# Line 178  Line 178
178  For entities, we suggest the attributes given in Table  For entities, we suggest the attributes given in Table
179  \ref{tab:entity-attributes}. If the attribute also exists in the W3C  \ref{tab:entity-attributes}. If the attribute also exists in the W3C
180  Provenance Data Model, we list its name in the second column.  Provenance Data Model, we list its name in the second column.
181  We discussed further attributes like \emph{size} and \emph{format}, but we decided to treat an
182  entity of the same content but different format (and thus size) as the same entity,  %We discussed further attributes like \emph{size} and \emph{format}, but we decided to treat an
183  unless they do not have the same provenance (e.g. when the transformation'' activity  %entity of the same content but different format (and thus size) as the same entity,
184  for converting one format into another is included in the provenance description).  %unless they do not have the same provenance (e.g. when the transformation'' activity
185    %for converting one format into another is included in the provenance description).
186
187  %\TODO{format and size may not be needed, if entities with the same content but different format and size are considered as the same entity.}  %\TODO{format and size may not be needed, if entities with the same content but different format and size are considered as the same entity.}
188
# Line 190  Line 191
191  More details on this will follow in Section \ref{sec:entity-activity-relations}.  More details on this will follow in Section \ref{sec:entity-activity-relations}.
192
193  \paragraph{EntityDescription.}  \paragraph{EntityDescription.}
194  As already mentioned before, the types of entities or datasets in astronomy  %The Entity class can have an EntityDescription class attached.
195  can be predefined using a description  The types of entities, or datasets in astronomy, can be predefined using a description class \class{EntityDescription}.
196  class \class{EntityDescription}.  This class is meant to store information about an Entity that are known before the Entity instance is created. For example, if we run an activity to create a RGB image from three grey images, we may have a mandatory format for the input and output images before the execution (JPG, PNG, FITS\dots), but we probably cannot know the final size of the image  that will be created. Therefore, format'' would be an EntityDescription attribute , while size'' would be an attribute of the Entity instance.
197  This class stores entity-related
198  attributes, describing the content of the data, which can mainly be derived from  %This class thus stores entity-related
199  the Dataset Metadata Model, the general model for observational data.  Some of the attributes that describe the content of the data could be derived from
200  The description attributes are summarized in Table  the Dataset Metadata Model.
\ref{tab:entitydescription-attributes}.
201
202  The \class{EntityDescription} does NOT contain any information about the usage  The \class{EntityDescription} does NOT contain any information about the usage
203  of the data, it tells nothing about them being used as input or output. This is  of the data, it tells nothing about them being used as input or output. This is
204  defined only by the relations (and the relation descriptions) between activities  defined only by the relations (and the relation descriptions) between activities
205  and entities (see Section \ref{sec:entity-activity-relations}).  and entities (see Section \ref{sec:entity-activity-relations}).
206
207    The EntityDescription general attributes are summarized in Table
208    \ref{tab:entitydescription-attributes}.
209
210
211  \begin{table}[h]  \begin{table}[h]
212  \small  \small
# Line 518  Line 521
521  the \class{UsedDescription} and \class{WasGeneratedByDescription} relation.  the \class{UsedDescription} and \class{WasGeneratedByDescription} relation.
522  For example, an activity for darkframe-subtraction requires two input images. But it is  For example, an activity for darkframe-subtraction requires two input images. But it is
523  very important to know which of the images is the raw image and  very important to know which of the images is the raw image and
524  which one fulfills the role of dark frame.  which one fulfils the role of dark frame.
525
526  The role is in general NOT an attribute for \class{EntityDescription} or \class{Entity},  The role is in general NOT an attribute for \class{EntityDescription} or \class{Entity},
527  since the same entity (e.g. a specific FITS file containing an image) may play  since the same entity (e.g. a specific FITS file containing an image) may play
# Line 636  Line 639
639  \midrule  \midrule
640  \textbf{id}  & & string & parameter unique identifier\\  \textbf{id}  & & string & parameter unique identifier\\
641  \textbf{name} & & string & parameter name\\  \textbf{name} & & string & parameter name\\
642  annotation & & string & additional free text description for the parameter\\  annotation & & string & additional free text description\\
643  datatype    & & string & datatype of the parameter \\  datatype    & & string & datatype \\
644  unit           & & string & physical unit of the parameter\\  unit           & & string & physical unit \\
645  ucd           & & string  & Unified Content Descriptor for the parameter, supplying a standardized classification of the physical quantity\\  ucd           & & string  & Unified Content Descriptor, supplying a standardized classification of the physical quantity\\
646  utype        & & string  & UType of the parameter, meant to express the role of the parameter in the context of an external data model \\  utype        & & string  & UType, meant to express the role of the parameter in the context of an external data model \\
647    min           & & number & minimum value \\
648    max           & & number & maximum value\\
649    options           & & list & list of accepted values\\
650  \bottomrule  \bottomrule
651  \end{tabulary}  \end{tabulary}
652  \caption{Attributes of \class{ParameterDescription}.}  \caption{Attributes of \class{ParameterDescription}.}

Legend:
 Removed from v.4237 changed lines Added in v.4238