Table of Contents

guest
2021-06-17
   Tutorial: Learn Sample Manager
     Tutorial: Add Samples
     Tutorial: Define Assays
     Tutorial: Add Users and Assign Roles
     Tutorial: Outline Workflow
     Tutorial: Track Sample Sources

Tutorial: Learn Sample Manager


This tutorial will help you get started with a new, empty Sample Manager project.

Learn the tasks of an administrator by adding a few "Tutorial" samples, defining an assay, and creating simple workflow jobs. You can even define sources for your samples and see how lineage and timeline features will help you manage your data.

These topics will give you a quick introduction to the tools and process before you load your real data.

Topics

After completing the tutorial topics, you will have an understanding of how to use Sample Manager for your own data and workflows.



Tutorial: Add Samples


Sample Types help you organize samples in your lab and allow you to add fields that help you describe attributes of those samples for easy tracking of data. Each individual Sample has a unique ID and is a member of one Sample Type. This topic assumes you are starting from an "empty" application and walks you through creating a "Tutorial Samples" type and populating it with a set of samples to use in the next steps.

Create a New Sample Type

Create the first Sample Type in the system by clicking the linked word here in the empty Dashboard Insights panel or by selecting Create a sample type from the main menu under Sample Types.

Once one or more Sample Types have been created on your server, you will click the Sample Types heading from the main menu, then select Create > Sample Type.

Define Sample Type Properties

  • Enter the Name: "Tutorial Samples"
  • Replace the default contents of the Naming Pattern box with the following, so that samples of this type will be clearly identified as part of this tutorial:
    Tutorial-${genId:number('000')}
  • Click Add Parent Alias to tell the system the name of the column where we will include information about parent samples with our data.
    • Enter "ParentSample" as one word to match our spreadsheet.
    • Select "(Current Sample Type)"
  • If you also see a button for Add Source Alias you can ignore it for now.
  • Click the Label Color selector to choose a color to associate with samples of this type. Our images show orange, but you can select any color you like by clicking, entering a hex value, or individual RGB values.
  • Display stored amount in: Select "mL (milliliters)". Notice that a variety of built-in solid and liquid unit measurements are available, as well as "unit" for cases where each sample is tracked independent of volume.
  • Barcodes: Learn more about barcodes in this topic: Generate Barcodes

Define Sample Fields

  • In the field editor:
    • For this tutorial, disregard the blue banner about adding a Unique ID field for barcodes.
    • Enter the name "Project" and leave the default type "Text" selected.
    • Click Add Field to add another row, enter then name "Concentration" and select "Decimal (floating point)" as the data type.
  • Click Finish Creating Sample Type.

You will now see the details page for this new Sample Type and are ready to create your first samples in the system.

Import Samples from File

Once you have defined the Sample Type for your samples, you can import them by typing directly into a grid, bulk entering values, or by importing a spreadsheet of sample information, as used in this tutorial.

  • Download this spreadsheet to use:
  • The "Tutorial Samples" Sample Type is now available on the main menu. Click to open it.
  • Select Create > Tutorial Samples.
  • Click Import Samples from File.
  • Confirm that "Tutorial Samples" is selected as the Sample Type.
  • Drag and drop the "TutorialSamples.xlsx" file into the target area.
  • You will see a preview of the data file as it will populate rows in the type. A unique "Sample ID" will be generated for each line based on the naming pattern we provided.
  • Click Import.
  • When complete, you will see the samples listed.
    • The generated Sample IDs for each row may vary if other samples have already been created on your system.
    • Notice that there are a number of additional built-in columns created for you, including but not shown below, the creation date and user.

Other Ways to Import and Create Samples

You can also add samples in a grid or using bulk insert methods. Learn more in this topic:

View Sample Details

You can view details about your samples by clicking the Sample ID. For example, scroll down and click Tutorial-018.

On the details page, you have 5 tabs with information:

  • Overview: basic details including the values of all sample properties and fields as well as the storage location (if any).
  • Lineage: parentage and source information (Tutorial-018 has both parent and child sample linkages provided in our example file)
  • Assays: all data about this sample
  • Jobs: all jobs that involve this sample
  • Timeline: a history of events for this sample (so far only registration has occurred)
Browse the information on these tabs before continuing to the next tutorial step.

Related Topics

Start Over | Next Step (2 of 5)




Tutorial: Define Assays


Assay Designs describe the structure of assay data you will gather for your samples. Similar to sample types, you define the properties and fields of your experiment data. Assay data will also be mapped to the sample that it is about. In this topic, we define a "Tutorial Assay" and import an example run of data for the "Tutorial Samples" we created in the previous step.

