
%{updated by Mathieu} 
%The ProvenanceDM includes description classes that can exist before any provenance information is recorded. 

% 2018-09 commented
%Description classes in ProvenanceDM gather information on the activity which can preexist to the activity itself. As presented in Section~\ref{sec:activity_desc}, the \class{ActivityDescription} class gives generic information on the activity (\attribute{name}, \attribute{annotation}, \attribute{doculink}...) and the parameters expected as an input with \class{ParameterDescription} instances. In addition, \class{UsedDescription} and \class{WasGeneratedByDescription} classes indicate the expected roles of the input and output entities, respectively. Finally, the activity may expect specific kinds of entities as inputs or outputs, for which there may be detailed descriptions stored as \class{EntityDescription} records.

The Description classes presented in Section~\ref{sec:activity_desc} are intended to store information about an activity that is known before the execution of this activity. Such information could thus be stored and transported separately from the main provenance information that traces the execution of activities.

The serialization of an \class{ActivityDescription} instance, that includes all the Description classes presented in Section~\ref{sec:activity_desc}, is based on the IVOA DataLink Service Descriptors for service resources \citep{std:DataLink}, and can thus be stored as a VOTable \citep{std:VOTABLE}. Indeed, a service descriptor points to a service that may execute an activity, using input parameters, some of which probably are or point to entities. One may thus easily translate an ActivityDescription VOTable resource to a DataLink service descriptor VOTable resource, and vice-versa.

The VOTable contains one resource with attributes \attribute{type="meta"} and \attribute{utype="voprov:ActivityDescription"}. This resource contains PARAM elements to describe the activity and then GROUP elements gathering additional PARAM elements to describe:
\begin{itemize}
 \item the input parameters (group \attribute{name="InputParams"}), which is similar to the group defining input parameters in a DataLink service descriptor,
 \item the input entities (group \attribute{name="InputEntities"}),
 \item the output entities (group \attribute{name="OutputEntities"}). 
 \end{itemize}
 
% comment Mireille: 
% what if an activity computes a number , a boolean as a result and produces an output parameter instead of an output entity: e.g compare 2 sets of dataproducts : false/True correlate two datasets : correlation value, etc ...  
% --> add output parameters  ?

The PARAM elements of the resource correspond to the attributes of the \class{ActivityDescription} class (see Section~\ref{sec:activity_desc}) and may include a main contact with a name and email (\attribute{contact\_name} and \attribute{"contact\_email"}), that corresponds to an agent associated with the \class{ActivityDescription}.
The \attribute{utype} attribute is used to connect the PARAM element to its corresponding element in the Provenance DM. Other optional elements can be added with their corresponding \attribute{utype} set, if relevant.

For the input parameters, each attribute located in the \class{ParameterDescription} class in the model (e.g. \attribute{units}, \attribute{ucd}, \attribute{utype}, \attribute{min}, \dots) is mapped to an attribute of a PARAM element in the VOTable (both have the same structure, see Section \ref{sec:parameters}).
%The \attribute{type} attribute of the PARAM element can be set to "no\_query" to indicate that the parameter is optional for the activity (i.e. a default value will be used).

The input group can be used to extend some of the parameters that point in fact to entities (e.g. if the parameter is a file name, a URL, an entity identifier).
Otherwise, it can indicate the other entities that may be used internally.

The output group indicates the expected entities that may be generated by the activity.

Each input or output entity is then described within a GROUP block where the name attribute is set to the role or the name of the reference parameter. 
This GROUP block contains PARAM elements with names corresponding to attributes of \class{UsedDescription}, \class{WasGeneratedByDescription} or \class{EntityDescription}.
For example, the following names can be found :
\begin{itemize}
 \item \attribute{name="role"}: gives the role of the entity with respect to the Used or WasGeneratedBy relation (e.g. "red", "green" or "blue" channel image, or the output "RGB" file),
 \item \attribute{name="content\_type"}: indicates the MIME type expected by the activity for the input or output entity,
 \end{itemize} 

%In the following example the output file name "RGB.jpg" is expected as a parameter to the activity and is thus referenced by the id PARAM element located in the GROUP of generated entities (with ref="RGB").

%Here is an example of an ActivityDescription VOTable that describes an activity to create an RGB image from three red, green, blue images:
%++ suggestion mireille : 
Here is an example of an \class{ActivityDescription} VOTable that describes an activity to create an RGB image from three input images mapped to the red, green, blue image planes in the composition. 

