1. User Guide

Welcome to the precision toxicology metadata manager user guide. In this documentation, we will show you how to generate a spreadsheet for your sample exposition and collection, how to validate your metadata and how to send them to the University of Birmingham.

1.1. Create an account

Head to https://ptmm.netlify.app/login and click on “Need a new account? Create one here” link. Fill in the form with a username, an email address, a password and the organisation you belong to.

Figure 1: Login page (left) and create account page (right)

You will receive an email with further instructions. Click the link to confirm your account and you will be able to login. Wait for an admin to validate your account and you will be able to use the application.

1.2. Generate your sample collection spreadsheet

The metadata stored by the tool are essential for downstream analysis and deposition to public repositories. The tool starts by generating information about the sample collection based on a predetermined study design.

After login in, head to https://ptmm.netlify.app/files/create. The form contains 3 pages that will ask you to provide information about general aspects of your study, timepoints and chemical exposure.

Figure 2: Creating a new sample collection spreadsheet - General information

The first page of the creator will ask general information about your sample collection:

1. The consortium partner for which the spreadsheet should be generated. By default, it is the organisation you belong to.

2. The organism you are working on. You can choose between Danio Rerio, Homo Sapiens (HepG2 cells), Xenopus Laevis, Caenorhabditis Elegans, Daphnia Magna and Drosophila Melanogaster (Male or Female).

3. The expected start date and end date of the sample collection step: default to today.

4. The exposure batch, in the format of a double capital letter: default to AA.

5. The solvent, either water or DMSO: default to water.

6. The number of empty tube in this batch: minimum 1, maximum 3, default 3.

7. The number of exposed and controlled replicates per time points: minimum 2, no maximum, default 4.

Figure 3: Creating a new sample collection spreadsheet - Timepoints

After clicking “Next”, you will access the timepoints page where you are asked to provide:

1. the number of collection timepoints after exposure: minimum 1, maximum 10, default 3.

2. the timepoints units: in the case of precision toxicology, it will always be hours.

3. the values of your timespoints: minimum 1, no maximum, default 0, 0, 0. Be careful because the values cannot exceed the end date of the expected timeframe.

Figure 4: Creating a new sample collection spreadsheet - Exposure Information

The last page of the creator will contain information of the chemicals used for the exposure. They are organised in different groups, including: BMD10 (Low), BMD25 (Medium), 10mg/L (High), or Alternative (Alternative). Each chemical can only be added to one group at a time and you will need to create a new batch to test a chemical at a different dose for the same species. At least one group must contain a chemical for the spreadsheet to be generated but you can add as many chemicals as you want in each group.

Figure 5: The sample collection spreadsheet

Finally click the submit button at the bottom right of the screen to generate the spreadsheet and add the information to the database. If you filled everything correctly, the excel document will open on google sheets in a new tab. The document contains two sheets:

1. The first sheet holds information about the samples. It contains:

   • Grey fields (pre-filled by the tool): you should not modify them. They are locked in excel but google sheets only supports this feature for google sheets documents.

   • White fields: these are they fields you want to fill after or during exposition and collection.

2. The second sheet contains general information that you should not modify.

1.3. Search and preview files

After creating your first excel file, you can navigate to https://ptmm.netlify.app/users/files to see all the spreadsheets that you have created or that belong to your organisation.

Figure 6: The search files page

1.3.1. Search files

The left side of the page contains a block with filters that you can use to search for a specific file. You can search using the following filters:

1. Validated: this is the status of the files. It indicates if they passed (success), failed (failed) or are still pending validation (No).

2. Organism: the organism for which the files were generated.

3. Chemical: the chemical used for the exposure.

4. Batch: the exposure batch.

5. Start and end date: filter all files where the expected start and end date are between the two given dates.

1.3.2. Preview files

Apart from the information you provided during the file creation, each file box also contains the following information:

1. Filename: it is generated automatically with the following format: <organisation>_<species>_<batch>.xlsx.

2. Validated: the current validation status of the file. Green for success, red for failure and yellow for pending validation.

3. Author: the user who created the file.

4. Shipped: No if the file has not been shipped yet. If it has been shipped, it will contain the date of shipment.

5. Received: No if the file has not been received yet. If it has been received, it will contain the date of reception. Doesn’t show if the file has not been shipped yet.

Overing the mouse over a file box will display a list of actions that you can perform on the file. Depending on the file state, different actions will be available.

Figure 7: Opening the actions menu when overing the mouse over a file box

If a file has not been validated yet (or if it failed validation), you will be able to:

1. View and edit the excel file on google sheets.

2. Validate the file. This will run a series of checks on the file and will change the validation status to success or failure.

3. Delete the file. This will remove the file from the database and from the google drive folder.

1.4. Validation file content

Keep editing your file until you are happy with it and then click the validate button. This will run a series of checks divided into three categories:

1. Syntactic checks: this step is automatic and is realised using JSON Schema. It checks that the file contains all the required fields and that the values are of the correct type. Details about the checks can be found here: https://raw.githubusercontent.com/precisiontox/ptox-metadata-manager/main/ptmd/resources/schemas/exposure_information_sheet_schema.json

2. Identifiers checks: this step will ensure that the identifiers generated by the tool were not tempered with. This step is realised by comparing the identifiers in the file with the identifiers stored in the database.

3. Study design checks: this step will verify that the study design consistency was not tempered with. It will check if the number of samples, the timepoints, the chemicals and the exposure information are correct.

If the validation fails, a report will be generated with a line by line detail of every error, and the validation status will turn to “failed” and its colour to red.

Figure 8: First line of the validation report for a failed empty file

The validation report is divided in two sections:

1. Summary: this section contains a link to the file on google sheets, the total number of errors and the number of lines containing errors.

2. Report details: a line by line report of the errors. Each subsection contains the concerned sample identifier and line number as well as the fields having errors and the corresponding error message.

Once a file has been validated, its status will turn to “success” and its colour to green. On overing the mouse over the file box, a new action will appear to ship the file and the sample box to the University of Birmingham.

Figure 8: Popup to select the shipping date and ship the file

Clicking the link will open a popup with a widget to selection the shipping date. Once the date is selected, click the “Ship” button to ship the file. This will lock the file from any further modification and its card will display the shipping date and the “Received” status.

Note

The shipping date cannot be earlier than the end date of the expected timeframe.

1.5. Accessing samples by identifier

Once the administrators at Birmingham receive the samples, they will mark the file has received through the admin interface. This will extract the samples metadata from the spreadsheet, store them in the database and make them available through the Rest API. Login in the ReST API will provide an JSON Web Token (jwt) that you can use to authenticate yourself. Once logged in, you will be able to access these samples by identifiers using the following endpoint:

https://pretox.isa-tools.org/api/samples/<identifier>