Experimental Organization

Scientific frames

Scientific experiments generate data, which is the focus the present information system. However, if only the data produced by experiments is stored, and not the complete experimental conditions, i.e. the environmental conditions, infrastructure and supporting equipment or resources used to conduct those experiments, then such archived data would be orphan and therefore non reusable.

The first element of experimental conditions which is stored in Phis is the scientific frames linked to plant phenotyping experiments. A scientific frame can be a national infrastructure, a local infrastructure, or an installation (also refered to as "platform" or "facility"), as defined at emphasis.plant-phenotyping.eu and at agroportal.lirmm.fr/ontologies/OEPO. OEPO is progressively being replaced by the more generic Ontology of Experimental Scientif Objects (OESO) stored in GitHub at github.com/OpenSILEX/ontology-vocabularies.

Users register scientific frames in Phis in order to later enrich metadata associated to experimental data by establishing a link between this data and given scientific frames.

The complete list of scientific frames registered in a Phis session is available in the Experimental organization / Scientific frames menu, accessible from Phis top navigation bar.

The Add document button at the top of the each scientific frame information sheet remains orange until a first document has been added, e.g. a flyer describing the infrastructure or an organization chart. See the Documents section below for further information on documents.

It is from this Scientific frames menu that the installation manager can add the template documents for UAV or Phenomobile acquisition sessions. He has to go to the information sheet of the concerned scientific frame. Then he has to click on the Add document button and then select the Document type AcquisitionSessionUAVDocument or AcquisitionSessionPhenomobileDocument depending on which type of template document is created. Those template documents will then be accessible from the Acquisition session template item from the Installations menu in the top bar.

Projects

What are projects ?

A research project is the higher level of organisation in Phis. It is generally the object of a contract or a grant agreement between the laboratory performing the research activities and funding agencies providing the financial support. A project can hold many experiments from various experimental campaigns. Besides, several projects can participate to the same experimentation.

What are project properties ?

Projects fact sheets are all public, i.e. visible for every Phis user, including those unrelated to them. However, experimental data included in a project is also necessarily related to a given experiment. This data is accessible only to users who belong to a group (either owner or guest) authorized to access the experimentation it is related to: access rights are managed by experiment and not by project. Please see the Restrictions to a group section of this documentation for further details on data access matters.

The complete list of projects is available in the Experimental organization / Projects menu, accessible from Phis top navigation bar. The projects list is preceded by a research bar enabling the user to filter projects by their acronym, their main source of funding, and their start and end dates. There's no need to use the same case as the expected results: a lowercase search returns every results matching the characters, disregarding whether those match are lowercase or uppercase. Further information on a given project is available on its information sheet, accessed to from the projects list through the eye-icon on the right-hand side of this project row.

project-menu

A project information sheet displays all this project information stored in Phis: URI, acronyme, objective, start and end dates, contacts linked to the project, a description, etc. Documents (PDF, tables, etc.) can also be linked to a project. At the top of the project information sheet lie three buttons allowing the user to interact with the selected project.

project-information-sheet

The project specifics, displayed in the information sheet, can be modified with the Update button.

Another top button is the Add document button which remains orange until a first document has been added. See the Documents section below for further information on Phis documents and for learning how to insert them in the information system.

The Add annotation button can be used by any user in order to annotate the selected project using the Web Annotation Data Model (oa). See the Annotation section below for further information on annotations within Phis.

Create a project

Within the Projects menu, one can create a new project with the Create Project button.

Tool tips are provided for most fields: they appear on the left hand side when one drags the pointer on those fields.

tooltips

The mandatory fields, followed by a red asterisk, are:

However, it is highly recommended to fill every field. If possible, fields requiring plain text (keywords, description) should be answered to in English.

URI. The project URI is automatically created using the acronym provided by the user. The URI creation respects the w3 recommandations.

Acronym. Short and meaningful, the acronym will be the preferred way to refer to the created project. The acronym provided here is usually the one of the research project. A project acronym cannot include spaces. Once the project created, its acronym can no longer be modified.

Name. Full name of the project, it will seldom be refered to but allows a project creator to explicit the acronym. For instance, RAPeSeed Oil content anD Yield under low Nitrogen input would be an adequate name for the project whose acronym is RAPSODYN.

Subproject Of. If the new project is part of an existing project (requisitly known to Phis), one can select the name of the given mother-project within the exhaustive list of projects registered to the Phis instance where the new project is created.

Subproject Type. The subproject type can optionnaly be provided. It can be either an existing type to be selected from the list of proposed project types, either a new type provided by the user. In the later case, one has to type the new subproject type (e.g. phd thesis or internship) in the search field of Subproject Type and then click on the newly proposed type.

subproject-type

Objective. A short synthesis of the project objectives is to be provided in plain text, preferably in English. A more complete description will be asked in the Description field.

Financial Support. Organism, institution or funding agency providing the financial support of the research project. Only one organism supporting financially the project can be cited for now. Same as the Subproject Type field, the answer can be both from a predefined list or a new one (the user has to type the new organism name and then click on the search result matching the organism name).

Financial Name. As indicated in the tool tip, this field is meant for the user to provide the identification of the financial support document (e.g. a grant agreement number).

Date Start and Date End are to be provided in the format YYYY-MM-DD (year-month-day), directly or through the calendar view. If the end date of the project is unknown, the start date can be used also as Date End temporarily.

Scientific Contacts. Email adresses of the scientists involved in the project. The email adresses refer uniquely to persons existing on Phis. If unavailable in the predefined list, emails can be added to Phis from the Persons menu, prior to the new project creation. Please see the Persons section of this documentation for further details.

