A digital experiment is a digital procedure to conduct data analysis in order to explore or validate scientific hypotheses or to process your data in a production mode. Digital experiments involve a range of activities, such as developing and testing bioinformatic protocols, conducting simulations, or analyzing data with sophisticated methods like machine learning or AI algorithms.

In this page, you can access to step-by-step tutorials and spotlight videos related to digital experiments. For example, you can learn how to create and manage digital experiments. We recommend reviewing the page about the virtual laboratory ecosystem as a prerequisite to better understand the content here.

How to create a digital experiment?

To create an experiment, click on the + button from the experiments page and then choose a title for your experiment. You can select or import a protocol template to pre-configure you experiment (see protocol documentation). You can attach your new digital experiment to a project - however, you will be able to change this parameter later. If you want to know how to connect a project to a digital lab, please check out the page Manage your lab.

To create a digital experiment, follow these steps:

1. Go to the experiments page.
2. Click on the + on the top right corner.
3. Choose a title for your experiment.
4. You have the option to select or import a protocol template to pre-configure your experiment. For more details, refer to the protocol documentation.
5. You can attach your new digital experiment to a project. Keep in mind that you can modify this parameter later if needed. If you need guidance on how to connect a project to a digital lab, please refer to the Manage your lab page for detailed instructions.

How to add a process to an experiment?

After creating your experiment, you can set it up by adding a process. A process is an operational component that can be connected with resources or other processes to execute data analysis. A process can take the form of a standalone block, referred to as a Task, or it can be a more complex structure known as a Protocol, which is made up of a sequence of interconnected Tasks and Resources.

To facilitate the organization and access to processes, they are grouped into bricks. A brick serves as a library or collection of processes and associated resources. These bricks provide a structured way to manage and reuse processes across different experiments.

Here's how you can add a process to your experiment:

1. Open the playground of the experiment.
2. Click on the + button and choose Add a process from the menu.
3. A pop-up appears, presenting a list of all processes accessible within your digital lab. This list is contingent upon the bricks previously installed into the lab, as well as their respective versions. The search menu allows you to search for processes either by name, brick or type of process. You can also access the process documentation by clicking on the i button.
4. Select the desired process from the list (e.g., Table column scaler).
5. You should now see a new box in the playground with the name of the process added to your experiment.

If you wish to remove a process from your experiment, you can simply right-click on the process box and select the X button to delete it.

Interact with process ports

Process ports are represented by small circles. A majority of processes has at least two ports, one port as input and one port as output. However, processes can possess multiple input and output ports. These ports are used to connect the process with resources or other processes to create a pipeline (see the figure below). Please note that from output ports, you can connect multiple objects. For example, on the figure below, the first Task (Table columns selector, grey box) is connected to a Sink (an output that will become a new Resource after running the experiment) and also connected to a second Task (Table rows deleter). However, input ports do not accept multiple objects.

To establish the connection, simply hold down the left mouse button while dragging from one port to another to create a link. To remove the link, right-click on it; a cross will appear, allowing you to delete the link.

When you click on a port multiple options are available:

• Select a resource (for input port only): this option allows you to connect a resource to the input port.
• Add an output (for output port only): This option adds a special box dedicated to quickly accessing the output of the process. It automatically flags the output resource, making it visible in the Databox for further use.
• Add a viewer (for output port only): This option adds a special box designed to pre-configure a view of the resource.
• Add a transformer (for output port only): This option adds a transformer connected to the process. A transformer is a specialized Task designed to take one input (typically a Table) and generate one output of the same type. The available transformers will depend on the selected port type.
• Suggested processes: This option opens a pop-up displaying a selection of processes based on the port type. It shows only the processes compatible with that specific port.
• Resource: This option is accessible when the resource in output is available (usually after the experiment has been run) and enables you to view the resource associated with that port.

How to add a resource to an experiment?

To provide data (resources) to your experiment, you have two options:

Option 1:

1. Click on the + button and then select Select a resource from the options.
2. This will open a popup where you can view the list of your resources.
3. Search and select the desired resource from the list.

Option 2 (recommended):

1. Click on an input port of a process in your experiment.
2. Click on Select a resource option.
3. This option is designed to only show resources compatible with the selected port. It ensures that you choose a resource that can be connected to that specific port.
4. Once you select the resource, it will automatically be connected to the input port.

To delete a resource from your experiment, you can follow the same process as deleting a process. Right-click on the resource and click on the X button to remove it.

How to configure a process?

To configure a process in your experiment, you can follow these steps:

• Open the experiment playground and locate the process you want to configure.
• To configure the process, click on the configuration button on the box. You can also click on the i button to open the right panel containing information about the process and then click on the CONFIGURATION button.
• This action will open a pop-up page with a dashboard.

• In the center section of the dashboard, you can update the configuration of the process according to your requirements.
• If the process is connected to one or more resources, you can access and configure them by clicking on the respective tab on the left side of the dashboard. This allows you view input while configuring the process.
• Similarly, if the process has generated output resources from a previous successful execution, you can open and configure them by clicking on the corresponding tab on the right side of the dashboard.

At the top of the dashboard, you will find additional information and actions related to the process:

• The status of the process.
• A Save button allows you to save the configuration changes made to the process.
• A Save and Run button enables you to save the configuration and initiate the execution of the process.
• A menu button provides access to documentation, process messages, logs, and monitoring features. It also includes a Reset Processbutton.

How to run an experiment?

To run an experiment, simply click on the play button within the experiment playground. Alternatively, you can run the experiment from the process dashboard as well.

