Skip to content

Detailed instructions

Setting up a study happens in four phases. Work through them in order.

Phase What you do
Phase 0 Prepare your study
Phase 1 Create the template
Phase 2 Enter the metadata
Phase 3 Update permissions and complete the metadata

Phase 0: Prepare

  1. Understand the basic structure of the metadata model.

  2. Decide what to group together. Decide on what experiments to group into (the investigation and) the study.

  3. Choose the study type: sequencing, phenotyping or combined.

    Info

    Inform DataXR well up front when your study does not fit these types.

  4. Make sure you have an active account. FairdomSEEK is the data catalogue. Log in with the following steps:

    1. Select Login in the top right corner.
    2. Under the tab KeyCloak, click đź”’ Sign in with KeyCloak.
    3. Click SURFconext to use your university account.
    4. For the first login, give the needed permissions.

  5. Request to be added to a project if you have not been added already. This is done by a project admin.

  6. Gather the files with the metadata that you already collected. This includes:

    • e-lab journal entries
    • files that outline experimental conditions per plant
    • files that link output files to the experiment
    • etc.

No separate registration step

There is no separate registration form. All metadata goes into the data catalogue, and that is where you register your investigation and study.

FairdomSEEK can be slow, do not click again while loading

Be aware, if you click twice on "create" while it is loading, it can create the same resource multiple times.

Phase 1: Create the template

Always select the highest ID

This phase asks you to choose a template four times: for the study source, for the study sample or observation unit, and for each assay. Every one of those lists shows every version of the template that has been released, all under the same name. Nothing in the name tells the versions apart. The ID does: the highest ID is the most recent version.

Whenever the selection tool offers more than one entry with the same name, select the one with the highest ID. A lower one gives your study an outdated set of fields, and the template of a sample type cannot be changed once samples have been created from it.

Step 1: Log in

Log in to the Catalogue webpage.

Step 2: Find or create an investigation

Click 🔎 Browse in the top left corner and select Investigations.

(Click the menu first when using a narrow window.)

If your investigation does not exist in the catalogue yet:

  1. Click âž• Create and select Investigations.
  2. Add a Title and select a Project.
  3. Click Create.

Step 3: Create a study

From within the investigation, create a new study by clicking âž• Design Study at the top.

  1. Title: create a title using the naming convention.

  2. Extended metadata: choose the extended metadata type that is relevant for your study.

    Only fill the mandatory fields for now (to be able to save). The other fields can still be entered later.

  3. Skip for now: “Study position”, “Sharing”, “Creators”, “Publications” and “Discussion Channels”. These fields can be reviewed and modified later.

  4. Define Sample type for Source:

    1. Select an Existing template.
    2. Choose the default template CropXR source — where the list holds several entries under that name, take the one with the highest ID.
    3. Click Apply.
    4. Review the predefined parameters that are collected for the study source. These are the fields that will be used to describe your experimental setup and conditions.
    5. If there are any missing, you can add them at the bottom by selecting âž• Add new attribute. Make sure that the column ISA Tag is set to source_characteristic. Additional fields can also be added later.

    seek-adding-sample-type-field.png

    Use MIAPPE field names

    In MIAPPE there are many suggestions for environmental parameters and experimental factors to collect. Please reference these lists, to get a predictable field name.

    Do not remove fields

    Please do not remove any fields; this will make your study harder to find. All fields not relevant to your study can be left empty.

  5. SOPs: skip for now, these will be added later.

  6. Define Sample type for Sample:

    1. Select an Existing template.

    2. Under Choose a template, pick from the drop-down. Templates are named and grouped by stream, so pick the set matching your study. Select, depending on the units of measurement:

      Your study has… Template
      samples only CropXR sequencing sample
      both samples as well as measurements on a different level CropXR combined sample
      no samples CropXR phenotyping study

    3. Take the entry with the highest ID, this is the latest version of that template, and click Apply.

    4. Check the fields and add additional fields when needed (now or later).

  7. Click 🟦 Create.

Step 4: Plan your assay streams

Decide which assay streams the study needs: one for each type of assay performed. (read here)