Administrative Contacts. Email adresses of the administrative personnel linked to the project (e.g. human ressources people). The email adresses refer uniquely to persons existing on Phis.

Project Coordinators. Email adresses of the project coordinators. The email adresses refer uniquely to persons existing on Phis.

Website. If available, URL of the website of the project.

Keywords. Keywords, preferably in English, characterizing the project. Each keyword should be separated by a comma and not include any capital letter, e.g. drought, maize.

keywords

Description. Complete plain text description of the project, preferably provided in English language. Additionally to the description, additional information can be provided as uploaded files, after the project has been created.

Experiments

What are experiments ?

Field plant phenotyping experimentations are refered to in Phis as Experiments. Experiments in Phis form self-sustained organizational units occuring in a delimited and known time frame. Every scientific objects and environmental data stored in Phis field have to be related to an experiment. Experiments include both raw and cleaned data. The data types found in Phis experiments are including but not limited to:

What are experiment properties ?

Contrary to projects, experiments information sheets are not public, but accessible only to the Phis members which are part of the groups involved in these experiments. Please go to Access rights for further details on this matter.

From the Experiments menu, a Phis user has access to the list of experiments it has the rights to access to. Every experiment on this list is characterized by:

From Home / Experiments, one can click on the eye icon on the right to see a given experiment information sheet.

experiment-list

Further information on the experiment is provided on its information sheet, such as the groups of users that have been given access to the experiment's data. For more detail on experimental data access restrictions, see the section Restrictions to a group.

experiment-view

On top of the experiment information sheet, several buttons are displayed. The button Map Visualization enables the visualization of the scientific objects (e.g. plots) of the experiment on a map centered on the experiment intallation location. Jump to the section Map Visualization for more information on experiment maps. The use of the other buttons, Update and Add document, is described at the end of the next section entitled Create an experiment. The Add annotation button can be used by any user in order to annotate the selected experiment using the Web Annotation Data Model (oa). See the Annotation section below for further information on annotations within Phis.

Create an experiment

Within the Experiments menu, a Phis user can create a new experiment with the Create Experiment button.

Tool tips are provided for some fields: they appear on the left hand side when one drags the pointer on those fields.

The mandatory fields, followed by an asterisk, are:

However, it is highly recommended to fill every field. If possible, fields requiring plain text (keywords, description) should be answered to in English.

URI. The project URI is automatically created by Phis web service which uses the acronym of the Phis instance from where the experiment is created (e.g. DIA for Diaphen) and the campaign provided by the user (e.g. 2018).

Alias. Internal name of the experiment, usually provided in all caps.

Projects. Name of the project(s) the new experiment is part of. A single experiment can be linked to several projects. One can select the name of the given projects only within the exhaustive list of projects registered to the Phis instance where the new experiment is created.

Date Start and Date End are to be provided in the format YYYY-MM-DD (year-month-day), directly or through the calendar view. It it compulsory to give a value to the Date End field in order to create an experiment. If the end date of the experiment is unknown, the start date can be reused in the Date End field. Typical Date Start values correspond to a sowing date, while Date End typically concur with an harvesting date.

create-experiment-date

Installation. Name or ID of the installation where the experiment is carried. No specific format is yet required for submitting an installation name. todo.

Campaign. Year (format YYYY) in which the experiment has been carried, or the year of the harvest/end of the experiment in case it has been carried on several years (to be confirmed). Once the experiment created, the information on the campaign in which it has been carried can no longer be modified.

create-experiment-campaign

Place. Locality or town name used internally to situate the installation location. This field will later be removed in the upcoming developments of Phis.

Scientific supervisors. Email adresses of the experiment supervisor(s). The email adresses refer uniquely to persons existing on Phis. If unavailable in the predefined list, emails can be added to Phis from the Persons menu, prior to the new project creation. Please see the Persons section of this documentation for further details.

Technical supervisors. Email adresses of the technicians and scientists (including phd students, interns, etc.) involved in the experiment implementation. The email adresses refer uniquely to persons existing on Phis.

Crop Species. Common name of the crop species which are the object of the experiment. Each crop species names must be separated by a comm. Preferably provided in English, without any capital letters. A link to the internal ontology is under development.

Groups. List of the Phis users groups authorized to access the new experiment. This field is crucial when creating an experiment. Only a Phis user belonging to at least one of the groups specified in this field will be authorized to access the newly created experiment. An experiment assigned to no group is by default set as public. Please go to Access rights for further details on this matter.

Objective. A short synthesis of the experiemnt objectives is to be provided in plain text, preferably in English. A more complete description will be asked in the Comment field.

Keywords. Keywords characterizing the experiment. Each keyword, should be separated by a comma and not include any capital letter, e.g. nitrogen use efficiency, rapeseed.

Comment. Complete plain text description of the experiment, preferably provided in English language. Additionally to the description, detailed knowledge on the experimentation can be provided through uploaded files, but only after the experiment has been created.

Completing the experiment creation within Phis is then achieved by clicking on the Create button.

From Home / Experiments, one can click on the eye icon on the right to see the newly created experiment information sheet.

The Add document button at the top of the experiment information sheet remains orange until a first document has been added, e.g. an experimental design. See the Documents section below for further information on documents.

Once created, the experiment specifics can be modified with the Update button.

Linking sensors and variables to an experiments

Admin users can associate experiments to variables and sensors, but only if they have already been declared in the system through to the Variables menu and the Sensors menu respectively.