Once initiated, the experiment will be added to the experiment queue (status waiting). It will start running once all the previous experiments in the queue have finished. You can refer to the instructions on How to check the experiment queue ? for more information.

The experiment's status will automatically change to Running, indicating its active execution. Once the execution is completed, the status can be Success if everything went well, or Error if at least one process did not finish.

In the playground, you will be able to track the progress of the experiment and view intermediate results during its execution. Additionally, you can access processes messages, logs, and monitoring features to gain insights into the experiment's performance and behavior during the execution process.

If needed, you can stop the experiment at any time by clicking on the stop button. This action will mark the currently running process as an error. It's important to note that the intermediate results will still be available, and you will have the option to resume the experiment from the stopped process.

How to update an experiment?

After running an experiment, the status can be Success if everything went well, or Error if at least one process did not finish. To update an experiment, you have two options. The first option is to reset your experiment. In this case, all processes will be reset, and your outputs (such as generated resources) will be removed from both the experiment and the Databox. The experiment's status will change to Draft. However, the configuration of each process will remain unchanged.

To reset an experiment, click on the menu button from the experiment page, and select Reset experiment.

The second option involves directly modifying the playground by adding a resource, a process, or by adjusting the configuration of a process. In this scenario, processes and resources remain unchanged. The experiment is updated based on the actions you perform within the playground, and the experiment's status will change to Partially run.

How to describe an experiment?

To describe your experiment and provide an explanation of its purpose and functionality, follow these steps:

1. Open the Details section of the experiment.
2. In the description field, you can provide a clear and concise description using simple styles such as bold, lists, or titles to enhance readability and organization.

How to manage an experiment?

The menu button on the experiment page provides access to various information and functionalities. Here are the options available:

1. Create Report: This allows you to create a report associated with the experiment. You can include views from resources generated by this experiment in the report.
2. Protocol:
1. Create Protocol Template: You can create a protocol template to save the configuration of the experiment and reuse it in new experiments. Refer to the protocol template documentation for more information.
2. Download Protocol Template: Download a descriptor file of the protocol template to use it elsewhere, such as in another lab or for documentation within community.
3. Update Experiment: Update the information about the experiment.
4. Validate the Experiment: Synchronize the experiment with the space and mark it as validated. Refer to the "How to Validate an Experiment" documentation for more information.
5. Reset Experiment: Reset all the processes of the experiment and delete all generated resources. Note that this is not possible if an output resource is used in another experiment. The configuration of the processes will be retained.
6. Tags: Update the tags associated with the experiment to simplify organization and categorization.
7. Duplicate Experiment: Create a new draft experiment with the same configuration as the current experiment. This option allows you to quickly create similar experiments based on an existing one.
8. Monitoring: Access messages, logs, and monitoring features at the experiment level. This allows you to track and monitor the progress and status of the experiment.
9. Archive Experiment: Mark the experiment and generated resources as archives. Archived experiments will be hidden by default in the experiments page (and resource hidden in databox), providing a way to declutter and organize your workspace.
10. Delete Experiment: Delete the experiment and its generated resources. Note that this option is not available if an output resource is used in another experiment or if the experiment is validated.

How to synchronize an experiment ?

The synchronization allows you to synchronize an experiment and its configuration with your space. After synchronization, the project team can access the experiment and its technical information even if they do not have access to the digital lab. The synchronization with the project space allows the project leader to track the progress of the data analysis and, more importantly, ensures the reproducibility of the analysis. However, the synchronization of an experiment does not synchronize the associated resources.

To synchronize an experiment with your space, follow these steps:

1. Open the experiment you want to synchronize.
2. Check if the experiment is attached to a project. If not, please refer to Manage the experiment to associate it with a project. The experiment must be associated to a project before synchronisation to be properly located in your space. You need to have access to the project in the space in order to synchronize the experiment.
3. Once the experiment is associated with a project, click on the Sync with space button. If the button is disabled, it means that the experiment is not associated to a project.
4. After synchronization, the experiment and its protocol configuration will be available in your space. Anyone with access to the project will be able to see the synchronized experiment.

How to validate an experiment ?

The validation process involves permanently freezing an experiment and its associated results. Validation takes place when the analysis is complete and the experiment meets your expectations—usually when you're prepared to document the final results. This process ensures that the experiment's state and configurations are finalized, preventing further modifications. To ensure reproducibility, traceability, and to prevent unintended changes, the validation process is NOT reversible. Throughout validation, the experiment will automatically synchronize with your space (see How to synchronize the experiment?). This requirement implies that your experiment must be associated with a project to undergo validation.

To validate the experiment, follow theses steps :

1. Make sure the experiment is associated with a project. If it is not associated with a project, please refer to the instructions on Manage the experiment to associate it with a project.
2. Ensure that the experiment is in its desired and final state, as validation is not reversible.
3. Click on the menu button of the experiment then Validate experiment button
4. The experiment will be marked as validated, and it will be locked from further modifications.

After the validation, your experiment will be stored and accessible in your project space. You can also find all validated experiments from the experiment page. Using the search menu, select the button "Include validated experiments" in order to display both validated and unvalidated experiments.

How to check the experiment queue ?

To check the list of running experiments and experiments in the queue, follow these steps:

1. Click on the Settings menu.
2. Select Execution Queue from the options.
3. The Execution Queue page will display the list of running experiments and experiments in the queue.

In the list, you can see the last message of the running experiment, which can be useful for tracking its progress.

To remove an experiment from the queue, locate the experiment in the list and click on the Stop button associated with it