Step 5: Create an assay stream

  1. Click âž• Design Assay Stream at the top of the study.
  2. Enter a title (following the naming convention).
  3. If needed, select the Extended metadata for the assay stream.
  4. Skip all other fields for now and click 🟦 Create.

Create the backbone of the assay stream before entering any metadata. The backbone is the same for every assay stream: a first assay of the ISA level “assay - material” (step 6), followed by a second assay of the ISA level “assay - data file” (step 7).

The assays must be in the order “assay - material”, then “assay - data file”

The Input column of an assay links to the table before it in the stream: the material assay takes the study samples as input, and the data file assay takes the rows of the material assay. The position of an assay cannot be changed afterwards; an assay created in the wrong position has to be deleted and created again.

The templates per ISA level:

ISA level Templates
assay - material CropXR sequencing assay, CropXR phenotyping assay, CropXR metabolomics assay
assay - data file CropXR sequencing data file, CropXR phenotyping data file, CropXR metabolomics data file

Step 6: Create the material assay

From the created Assay Stream, create the first assay by clicking âž• Design Assay.

  1. Enter a title (following the naming convention).
  2. Skip for now: “Sharing”, “Creators”, “SOPs”, “Publications”, “Documents” and “Channel discussions”.
  3. Define Sample type for Assay:
    1. Start at Existing Templates.
    2. Leave the ISA Level drop-down at “assay - material”.
    3. Choose the assay template of your stream, taking the entry with the highest ID, and click Apply.
  4. Extra columns (optional): the sample type can be expanded with additional columns that should be included as metadata. This is relevant for assays where most parameters are kept constant, but some are varied between measurements/samples. Set the ISA Tag column to parameter_value.
  5. Click 🟦 Create once. If duplicate assays were created, delete the extra ones before continuing.

Step 7: Create the data file assay

  1. Open the assay created in step 6 and click Insert a new Assay there. Do not click âž• Design Assay on the assay stream a second time: that places the new assay before the existing one, and SEEK relinks the inputs of both assays to match that order.
  2. Enter a title and skip the same fields as in step 6.
  3. Define Sample type for Assay: change the ISA Level drop-down to “assay - data file”, choose the data file template of your stream, taking the entry with the highest ID, and click Apply.
  4. Extra columns (optional): columns that describe the output file take the ISA Tag data_file_comment.
  5. Click 🟦 Create once.

Step 8: Derived data assay (if needed)

A study with derived data gets one further assay of the ISA level “assay - data file” per processing step, inserted from the last assay of the stream in the same way as step 7.

Phase 1 done

Now you have the outline of your metadata structure. The actual metadata can be uploaded.

Phase 2: Enter the metadata

Enter the metadata first; adding the data is the second step. Not all steps need to happen in this exact order, but some steps are dependent on each other:

flowchart LR
    A["Study sources"] --> B["Study samples"] --> C["Assay row entries"]

One table at a time

Work through those tables one at a time, downloading each only after the previous one has been uploaded. SEEK identifies rows by the id the catalogue generates, not by name, so the Input column that links a table to the one before it cannot be filled until those rows exist. Downloading every workbook up front leaves you with Input columns you have no ids for.

Step 1: Add SOPs (can also be done later)

SOP stands for standard operating procedure. Each step can refer to the protocol that was used: at study level, how samples were created and observation units grouped; at assay level, the assay protocols and the data processing steps.

  1. At the top menu under âž• Create choose SOP.
  2. Click Browse to upload a local file.
  3. Add a Title. This needs to be specific enough to find the SOP back between other SOPs from different studies.
  4. Add a Description, select a Project and a License.
  5. Skip “Discussion Channels”, adapt “Sharing”, skip “Creators”, “Tags” and “Attributions”.
  6. If the SOP is related to an assay, it can be linked under Experimental assays and Modelling analyses. This can also be done at the assay.
  7. If a data processing step is described by a registered workflow/processing pipeline, it can be linked under Workflows.
  8. Click 🟦 Register.

Step 2: Edit the study