An experiment can be linked to several variables and sensors previously declared in Phis.

From the Experiments menu (accessible from the experimental organization menu in the top navigation bar), select an experiment from the experiments list clicking on the eye icon on its right to access its information sheet. Then, go to the Measured Variables field and add variables from the dropdown list displaying all the alias of the variables previously declared in Phis. You can also go to the Sensors which participates in field and add sensors from the dropdown list displaying all the alias of the sensors previously declared in Phis.

After having selected one or several variables or sensors, click on the Update measured variable button (check symbol) on the right to save the changes you made to the experiment. You should get a green "Resources updated" pop-up on the top right corner of your screen after having clicked on the Update measured variable button.

experiments_link-to-variables-and-sensors

The experiment-variable and experiment-sensor links are now saved in the triplestore and displayed respectively in the Measured Variables and Sensors which participates in fields of the experiment information sheet. To remove these links, just click on the close window symbol ("x") next to the variable or sensor alias in their respective fields, and then click on the associated Update measured variable button. You should get another green "Resources updated" pop-up on the top right corner of your screen after having clicked on the Update measured variable button, which confirms the changes made.

Map visualization

Objects selection

Scientific objects associated with a given experiment, for example plots, can be displayed on a map, thanks to their geopositioning informations. In Phis, a map refers to a dynamic map where all the scientific objects of a given experiment are represented.

After having imported scientific objects linked to an experiment, a map associated with this experiment can be visualized within the Experiments menu through the Map Visualization button.

From this Map Visualization menu, one can create and subsequently update its information (if new scientific objects have been linked to the experiment) through the Generate Map button on the top right corner of the web page. Once the map of an experiment has been created, there's no need to re-create it if no new scientific object (e.g. plot) has been linked to this experiment.

The map of an experiment is dynamic: one can zoom in and out with the + and - sign at the top left corner of the map, or simply using the mouse wheel. The map visualization also works with a touchscreen. Map rotation is performed pressing Alt + Shift while draging the mouse pointer. Selecting multiple contiguous scientific objects is performed pressing Ctrl + Left Click and then dragging the mouse pointer (still holding the mouse left click). Selecting multiple non-contiguous scientific objects is performed pressing Ctrl + Shift and then using the left-click of the mouse pointer.

map-visualization-ctrl

When scientific objects of a map are selected, their attributes (alias within the experiment, crop species, variety, modality, replication) are displayed in a table under the map.

map-visualization-selected

Graphics from datasets

Another feature provided by the Map Visualization menu is the possibility to plot graphics from datasets associated to an experiment. A first step is to select on the map scientific objects (e.g. plots) as explained above. In order to order to create clear graphics,one should avoid selecting too many objects at the same time. At that point, a new section, Dataset(s) Visualization (On selected plot(s)), appears under the map where the objects have been selected. The second step is to select the variable of the dataset from which a graphic should be produced. An optionnal filter for the graphic creation enables the user to use only data from a specific time window to produce the desired graphic.

Quantitative Variable. Mandatory field. Here is selected a variable of interest from a predefined list of all the variables defined in a given Phis instance. Variables can be selected only one at a time. If the selected variable is associated to no dataset linked to the present experiment, then no graphic is plotted. In the next Phis developments, variables associated a gien project or experimentation will be declared at the level of the project/experimentation.

Date Start. Optionnal. First date from which variable values are used to produce a graphic. Variable values associated to a previous date will not appear in the graphic.

Date End. Optionnal. Last date at which variable values are used to produce a graphic. Variable values associated to a later date will not appear in the graphic.

The last step is to press the Search button, which will lead to the creation of a graphic displaying according to a time axis the variable values associated to:

On the new graphic, the time is displayed on the abscissa axis and the variable on the ordinate axis. Each points of the same color are associated to the same scientific object which is identified below the graphic by its URI. In future Phis developments, objects alias instead of URIs will be used as curve labels. Variable values and curve associated to an scientific object can be masked by clicking on its associated curve label which at this point changes from black to grey. Clicking a second time on the label as the effect to show again the previously hidden curve.

Images

Another feature provided by the Map Visualization menu is the possibility to show images associated to an experiment, such as hemispherical images shot on the field.

A first step is to select on the map the scientific object (e.g. plot), as explained above, associated with the images you want to visualize. Do not select two scientific objects (or more), otherwise PHIS would look for images associated to both the selected object, while most images are associated to one and only one object. At that point, a new section, Images Visualization (On selected plot), appears under the map where the objects have been selected.

images-visualization

The second step is to select the type of image you want to display, selecting it from the list of images type, and then press the Show Images button.

Documents

What are Phis documents ?

In order to ease the comprehension of projects and experiments, it is possible to upload various documents to Phis and connect them to resources such as infrastructures, projects, experiments, sensors or vectors declared in Phis. Documents that could help persons understand a project are typically a (reasearch) contract, a phd (or master) thesis, or various multimedia content such as photos or beamer presentations. Similarly, one could expect knowledge about an experimentation to be provided through documents that could be protocols, experimental designs, technical or scientific files, data files, research papers, etc. Examples of document formats are PDF, txt, csv, png images, etc. However, large files are not yet supported by Phis: a document uploaded to Phis cannot exceed 2MB for now.

The documents uploaded to Phis through the Documents section are meant for human consultation. However, metadata (intelligible to machines) must be provided for every new document. These metadata contain the document properties:

Information of a document can later be changed, while the document itself cannot be modified.

