Merge branch 'admin-doc-data-model' into 'master'

Admin doc data model

See merge request !35

docs/user-documentation/advance-features/openbis-data-modelling.md

 openBIS Data Modelling
 ======================
 
-Overview
+# Overview
 
-openBIS has a hierarchical data structure:
+openBIS has the following data structure:
 
-1.  **Space**: folder with *Code and *Description**
-2.  **Project**: folder with *Code* and *Description*
-3.  **Experiment/Collection:** folder with *user-defined properties*
+1.  **Space**: entity with *Code and *Description**
+2.  **Project**: entity with *Code* and *Description*
+3.  **Experiment/Collection:** entity with *user-defined properties*
 4.  **Object**: entity with *user-defined properties* 
-5.  **Data set**: folder where data files are stored. A data set has
-    *user-defined properties*  
+5.  **Dataset**: folder where data files are stored. A dataset has *user-defined properties*      
       
-![image info](img/125.png)
+![image info](img/openbis-data-model.png)
 
-  
-
-Access to openBIS is controlled either at the *Space* level or *Project*
-level.
-
-  
-
-Data model in openBIS ELN-LIMS 
--------------------------------
-
-In the openBIS ELN-LIMS the following structure is used.
-
-## Inventory
-
-The inventory is usually conceived to be shared by all lab members. The
-inventory is used to store all materials and protocols (i.e. standard
-operating procedures) used in the lab. It is possible to create
-additional inventories, for example of instruments and equipment.
-
-The following structure is used in the Inventory:
 
+*Space* is the top level. Below *Spaces* there are *Projects* and below *Projects* there are *Experiments/Collections*. 
+In the general openBIS data model, *Objects* can:
+- be shared across *Spaces* (i.e. they do not belong to any Space)
+- belong to a *Space*
+- belong to a *Project*
+- belong to an *Experiment/Collection*
   
+*Datasets* can be associated only to *Experiments/Collections* or to *Objects*.  
 
-**Materials** (=*Space*)
-
-**Methods** (=*Space*)
+Access to openBIS is controlled at the *Space* level, *Project* level or openBIS instance level (see [openBIS roles ](../general-admin-users/admins-documentation/user-registration.md#openbis-roles)).
 
   
 
-In the generic ELN-LIMS, the *Materials* folder is empty and everything
-has to be defined by an admin user.
-
-The *Methods* folder has default folders for general protocols defined:
-
-  
+## Data model in openBIS ELN-LIMS 
+-------------------------------
 
-**Methods** (=*Space*)
+In the openBIS ELN-LIMS a simplified data model is used, as shown below.  
 
-**Protocols** (=*Project*)
+![image info](img/ELN-data-model.png). 
 
-**General Protocols** (=*Collection*)
+In this case, *Objects* can only belong to *Experiments/Collections*.
 
-  
 
-In the ELN-LIMS for life sciences, some folders are already predefined
-in the *Materials* folder. For example:
 
-  
 
-**Materials** (=*Space*)
+## Inventory
 
-**Reagents** (=*Project*)
+The inventory is usually conceived to be shared by all lab members. The
+inventory is used to store all materials and protocols (i.e. standard
+operating procedures) used in the lab. It is possible to create
+additional inventories, for example of instruments and equipment.
 
-**Chemicals Collection** (=*Collection*)
+The picture below shows an example of an Inventory with the different openBIS levels.  
 
-**Enzymes Collection** (=*Collection*)
+![image info](img/inventory-data-model.png)
 
-**Antibodies Collection** (=*Collection*)
 
-  
 
-An openBIS Instance admin can customise the Inventory folders for the
-lab and create the needed Object types ([Register Master Data via the Admin Interface](../../uncategorized/register-master-data-via-the-admin-interface.md)).
 
 ## Lab Notebook
 
 By default, the lab notebook is organised per user. Each user has a
 personal folder (=*Space*), where to create *Projects*, *Experiments*
-and *Experimental Steps (*=Objects). Data files can be uploaded to *Data
-Sets*. Example structure:
+and Experimental Steps (=*Objects*). Data files can be uploaded to *Datasets*. Example structure:
 
   
+![image info](img/labnotebook-data-model.png)
 
-**Username** (=*Space*)
 
-**Master thesis project** (=*Project*)
-
-**Experiment 1** (=*Experiment*)
-
-**Experimental step 1** (=*Object*)
-
-**Experimental step 2** (=*Object*)
-
-**Raw Data** (=*Data set*)
-
-  
-
-  
-
-Some labs prefer to organise their lab notebook using a classification
-per project rather than per user. In this case an openBIS space would
-correspond to a lab Project and an openBIS project could be a
-sub-project. Example structure:
 
   
 
-**SNF projects** (=*Space*)
-
-**Project 1** (=*Project*)
-
-**Experiment** (=*Experiment*)
-
-**Experimental Step** (=*Object*)
-
-**Raw Data** (=*Data set*)
-
-**Project 2** (=*Project*)
-
-**Experiment** (=*Experiment*)
-
-**Experimental step 1** (=*Object*)
-
-**Experimental step 2** (=*Object*)
-
-**Raw Data** (=*Data set*)
-
+Some labs prefer to organise their lab notebook using an organization
+per project rather than per user. In this case an openBIS *Space* would
+correspond to a lab Project and an openBIS *Project* could be a
+sub-project or a user folder (one folder per user working on the same project). 
   
 
-openBIS parents and children
+# openBIS parents and children
 ----------------------------
 
-Objects can be linked to other objects, datasets to other datasets with
+*Objects* can be linked to other *Objects*, *Datasets* to other *Datasets* with
 N:N relationship. In openBIS these connections are known as *parents*
 and *children*.
 
   
 
-![image info](img/255.png)
+![image info](img/objects-parents-children.png)![image info](img/dataset-parents-children.png)
+
+
 
   
 
@@ -149,29 +91,22 @@ and *children*.
 
 1.  One or more samples are derived from one main sample. This is the
     parent of the other samples:  
-![image info](img/263.png)
+
+
+![image info](img/sample-vials.png)
       
-2.  One Experimental step is written following a protocol stored in the
-    Inventory and using a sample stored in the inventory. The protocol
-    and the sample are the parents of the Experimental
-![image info](img/268.png)
+2.  One Experimental step is performed following a protocol stored in the
+    inventory, on a sample stored in the inventory, using a given equipment. The protocol, the sample and the equipment are the parents of the Experimental step
+
+
+![image info](img/exp-step-parents.png)
+
       
 3.  One Experimental Step is done after another and we want to keep
-    track of the links between the steps:  
-![image info](img/272.png)
+    track of the links between the steps: 
+    
+     
+![image info](img/exp-step-parents-children.png)
       
 
-Protocols
----------
-
-Protocols are standard procedures that can be followed to perform given
-experiments in a lab. Usually protocols are stored in the common
-inventory and are linked to Experimental procedures using the
-parent-child relationships described above. 
-
-The protocol contains the standard steps to follow. The parameters
-measured during one experiment following a give protocol should be
-recorded in the Experimental Step.
 
-Not all labs have standard procedures in place. In this case, the
-*Methods* section of the Inventory does not need to be used.