Go to ⚙️ Actions in the top corner and then 📝 Edit ISA Study.

  1. Fill in the description.
  2. Fill in extended metadata. Focus on the fields most relevant to understand the study. Skip the fields that do not apply. The fields can always be revised later.
  3. Under SOPs select the SOP(s) that describe the sampling and the experimental design map.
  4. Click 🟦 Update to apply the changes.

Step 3: Define study source samples

  1. Choose how to group/define the sources.

  2. Go to the Sources table by clicking the tab Study design. Study design tab

    You should now see a table with the columns you defined:

    The samples table

  3. Download the template by clicking Batch download to Excel.

  4. In the Excel, under the Samples tab, fill in the data:

    • Ignore the first two columns.
    • The Source Name is the name that will be displayed.
    • Start with the most relevant fields to understand the study and the sources used. The data can be improved on at a later point. Fill in at least the species and the experimental group.

    Uploading twice creates duplicates

    If you upload the same Excel file more than once, a new sample with the same name is created each time. To update existing samples, see the phase 3 instructions.

  5. Save the file. Upload it under Upload excel spreadsheet: select Browse and click 🟦 Upload.

    Now there might be an error message. Please read it carefully and adjust the data accordingly.

Step 4: Define study samples

  1. Choose which types are needed.
  2. Go to Samples table under Study design.
  3. Download the template by clicking Batch download to Excel.
  4. In the Excel, under the Samples tab, fill in the data in the fields:
    • Ignore the first two columns.
    • Use the Input column to link each sample to its source. The ids you need come from the Sources table you just uploaded. Follow how to fill the Input column.
    • The subject_id is the name that will be displayed.
    • There is a mandatory column called protocol. The text should refer to a registered SOP.
    • Start with the most relevant fields. The data can be improved on at a later point.

  5. Save the file. Upload it under Upload excel spreadsheet: select Browse and click 🟦 Upload.

    Now there might be an error message. Please read it carefully and adjust the data accordingly.

Step 5: Fill in the assay stream metadata

Go to ⚙️ Actions in the top corner and then 📝 Edit Assay Stream. Focus on the fields that are most important and click 🟦 Update to save.

Step 6: Enter the assay rows

For each assay defined in phase 1, enter the row data the same way as the study source and sample: download the template, fill in the data, save and upload the template.

Input column. Each assay row says what it was made from:

  • First assay of an assay stream: the input is a study sample (so this is a sample or observation unit). The ids come from the Samples table.
  • Later assays: the input is a row from the previous assay. The ids come from that assay's table.

For example, if the first assay is an RNA extraction and the second is sequencing, each sequencing row points to the RNA extract it used:

flowchart LR
    S["Study sample"] -->|input of| A1["Assay 1: RNA extraction"]
    A1 -->|output = input of| A2["Assay 2: sequencing"]

So enter the assays in order, and upload each one before you start the next. To fill the Input column in the excel sheets, follow How to fill the Input column.

Leave the file location empty for now

That column takes a reference to a data file already registered in SEEK — not a path or a URL — so the file has to exist as a record before the cell can be filled.

Metadata done

The metadata now stands on its own. The data can be added now.

Phase 3: Refine and share

Step 1: Update sharing permissions

Update the sharing permissions that each of the created elements have. Think about who should see your study. If you are collaborating with others you can give them edit permission.

  1. Navigate to the Study/Assay/DataFile/SOP.
  2. Click ⚙️ Actions in the top corner and then 🔧 Manage ..
  3. After making the changes, make sure to click 🟦 Update.

Note

In the future the permission you set in SEEK on the data file will be automatically set where the data is stored, but for now the permission is still set separately within the Research Drive.

Step 2: Complete the metadata

Update the study and assay extended metadata to make the metadata more complete (under ⚙️ Actions in the top corner and then 📝 Edit ..).

Step 3: Updating existing samples

[todo: expand]

  • Select the samples before you download the table, so that no new samples with the same name are created.
  • You can upload samples in several rounds, but re-uploading a sample with the same name creates a new sample. Only upload new samples.

Step 4: Adding additional columns

[todo: expand] (under ⚙️ Actions in the top corner and then 📝 Edit ..)