Metadata are specified with Dublin Core recommendations. Metadata enables the documents to be stored in the Phis triplestore. The expression of Dublin Core metadata using the Resource Description Framework is described at dublincore.org.

Upload a document

Any Phis user can upload a new document and specify its metadata with the Create Document button displayed on top of the information sheet of any element prone to be enriched with documents (infrastructures, projects, experiments, sensors and vectors). No admin rights are required from a Phis user to add a new document.

Title. Title of the uploaded document. No specific naming convention is required for filling this field. A document title does not have to match the name of the uploaded file it is imported from.

Creator. Name(s) of the document creator(s), separated by commas No specific naming convention is required for filling this field.

Language. Language in which the document is provided. In accordance to the Dublin Core Element Set v1.1 document, the value of the language element is defined by RFC 1766 which includes a two-character language code taken from the ISO639 standard. The language code should be provided in lower case (e.g. fr for French, en for English, etc.).

Creation Date. Date of the document creation. If unknown, the current date (i.e. the date at the moment of the document upload into Phis) can be used.

Concerned Projects. Project(s) for which the document is relevant. One can select the name of the given project(s) only within the exhaustive list of projects registered to the Phis instance where the new document is uploaded.

Concerned Experimentation. Experiment(s) for which the new document is relevant. A Phis user can select the name of the given experiment(s) only within the exhaustive list of experiments it has access to.

Document Type. The nature of the document's content. A single type has to be selected from a predefined list. Only one doucment type can be selected. Phis controlled vocabulary of document types is defined in Phis ontology. If an element seems to be missing from the proposed predefined list, please contact Phis managers (see README.md for Phis managers contact).

File. This field enables Phis users to upload the new document from their computer through the Browse button. Only one document at a time can be created, since every document is identified uniquely through an automatically generated URI. The uploaded file cannot be empty (it has to exceed 0B). For now, a document cannot exceed 2MB, due to technical problems encountered with Apache server.

Once the file has been uploaded, do not click on the Upload button but Create underneath, only when all fields have been completed. The upload button is bound to be abandonned in the following Phis development.

upload-file

Comment. Complete plain text description of the new document, preferably provided in English language. For now, line breaks cannot be inserted in a comment: they could generate a bug.

Click on the Create button to complete the document creation, i.e. the document upload and the specification of its metadata with Dublin Core standards.

The list of documents a given user has access to is avaible from the navigation bar through the Tools > Documents menu. From Home / Documents, one can click on the eye icon on the right to see a given document information sheet (metadata). From there, the document cannot be modified or deleted (in Phis current version). However, the document metadata can be modified with the Update button on top of the information sheet. The document can also be downloaded clicking on the view icon above the View / Download text, below the information sheet.

update-document

Scientific Objects

Object types

Plant phenotyping experiments all revolve around one entity of interest: plants ! However, plants can be studied at various scales, from a single leaf to a field. Phis experiments register data on elementary units: scientific objects (also refered to as agronomical objects), which are no more than declinations of plants, at various scales:

These scientific objects, forming the basic units of experimentations, are observed through time, and consequently constitute the origin of phenotypic data.

A given scientific object is required to be associated with one experiment, and one only. Phis development team is aware of the challenge in declaring perennial plants studied over several years. One might want to declare it in various experiments, each experiment matching a different time-period. Phis development team is open for discussion on this matter with its user.

Phenotypic data created in an experiment, whether it is directly measured, calculated or estimated, is necessarily linked to scientific objects.

Every scientific object is uniquely identified through a standardized URI which is automatically assigned by Phis when it is first entered in the system by a user. Metadata is associated to objects under the form of attributes: the object alias, its type (plant, plot, etc.), the experiment it is part of, etc. Data associated with these objects consists of the values of phenotypic variables (declared in Phis through the Variables menu) linked to these objects during the Data import process.

The complete list of scientific objects declared in Phis is available in the Scientific Objects menu, accessible from Phis top navigation bar. Phis users with a restricted access (e.g. guest) are likely to be unable to see the Scientific Objects menu, since there are no objects for them to see. The scientific objects list is preceded by a research bar enabling the user to filter objects by their URI, Alias, type and the experience they are linked to. The scientific objects list also displays additional properties (the objects species, variety, etc.). The list of objects associated with a search result, and their metadata, can be retrieved as a .csv file with the Download Search Result button.

scientific-objects-list

Scientific objects information can also be accessed through the Experiments menu. After having selected an experiment, the scientific objects linked to it can be displayed on a map. Moreover, selecting objects on such a map provides additional information on the attributes of these objects. See the Map Visualization section for more information on that matter.

Importing scientific objects

Within the Scientific Objects menu, Phis users can import new plots with the Create button.

Scientific objects such as plots are imported into Phis through an editable table in which each row contains the information of an additionnal scientifc object to be inserted in Phis database.

One can also copy and paste in this table the content of a .csv file whose header is:

Alias;Type;Experiment;Geometry;Parent;Species;Variety;ExperimentModalities;Replication

Description of the content of this table, column by column:

Generated URI. Field to leave blank. Every new scientific object will be automatically assigned an URI when declared in Phis.

Alias. Internal name of the scientific object (free text). In a given experiment, there can not be two identical aliases.

Type. Type of the scientific object, chosen from a closed list containing:

There is only a handful of proposed scientific object types in the current ontology: do not hesitate to contact OpenSILEX development team to add object types that cannot be found in the list in order to make it evolve. If the dropdown list isn't displayed correctly, try selecting any element of the list: the column width will then expand automatically.