%\begin{verbnobox}[\scriptsize]
%\begin{lstlisting}[language=XML, style=customc,caption= example of an \class{ActivityDescription} VOTable]
\begin{minted}[breaklines,breakanywhere,frame=single,fontsize=\footnotesize]{xml}
<VOTABLE xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.ivoa.net/xml/VOTable/v1.3" version="1.3" xsi:schemaLocation="http://www.ivoa.net/xml/VOTable/v1.3 http://www.ivoa.net/xml/VOTable/v1.3">
    
  <RESOURCE name="make_RGB_image" type="meta" utype="voprov:ActivityDescription">
      
    <DESCRIPTION>Create an RGB image from 3 images</DESCRIPTION>
    <PARAM name="type" value="..." datatype="char" arraysize="*" utype="voprov:ActivityDescription.type"/>
    <PARAM name="subtype" value="..." datatype="char" arraysize="*" utype="voprov:ActivityDescription.subtype" />
    <PARAM name="version" value="..." datatype="float" utype="voprov:ActivityDescription.version" />
    <PARAM name="doculink" value="..." arraysize="*" datatype="char" utype="voprov:ActivityDescription.doculink"/>
    <PARAM name="contact_name" value="..." datatype="char" arraysize="*" utype="voprov:Agent.name" />
    <PARAM name="contact_email" value="..." datatype="char" arraysize="*" utype="voprov:Agent.email" />
        
    <GROUP name="InputParams">
      <PARAM name="R" value="R.jpg" arraysize="*" datatype="char" ucd="meta.id">
        <DESCRIPTION>Name of the image for red channel</DESCRIPTION>
      </PARAM>
      <PARAM name="G" value="G.jpg" arraysize="*" datatype="char" ucd="meta.id">
        <DESCRIPTION>Name of the image for green channel</DESCRIPTION>
      </PARAM>
      <PARAM name="B" value="B.jpg" arraysize="*" datatype="char" ucd="meta.id">
        <DESCRIPTION>Name of the image for blue channel</DESCRIPTION>
      </PARAM>
      <PARAM name="normalize" value="true" datatype="boolean">
        <DESCRIPTION>Apply normalization</DESCRIPTION>
      </PARAM>
      <PARAM name="RGB" value="RGB.jpg" arraysize="*" datatype="char" type="no_query">
        <DESCRIPTION>Name of the generated RGB image</DESCRIPTION>
      </PARAM>
    </GROUP>
		
    <GROUP name="InputEntities">
      <GROUP name="R" utype="voprov:UsedDescription">
        <DESCRIPTION>Image for red channel</DESCRIPTION>
        <PARAM name="role" value="red" arraysize="*" datatype="char" utype="voprov:UsedDescription.role" />
        <PARAM name="content_type" value="image/jpeg" arraysize="*" datatype="char" utype="voprov:EntityDescription.content_type" ucd="meta.code.mime" />
      </GROUP>
      <GROUP name="G" utype="voprov:UsedDescription">
        <DESCRIPTION>Image for green channel</DESCRIPTION>
        <PARAM name="role" value="green" arraysize="*" datatype="char" utype="voprov:UsedDescription.role" />
        <PARAM name="content_type" value="image/jpeg" arraysize="*" datatype="char" utype="voprov:EntityDescription.content_type" ucd="meta.code.mime" />
      </GROUP>
      <GROUP name="B" utype="voprov:UsedDescription">
        <DESCRIPTION>Image for blue channel</DESCRIPTION>
        <PARAM name="role" value="blue" arraysize="*" datatype="char" utype="voprov:UsedDescription.role" />
        <PARAM name="content_type" value="image/jpeg" arraysize="*" datatype="char" utype="voprov:EntityDescription.content_type" ucd="meta.code.mime" />
      </GROUP>
    </GROUP>
    
    <GROUP name="OutputEntities">
      <GROUP name="RGB" utype="voprov:WasGeneratedByDescription">
        <DESCRIPTION>RGB image generated</DESCRIPTION>
        <PARAM name="role" value="RGB" arraysize="*" datatype="char" utype="voprov:WasGenereratedByDescription.role" />
        <PARAM name="content_type" value="image/jpeg" arraysize="*" datatype="char" utype="voprov:EntityDescription.content_type" />
      </GROUP>
    </GROUP>
    
  </RESOURCE>
</VOTABLE>
\end{minted}