Create Assay Design

  • From the main menu, select Assays > Create an assay design.
    • If any assay designs have already been created, you will not see this link. In that case, click Assays and then select Create > Assay Design.

Define Assay Properties

Assay properties are elements that apply to all runs that use this assay design, i.e. one value is set for all runs.

  • Enter:
    • Name: Tutorial Assay
    • Description: Complete blood count
    • Check both boxes for Editable Runs and Editable Results to give you the most options to explore with this tutorial assay design.

Add Run Fields

Assay run fields are set once for each run that uses this assay design, i.e. one value is set for each run.

  • Click the Run Fields section to open it.
  • Click Manually Define Fields.
  • Click Add Field to add each of the fields shown below and select the Data Type shown:
    • "Date" of type "Date Time"
    • "Instrument" of type "Text"

Add Results Fields

You could also manually add results fields, which will be different for each row of data within a given run, but in this tutorial, we will infer them from an example spreadsheet.

In the assay designer:
  • Click the Results Fields section to open it.
  • Drag and drop the "TutorialAssay_Run1.xlsx" into the target area.
  • The results fields will be inferred from your upload and shown in the panel.
    • Notice that the SampleID field from the example spreadsheet has been inferred to be of type "Sample" automatically. All assay results must map to samples, so if the system could not infer which field contained that mapping, you would have had to assign it yourself.
    • You can make adjustments if needed to the types and names, but for this tutorial accept the defaults.
  • Click Finish Creating Assay Design.

Now that your assay design has been created, you can use it to import the data from the same example spreadsheet.

Import Assay Data

The "TutorialAssay_Run1.xlsx" spreadsheet you already downloaded contains some "Tutorial Assay" data for some of the samples we created in the previous tutorial step.

You can confirm that the expected set of samples already exists by selecting Menu > Tutorial Samples and seeing that "Tutorial-003 through Tutorial-012" already exist. (Hint: Sort by Sample ID or use the to see the second page of samples.)

  • If you navigated away to check samples, reopen your Assay Design page by selecting Tutorial Assay from the main menu.
  • Click Import Data.
  • Enter Run Details:
    • Assay Id: Enter "Run1". If you leave this blank, a run name will be generated for you based on the assay design name and current day and time.
    • Comments are optional.
    • Date: Enter "2019-10-01" or click the field to use the day/time date picker.
    • Instrument: Enter "INS-01"

Upload Results from File

  • In the Results panel, the Upload Files tab is selected by default.
  • Drag and drop the "TutorialAssay_Run1.xlsx" file into the target area.
  • You will see the first three rows of the data file in the preview section.
  • Click Import.

You will see the grid of results. This grid allows you to filter, search, and sort the result data.

Other Ways to Enter Results

The other tabs in the Import Data interface allow you to copy and paste data from a spreadsheet or enter values directly in a grid, individually or in bulk. Learn more in this topic:

Related Topics

Previous Step | Next Step (3 of 5)




Tutorial: Add Users and Assign Roles


Now that we have created some Samples and learned how to describe and import assay data, it's time to add some other users so we can understand how the workflow management tools work in Sample Manager. To do this, we will add a few fake users and assign them different roles. You must have administrator permissions yourself to complete the tasks in this step.

Add Users

  • To add one or more new users, select Administration from the user menu.
  • You'll start on the User Management page, i.e. the Users tab.
  • Click Create.

In the popup:
  • Enter one or more email addresses, each on it's own line for each user you want to create.
    • For this tutorial, create users for
      team_lead@local.test
      lab_technician@local.test
      reviewer@local.test
  • Select the desired Role for the users you are creating. For the tutorial, select Reader for now.
  • Uncheck the box to Send notification emails to all new users since these are not real email addresses.
  • Click Create Users.
You will see the new users added to the grid. In the green banner message, you can click view to filter the grid to only the newly added users.

Assign Roles

Once users have been defined, an administrator can assign them one of the three available permission levels:

  • Readers: Have a read-only view of the application.
  • Editors: Have the Readers' access, and can also add new information or edit data related to samples, assays, and jobs.
  • Administrators: Have full control over the application. This includes user management, permission assignments, and creating and editing sample types, assays, and job templates.
  • Reopen user management if you closed it by selecting Administration from the user menu. Click the Permissions section.
  • All our fake users are currently in the Reader role.
  • Click the for the Editors role to open it.
  • Click the Add member dropdown and select "team_lead".
    • Selected users will be shown in the panel for the role as you go.
  • Click Add member again and select "lab_technician".
    • Each time you select a user, the details for that user will be shown on the right.
    • In the image below, the Editor role is being granted to the team lead and lab technician; all three fake users we added are still also members of the Reader role.