Experiment. URI of the experiment the declared scientific objects belong to. If this field is not filled excusively with URIs of experiments stored in Phis, then no scientific object will be added to the system. The experiments URIs can be selected from a dropdown list displaying all experiments declared in the system. If the dropdown list isn't displayed correctly, try selecting any element of the list: the column width will then expand automatically. Note that as described in the Modifying scientific objects section, it is possible to link a scientific object to several experiments in two steps. From the Scientific Objects menu :

  1. Using the Create button, create scientific objects with a given experiment URI in the Experiment column
  2. Using the Update button, copy and paste the table used in the scientific object creation, and then replace the value of the Experiment column with another experiment URI
  3. Repeat the step 2 everytime you want to associate the same scientific objects to another experiment

Geometry. Optionnal. Vector geometry such as polygons (for plots), provided according to Well-known text standard). Geometry coordinates are formatted in WGS84, also known as the EPSG4326 geodetic coordinate system. More information on this system here. A quick way to draw WKT polygons from a map is to use the "draw a shape" tool of the sandbox website. However, it is recommended to use professional geographic information systems such as QGis.

Parent. Optionnal. URI of the parent scientific object, for example the URI of a previously declared plot when declaring in the system a plant that has been harvested from this plot. Another example is a plant URI which can be used as a parent of a plant organ being declared.

Species. Optionnal. The URI of the species of a plant, a plant part or plot (free text). The Species URIs can be selected from a dropdown list displaying all species URIs declared in the system. If the dropdown list isn't displayed correctly, try selecting any element of the list: the column width will then expand automatically. The complete list of species found in Phis is displayed in the Experimental organization / Species menu, described in the Species section of this documentation.

Variety. Optionnal. The variety of a plant or a plant part or the variety of a plot (free text).

Additional scienfic object properties that can be declared through the web services but not through the web client:

ExperimentModalities. The experiment modality of the plot, no controlled vocabulary required so far (e.g. "WD" for water deficit). (free text).

Replication. The repetition of the scientific object mostly used for plots (e.g. 1, 2, A, or B...). (free text).

Insertion status. Automatically filled when clicking on the Create Scientific Objects button : this indicator shows which new scientific objects have been created and which one have failed to be added to the system.

Every other additional line matches with a new scientific object.

Let's take into consideration a fictionnal experiment composed of 4 plots of the same crop ("Species"). In half of the plot, the variety "A" of the studied crop is grown, and in the other half, the variety "B". Of two plots dispaying the same variety, one is submitted to an experiment modality labelled "treatment 1", while the other is submitted to a "treatment 2". Experiments and Species have to be expressed with their internal Phis URI. This configuration is sum up in the following table:

Alias Geometry ExperimentURI Species Variety ExperimentModalities Replication
plot1 POLYGON (( ... ... , ... ... )) URI Experiment X URI Species Y varietyA Treatment1 Rep1
plot2 POLYGON (( ... ... , ... ... )) URI Experiment X URI Species Y varietyA Treatment2 Rep1
plot3 POLYGON (( ... ... , ... ... )) URI Experiment X URI Species Y varietyB Treatment1 Rep1
plot4 POLYGON (( ... ... , ... ... )) URI Experiment X URI Species Y varietyB Treatment2 Rep1

The file necessary to import those four plots is a 5 line csv file: after the header, every line of the imported file needs to display the 7 required elements, for instance separated by semicolons (or commas):

Alias;Geometry;ExperimentURI;Species;Variety;ExperimentModalities;Replication
plot1;POLYGON (( ... ... , ... ... ));URI Experiment X;URI Species Y; varietyA;Treatment1;Rep1
plot2;POLYGON (( ... ... , ... ... ));URI Experiment X;URI Species Y; varietyA;Treatment2;Rep1
plot3;POLYGON (( ... ... , ... ... ));URI Experiment X;URI Species Y; varietyB;Treatment1;Rep1
plot4;POLYGON (( ... ... , ... ... ));URI Experiment X;URI Species Y; varietyB;Treatment2;Rep1

Such a file can be then copied and pasted to the handsontable form.

A single scientific object cannot correspond to several species, variety, experimental modality or replication. On the contrary, the same species, variety, experimental modality or replication can be used for several scientific objects.

Some scientific object type such as plots can be described by geometrical objects such as polygons, whose GPS coordinates are provided following the Well-known text standard).

The first step in order to import scientific object is usually to create a .csv file containing all the new plots information, as is reminded below:

Alias Geometry ExperimentURI Species Variety ExperimentModalities Replication
expX_modY_plotZ POLYGON (( ... ... , ... ... )) http://www.phenome-fppn.fr/.../... http://www.phenome-fppn.fr/id/species/... e.g. varietyX e.g. nitrogen-1 e.g. 1 (or A-I)

The second step is to copy and paste the content of the CSV file in the handsontable form displayed in the Home / Scientific Objects / Create Scientific Object menu and then click on the Create Scientific Objects bottom button to complete the declaration of scientific objects.

new-objects-create

Modifying scientific objects

Within the Scientific Objects menu, Phis users can modify the properties of existing scientific objects with the Update button.

Scientific objects such as plots are modified through an editable table in which each row contains the information of an additionnal scientifc object to be modified in Phis database.

Even if you want to change the value of only one property of an experimental object (i.e. its experimental modality), you need to provide in the handsontable all of its former properties that you want to keep (e.g. type, species, etc.), otherwise this information will be lost.

