Scenario

A scenario 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. Scenarios 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 scenarios. For example, you can learn how to create and manage scenarios. We recommend reviewing the page about the virtual laboratory ecosystem as a prerequisite to better understand the content here.

How to create a scenario ?

To create a scenario, follow these steps:

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

How to add a process to a scenario ?

After creating your scenario, 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 scenarios.

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

1. Open the playground of the scenario.
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 data 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 scenario.

If you wish to remove a process from your scenario, 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.

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 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 scenario has been run) and enables you to view the resource associated with that port.

How to add a resource to a scenario ?

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

Option 1 (recommended):

1. Click on an input port of a process in your scenario.
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.

Option 2:

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.

To delete a resource from your scenario, 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, simply open the scenario playground and click on the process. This will open the process 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 a scenario?

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

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

The scenario'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 scenario and view intermediate results during its execution. Additionally, you can access processes messages, logs, and monitoring features to gain insights into the scenario's performance and behavior during the execution process.

If needed, you can stop the scenario 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 scenario from the stopped process.

How to update a scenario?

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

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

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 scenario is updated based on the actions you perform within the playground, and the scenario's status will change to Partially run.

How to describe a scenario ?

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

1. Open the Details section of the scenario.
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 a scenario ?

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

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

How to synchronize a scenario ?

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

To synchronize a scenario with your space, follow these steps:

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

How to validate a scenario ?

The validation process involves permanently freezing a scenario and its associated results. Validation takes place when the analysis is complete and the scenario  meets your expectations—usually when you're prepared to document the final results. This process ensures that the scenario'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 scenario will automatically synchronize with your space (see How to synchronize a scenario ?). This requirement implies that your scenario must be associated with a folder to undergo validation.

To validate the scenario, follow theses steps :

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

After the validation, your scenario will be stored and accessible in your space. 

How to share scenarios between data labs?

Share from a share link

Sharing scenarios between data labs is easy, it allows one data lab to download a scenario generated by another data lab. To do so, follow these steps:

1. Open the Scenario detail page.
2. Click on menu buton ⁝ then Share button.
3. The share object popup will appear. If there is no share link, you can create a new one. If there is a share link, it will be displayed. At the bottom of the dialog, you can access the list of data labs that used the shared link and downloaded the scenario, which can be useful for traceability.
4. If you don't have an existing sharing link, click on the Create share link button to create a new share link.
5. Provide an expiration date for the link and click on save.
6. The share link will be generated. You can copy the Download link, update its validity, or delete it if needed.

To download the scenario in a different data lab follow these steps

1. Copy the link.
2. Open the data lab.
3. Open the Scenarios page, and click on Import a scenario from another lab.
4. Paste the link and choose your options:
1. Resource mode: Decide which resources to download.
2. Create option:
1. Skip if exists : Skips the download if the scenario already exists. It also reuse existing resources.
2. Force new scenario : Creates a new scenario and resources even if they already exist.
5. Click on Ok to start the transfer. A scenario will be created in the data lab to monitor progress.

Send a scenario to another lab (e.g. a datahub)

If you frequently send scenarios to the same lab (e.g., a datahub), you can set up a connection between the two labs to simplify the process.

Share credentials between labs

To create a connexion between the two lab, check this : Connect two data labs

Send a scenario

After setting up credentials in both labs, you can send scenarios:

• Open the scenario details page.
• Click on menu buton ⁝ then Share button.
• Click on Send scenario to lab.
• Choose the credentials to use for the connection.
• A share link will be created automatically (you can leave it as is).
• Click on Ok, to start the transfer. A scenario will be created in both the source and destination labs to monitor progress.

How to check the scenario queue ?

To check the list of running scenarios and scenarios 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 scenarios and scenarios in the queue.

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

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