Click Save.

View Audit History

This is a good time to mention that all actions in Sample Manager are logged for later use in an audit. The audit logs can be viewed from any tab within the Administration dashboard, and from many other places in the application. Select > View Audit History. The log opens to the section most relevant to where you were when you opened it.

Learn more in this topic: Audit History

Related Topics

Previous Step | Next Step (4 of 5)




Tutorial: Outline Workflow


In this step of the tutorial, you will create a simple job and template, helping you understand how to use jobs, tasks, and templates to represent an efficient sample management workflow. Jobs can include a set of samples, direct links to the necessary assays, and notification mechanisms to ensure the right people know about actions that impact their work.

Create a Job with Selected Samples

  • Select "Tutorial Samples" from the Sample Types section of the main menu.
  • Check the boxes to select "Tutorial-018", "Tutorial-019" and "Tutorial-020".
    • We're including some assay data for these specific samples below.
  • Select Jobs > Start a Job with Selected Samples from the menu above the grid.

Job Details and Priority

On the first panel of the job creation wizard, enter details about the job:

  • Job Name: "Tutorial Workflow Job"
  • Description: "This is an example job with three tasks"
  • Job owner: Select "team lead" for this tutorial. This is the user who "owns" the overall job completion, not necessarily owns the tasks. Note that if you did not create the fake "team lead" user and assign them the role of "Editor" in the previous step, you won't be able to select them here and can just select yourself.
  • Notify these users: Add users who should get notifications as this job progresses. Select yourself here.
  • Job start and due dates: Use the date picker to select any begin and end dates you like.
  • Priority level: Use the pulldown menu to select "Medium".

Define Job Tasks

Click the Define Job Tasks section to open it.

Any job can be composed of several tasks to complete in sequence. For each task in your job, enter the name in the Task column, select any Assays to Perform as part of that task, and use the dropdown to select an Assignee.

For this tutorial enter the following, using Add Task to add rows for the second two tasks:

TaskAssays to PerformAssign task to
Prepare Samples Yourself
Run Tutorial AssayTutorial Assaylab technician
Review Results team lead

Assign Samples

Click the Assign Samples section to open it. You will see the samples you selected listed on the Included Samples tab.

Attach Files (Optional)

Click the Attach Files section to open the final wizard panel. You could drag and drop to upload any files needed for the job. For example, an SOP document or other instructions related to the job could be included here. You can skip this for the tutorial.

Finish Creating Job and Template

Before finishing job creation, consider whether you want to make this job available as a template for creating similar future jobs. Creating a template from a job is offered only during initial job creation.

  • Use the dropdown menu option Save as Template and Start Job to create a template and start this job.

In the popup, you will name the template and provide an optional description. For this tutorial, name the template "Tutorial Job Template 1."

  • Click Save Template.
You will see the job overview. Note the tabs along the top edge for viewing Tasks, Samples, Assays, and Files in addition to the Overview.

Complete Job Tasks

Click the Sample Manager logo to return to the home page of the application. You will now see that the Jobs section has begun to grow. Your Queue includes the job you just created (because the first task is assigned to you).

Click the name of the job to open it. On the Overview page, you'll see summary information, including the list of tasks. The current task is assigned to you.

  • Click Complete Current Task to mark it as complete.
In the Status column, you'll now see that the second task, "Run Tutorial Assay" is now "In Progress".

The assay task is assigned to the "lab technician" but as an administrator you have the ability to complete any task in the system. Let's use that power here to illustrate assay data import from within the workflow system.

  • Click the Tasks tab to see more detail about the task. In this view, you have an Import Data button since the task involves importing data to the "Tutorial Assay".
  • Click Import Data.
  • Enter:
    • Assay Id: "Run2"
    • Date: Today's date (click the entry field to use the date picker)
    • Instrument: INS-01
  • Download this example data sheet: TutorialAssay_Run2.xlsx, then drop it into the upload window.
  • You'll see the data preview.
  • Click Import.
  • When complete, you'll see the imported data.

  • To return to the job details page, you can click here in the green "Successfully created assay run" banner. For this tutorial, navigate as follows to see how task assignment changes your task queue.
    • Click the Sample Manager logo to return to the home page.
    • In the Jobs section, notice that the job is no longer shown in Your Queue because the current task is not assigned to you. To find the job, click Active Jobs.
    • Click the name Tutorial Workflow Job.
  • Click the Assays tab to see the data you just uploaded.
  • Click the Tasks tab to return to task details.
  • You can now click Complete This Task to mark the lab technician's task complete.

View Timeline