It is not possible to change the experiment to which a scientific object participates, however it is possible to state that a scientific object participates in various experiments. In order to assign scientific objects to two experiments, one has to create those scientific objects through the Create button of the Home / Scientific Objects menu, assigning them to a first experiment, and then submit the same table through the Update button, with the exception of the "ExperimentURI" field which will display of URI of the other experiment the new scientific objects belong to.

Visualize scientific objects

See Map Visualization section.

Species

The complete list of species registered in a Phis session is available in the Experimental organization / Species menu, accessible from Phis top navigation bar.

This list comes handy when declaring the species a scientific object belongs to. Instead of using free text when specifing a species, we choose between the available species URI. This procedure prevents the use of various names for the same entity, e.g. triticum aestivum and bread wheat.

There is only a handful of proposed species in the current ontology: do not hesitate to contact OpenSILEX development team to add species that cannot be found in the list in order to make it evolve.

Variables

Variables properties

Phis variables characterize Phis scientific objects or their environment. Variables characterizing scientific objects are phenotypic variables, while variables characterizing the environment in which those scientific objects are studied are refered to as environmental variables. Phis variables can be either directly mesured by a sensor, either computed from one or several variables.

Every variable produced by an experiment must have been previously created in Phis, and every variable created in Phis has to be defined unambuigusously. Consequently, when a user refers to a variable in an experiment, there is no ambiguity about the concept he is refering to. Moreover, the usage of unequivocal variables in experiments is a necessary step towards a more intelligible, reliable and reproducible Science.

Phis variables are listed in the Variables menu. A Phis user with a restricted access (e.g. guestphis) is likely to be unable to see the Variables menu, since there is no variable for her/him to see.

Variable definition is based on the Crop Ontology guidelines (draft document). Therefore, Phis variables are all unequivocally characterized by the following triplet:

Further information on a given variable is available on its information sheet, accessed to from the variables list through the eye-icon on the right-hand side of this project row.

variables-list

A variable information sheet provides knowledge on this variable, but also on the three elements that define it, namely the trait, method and unit related to this variable. The variable and those three defining features all display a label, that should be meaningful and unique, but does not have to be so, an URI which is however unique, a Definition (or Comment) meant for human comprehension, and related references meant for Semantic Web applications. Reference to external ontologies is achieved through SKOS standards

NB: for now, only phenotypic variables are present

Create variables, traits, methods and units

Every variable found on Phis has been previously created by a Phis user. Within the Variables menu, one can create a new project with the Create Variable button.

Variable label. This field is automatically produced with the concatenation of the trait, method and unit labels, separated by underscores. The resulting variable label is not necessarily unique, but it would be better if it was. On the contrary, the automatically generated URI (not shown in the Create Variable menu) is unique.

Trait. If the trait associated to the new variable has already been created in Phis, one can select it through the predefined list of the Trait label field. Otherwise, it has to be created, which can be achieved by clicking on the + green icon on the right-hand side of the Trait label field.

new-trait

In the case of a new trait, do not fill the Trait label field but the Internal label one, below the - red icon that replaced the + green icon. This new trait label should be if possible meaningful, distinct from other trait labels, and underscores "_" should be avoided since trait, method and unit labels are concatenated to generate the new variable name with the format Trait_Method_Unit.

A Comment should be added, preferably in English, in order to explicit the trait specifics as clearly as possible.

new-trait-label

Method. If the method associated to the new variable has already been created in Phis, one can select it through the predefined list of the Method label field. Otherwise, it has to be created, which can be achieved by clicking on the + green icon on the right-hand side of the Method label field.

new-method

In the case of a new method, do not fill the Method label field but the Internal label one, below the - red icon that replaced the + green icon. This new method label should be if possible meaningful, distinct from other method labels, and underscores "_" should be avoided.

A Comment should be added, preferably in English, in order to explicit the method specifics as clearly as possible.

Unit. If the unit associated to the new variable cannot be found on the Unit label predefined list, a new unit has to be created. This can be achieved by clicking on the + green icon on the right-hand side of the Unit label field. In the case of a new unit, do not fill the Unit label field but the Internal label one, below the - red icon that replaced the + green icon. This new unit label should be if possible meaningful, distinct from other unit labels, and underscores "_" should be avoided.

Otherwise, if the appropriate unit is already register in Phis, then one only has to select it from the Unit label field, without clicking on the + green icon (or clicking on the - red icon if the + green icon had previously been clicked on).

In the tricky case of a variable presenting no unit (e.g. pH), it is advised to crete a new unit whose label would be: dimensionless_unit_variable-name (e.g. dimensionless_unit_pH). It matters in order not to use the same "unit" for every variable displaying a dimensionless unit. More on this topic on the ontobee.org website.

existing-trait

Related References. In order to unambiguously define the new variable, semantic relations are established by the user between the new variable and concepts already defined in reliable ontologies existing on the world wide web. These relations to external ontologies are established using SKOS (Simple Knowledge Organization System).

Entity refers to the Phis entity that will be associated to a concept found in an ontology. This Entity be either the new variable, trait, method or unit. It is not required to specify related concepts for traits, methods and units, however it is recommanded.

Relation refers to the nature of the relation between the entity and the concept defined in an ontology. This semantic relation is provided using SKOS. The entity can either be, compared to an ontology concept, an exact match, a close match, narrower or broader.

SKOS mapping properties, skos:closeMatch and skos:exactMatch, are used to state alignement links between SKOS concepts, as indicated in the w3 SKOS Mapping properties web page:

SKOS hierarchical properties skos:broader and skos:narrower are used to assert a direct hierarchical link between two SKOS concepts, as indicated in the w3 Semantic Relations web page:

By convention, skos:broader and skos:narrower are only used to assert a direct (i.e., immediate) hierarchical link between two SKOS concepts. This provides applications with a convenient and reliable way to access the direct broader and narrower links for any given concept. Note that, to support this usage convention, the properties skos:broader and skos:narrower are not declared as transitive properties.

Reference URI refers to the URI of the concept found on ontologies such as the ones suggested in the short list above the Related References field. The URI provided here is not necessarily the URL of the web page of the ontology on which the targeted concept is defined. Indeed, the URI of a given concept does not necessarily match with the URL of the web page where this concept has been found. Example: http://www.cropontology.org/rdf/CO_322:0000907 is the URI of the concept "Silk_Date_ymd" of the Crop Ontology. WARNING: using the identifier (e.g. CO_322:0000907) is not sufficient.

Hyperlink (optionnal) refers to the URL where are located the related concept whose URI has been provided in the previous field. Example: http://www.cropontology.org/rdf/CO_322:0000907 is the hyperlink (URL) associated to the URI of the concept "Silk_Date_ymd" of the Crop Ontology. In this example, the URI of the concept is also an URL (a hyperlink), but it is not the case for every ontology.

When a variable is created, multiple references using SKOS can be stated, using the + white icon.

add-relation-to-a-reference

Which portals provide a link towards various ontologies ?

The AgroPortal project aims to offer a reference ontology repository for agronomy, reusing the NCBO BioPortal technology, as stated on the FAO website. The scientific outcomes and the experience of the biomdical domain are thus exploited and transposed into the agronomy domain, including plants, food, environment and possibly animal sciences.

The Ephesis Ontotology Portal is a JavaScript widget displaying all the observation variables of a Breeding API endpoint. It lists ontologies available with the BreedingAPI/CropOntology JSON format.

Here are some examples of ontologies:

The Crop Ontology (CO) current objective is to compile validated concepts along with their inter-relationships on anatomy, structure and phenotype of crops, on trait mesurement and methods, as well as on germplasm with the multi-crop passport terms.

The Plant Ontology (PO) is a structured vocabulary and database resource that links plant anatomy, morphology, growth and development to plant genomics data. The URL provided here redirects visitors to the Planteome website since PO is developed by the Planteome Project, alongside with other reference ontologies listed in the Planteome Ontologies webpage. The Planteome project is a centralized platform where reference ontologies for plants will be used to access plant genomics data.

The Unit Ontology gathers metrical units for use in conjunction with PATO (Phenotype And Trait Ontology), which is a phenotypic quality ontology.

Which other ressources, besides ontologies, can I link my variables to ?

AGROVOC is a controlled vocabulary covering all areas of interest of the United Nations Food and Agriculture Organization (FAO), including food, nutrition, agriculture, fisheries, forestry, environment, etc. It is published by the FAO and edited by a community of experts. More information is provided on the FAO website.

Variable Definition. Text defining clearly the concept underlying the new variable. This definition should ideally be provided in English.

Modifiy existing variables

So far, it is not possible to modify or delete an existing variable, other than by asking a Phis developper.

Dataset

Dataset properties

The heart of experiments is to produce datasets associated with the agronomical variables it studies. High-throughput plant phenotyping platforms commonly set up experiments in which plant growth is monitored. Plant growth dynamics are analyzed through the evolution of various variable (e.g. LAI, NDVI, etc.) through time.

At this stage of development, all dataset variables are quantitative. No qualitative variables are saved in the datasets: a variable from a dataset can only assume numerical values and no character string is allowed.

A dataset typically displays information on many scientific objects. These objects can be described by several variables. Each one of these variables can assume diverse values at different dates. In order to avoid confusion, each element of a dataset should then be understood as a triplet object-time-variable. Thus, each element of a dataset is associated uniquely with

Datasets are available indirectly through the Experiments menu, selecting an experiment and then accessing to its map through the Map Visualization button.

Graphics can be extracted from the experiment datasets in the Dataset(s) Visualization (On selected plot(s)) section, which appears under the map of the experiment when scientific objects are selected. How to create such graphics is explained in the Map Visualization section of this documentation.

Import Dataset

Datasets can be added to Phis through the Dataset menu in the top navigation bar. A Phis user with a restricted access (e.g. guestphis) is likely to be unable to see the Dataset menu. Indeed, only users that are part of an owner group are authorized to add datasets to the experiments associated to this group. Go to the Groups level of access section for further information on this issue.

When adding a dataset to Phis, three types of elements can be created:

Quantitative Variable. Mandatory field. Variable or list of the variables found in the added dataset. The variable(s) must have previously been defined in Phis (see Variables).

Dataset Creation Date. Mandatory field. Date in the YYYY-MM-DD (year-month-day) format matching to the day in which the imported data has been generated. Let's take the example of a drone flight performed two weeks before the data import, followed by the production of clean data from the flight images one week before the import. The imported data is the clean data created one week before the data import. Therefore, the date to provide in Dataset Creation Date is the one corresponding to one week before the data import. This field is necessary for provenance purposes.

Was generated By. Optionnal document giving indications on how the data has been created. If a single script (e.g. in R or python language) has been used to create the imported data, it should be uploaded here. If the data creation process has been more complex, a document (e.g. PDF or text) could be provided to describe it. The document import is performed via the Add Document Script button. The metadata to provide is the same as in any Phis document, see the Upload a document section. Only one document can be added to this field. More documents can be imported together with the dataset through the Linked Document(s) field.

add-script-generating-dataset