Each sample has a record of all activities that happen for it within the system. To see a timeline, select Sample Types > Tutorial Samples from the main menu and locate "Tutorial-020". Click the name to open details about that sample.

Click the Timeline tab to see the event timeline for this sample.

  • You'll see when it was created (registered), when it was added to the job, and when assay data was uploaded for it.
  • You're also shown the current status of the sample on the right, including who last handled it.
  • If you click an event, such as "Assay Data Loaded" you'll see an additional panel on the right which includes details including a link to the run of data you uploaded.

Related Topics

Previous Step | Next Step (5 of 5)




Tutorial: Track Sample Sources


Sources help you track where your samples came from and trace common attributes across sets of samples from the same source. Sources can be:
  • Physical like labs, vendors, locations, studies, etc.
  • Biological like patients, mice, trees, cell lines, etc.
In this tutorial step, we create and populate two kinds of sources, "TutorialLabs" and "Creatures", then associate the tutorial samples we created earlier with some of each. After doing that, we will examine the kinds of detailed information that are available for samples including timeline and lineage.

Create a Source Type

Creating source types is very similar to the creation of sample types covered in the first step of this tutorial.

  • From the main menu, look under Source Types and click Create a source type.
    • Once source types have been created, click Source Types, then select Create > Source Type.
  • Enter:
    • Name: Tutorial Labs
    • Delete the default Naming Pattern that is provided (and ignore the placeholder text). We will provide unique source names when we create them.
  • Click the Fields section to open it.
  • Download this spreadsheet and drop it in the upload area: TutorialLabSources.xlsx
  • You will see the inferred fields.
  • Notice the blue banner informing you that reserved fields were found and are not shown. This refers to the "SourceId" field that is present in the data file and cannot be "defined again."
  • Click Finish Creating Source Type.

You can now select your new source from the Source Types section of the main menu.

Create Sources (Populate a Source Type)

  • Select your Tutorial Labs Source Type from the main menu, if you navigated away.
  • Select Create > Tutorial Labs.
  • Click Import Sources from File.
  • Drag and drop the same "TutorialLabSources.xlsx" spreadsheet into the target area.
  • You'll see a preview of the first three lines.
  • Click Import to import the file and create these sources.

Create and Populate a Second Source Type

Follow the two sections above to create another source type to use for our tutorial samples, in this case a biological one.

  • From the page for the "Tutorial Labs" you just imported, select Create > Source Type.
  • Name this type "Creatures".
  • Delete the Naming Pattern.
  • Download and use this file for inferring the Fields: TutorialCreatures.xlsx
  • Click Finish Creating Source Type.
  • Select Create > Creatures.
  • Click Import Sources From File.
  • Drag and drop the same "TutorialCreatures.xlsx" spreadsheet into the target area.
  • Click Import.

Now you have two Source Types and we can mark the Samples as having come from one or both types of source.

Associate Samples with Sources

When we originally created the "Tutorial Samples" type, we had not defined these sources, and did not include a way to reference them in the Sample Type definition.

We can now use these new sources when using the Create Samples from Grid entry method for new samples, or by directly editing each individual Sample. Learn more in this topic: Associate Samples with Sources.

For this tutorial, we want to add Source information to our existing Samples. To do so, we must modify the Sample Type design to identify the columns where we will import source information, i.e. the source aliases.

  • From the main menu, select the Tutorial Samples Sample Type.
  • Select > Edit Sample Type Design.
  • Click Add Source Alias.
  • Enter the Source Alias "Lab", and select the Tutorial Labs Source Type.
  • Click Add Source Alias again.
  • Enter the Source Alias "Creature" and select the Creatures Source Type.
  • Click Finish Updating Sample Type.

We now will update the samples we created earlier.

  • Select Create > Tutorial Samples.
  • Click Import Samples from File.
  • Check the box to Update data for existing samples during this file import.
  • Download this file: TutorialSamplesWithSources.xlsx then drop it into the target area.
  • You'll see a preview:
  • Click Import.

The existing samples have now been updated with source information.

View Lineage

As an example, click the Tutorial-020 sample. Click the Lineage tab. You'll see a graphical representation of the creature and lab sources for this sample, as well as child samples 'derived' from it. Click the icon for either source to see more details about it in the panel to the right.

View Timeline

In the previous step, we saw how assay data import is included in the timeline for a sample, open the Timeline tab for the "Tutorial-020" sample to see that the update we just completed was also recorded for this sample. Clicking the timeline event populates the Event Details panel.

Learn more about the timeline here: Sample Timeline

Congratulations!

Now that you have learned to use Sample Manager with our tutorial content, you are ready to start loading your own data into the system. Learn more in the documentation for each area:

Previous Step