Description. Informative plain text description of how the imported data has been generated, preferably provided in English language. For instance, if the data has been generated with Phenoscript v1.2, one can mention it here, especially if the concerned script cannot be imported.

Linked Document(s). Additionnal documents associated with the dataset and imported to Phis. Click on the Add Document button and then fill out the usual document creation form as described in the Upload a document section. Multiple documents can be uploaded and associated to the imported dataset. Click several times on Add Document in order to add several documents.

add-document-linked-to-dataset

Data File. This mandatory field is used by users to upload the dataset from their computer through the Browse button.

add-dataset-browse-file

The dataset added to Phis must respect some file rules:

In the following example, the added dataset exhibits information on two objects, one of them (URI1) displaying values for one variable at three different dates, and the other one (URI2) displaying values for two variables at the same dates:

ScientificObjectURI;Date;VariableAlias1;VariableAlias2
URI1;2017-04-01;;5
URI1;2017-04-15;;10.0
URI1;2017-04-31;;12.00
URI2;2017-04-01;3.22;6
URI2;2017-04-15;4.12;9
URI2;2017-04-31;5.347687869;10

The URI of the scientific objects of a given experimentation can be found on the Scientific objects menu, using search filters, and then downloaded with the Download Search Result button (see the Object types of this documentation). All variables values of the imported dataset are associated with scientific objects that must have been previously declared in Phis (see Importing Scientific Objects).

The data file imported in Phis can displays many fields (i.e. number of items in the header), but only the column matching with the expected fields will be kept. The expected fields and their name are provided in the .csv template provide by the Download Template link above the Data File field. Hence, users can copy and paste their data in the template file (keeping the header unchanged), or import directly their datasheet as a .csv, after having renamed correctly the fields as described in the template.

add-dataset-open-datafile

In order to finalize the addition of the dataset, click on the bottom Create button.

add-dataset-create

The waiting time following the use of the Create button can relatively long, depending on the quantity of variable values added. If an error occurs, the dataset is not added to Phis and an error message is displayed.

add-dataset-unknown-object

Else, the dataset is imported in Phis and a success message is displayed.

add-dataset-success

At the current stage of Phis development, datasets cannot be modified nor deleted once it has been added to Phis.

Visualize Dataset

Graphics extracted from Phis datasets are available through the Experiments menu. See the Map Visualization section of this documentation for further information.

Annotations

What are annotations ?

Annotations are comments made on an element of Phis and stored as metadata linked to this element. More broadly, the W3C describes annotations as "typically used to convey information about a resource or associations between resources". An annotation can be an explanation given by the creator of a resource, an expert viewpoint or the input of other persons. Phis projects, experiments, sensors, vectors, etc. (any element displaying an URI) can be annotated using the W3C specifications of the Web Annotation Data model, or oa (prefix of the Web Annotation Data Model, whose namespace is http://www.w3.org/ns/oa#). Any user can therefore enrich Phis elements with attached information (metadata) using semantic annotations.

Add annotation

Annotations can be added to Phis through the Add annotation button of the information sheet of any project, experiment, sensor or vector.

Creator. The username of the creator of the annotation (you) is automatically recorded by Phis whenever you create an annotation.

Motivated by. Following W3C recommendations on annotation motivations, when creating an annotation you need to select through the controlled vocabulary of oa the motivation category matching the reason why you are creating this annotation:

Creation Date. Automatically set by Phis using the local time.

Targets. Automatically set by Phis, this field records the resource (e.g. experiment) from which an annotation creation has been requested by the user (i.e. from which resource he clicked on the Add annotation button).

Description. Content of the annotation, ideally provided in English (free text).

Events

What are events ?

Events are crucial pieces of information used to enrich Phis datasets. Events are ponctual occurrences happening during an experiment, and potentially having an impact on the recorded data. Those events can be either planned (e.g. a sowing date) or unexpected (e.g. damages to a field experiment caused by wild animals).

Events, like simple annotations, are created following the Open Annotation Data Model that allows assigning motivation and purpose attributes to annotations (e.g. oa:describing, oa:identifying, oa:linking, oa: replying, etc.). Dublin Core and foaf specifications such as dcterms:created, dcterms:creator, foaf:Agent are also used.

Ontology of Experimental Events

An application ontology developped at INRA Montpellier, compliant with the standards of OWL, provides the structured vocabulary necessary to describe all events created and then stored in Phis: it is the Ontology of Experimental Events (OEEv), hosted by AgroPortal. It can be accessed to from agroportal.lirmm.fr/ontologies/OEEV.

The Ontology of Experimental Events, characterises events that occur during an experiment, e.g. dates of sowing, application of a given treatment, harvesting, measurements or sampling for -omic measurements, or any category of technical problem. The OEEv ontology contains four groups of events, namely Facility Management, Scientific Object Management, Trouble and Displacement.

Facility Management

The Facility Management refers to the set of actions related to the management and maintenance infrastructure and supporting equipment. It describes events related to servicing, maintenance and calibration of equipment or installations.

Scientific Object Management

The Scientific Object Management contains different sub-categories of events related to the typical operations conducted on plants or plots in experiments:

Trouble

The event Trouble is defined by three different sub-categories:

Several subtypes of incidents that often occur in platfortm or field experiments have been declared including:

Displacement (object tracking)

The Displacement event has been created to follow the position in time and space of the different objects participating in experiments. For instance, plants are often transferred, during a single indoor experiment, between installations or compartments with different environmental conditions. Similarly, sensors can be replaced or moved to different positions in the field or greenhouse. The MoveTo and MoveFrom concepts allow tracking objects.