Samples

Biological and digital materials that flow through your research processes.

What is a sample?

A sample represents any material tracked through the research workflow — biological specimens, extracted nucleic acids, sequencing libraries, or digital data objects. Samples flow between processes as inputs and outputs, forming the provenance chain.

Creating samples

Samples are created as outputs of a process:

1. Navigate to a process page
2. Go to the Samples tab
3. Under Output Samples, click Add Sample
4. Fill in:
   • Name — A unique identifier (e.g., "HaFB_RNA_01")
   • Material type — What the sample is (RNA, DNA, library, tissue, etc.)
   • Characteristics — Key-value metadata (species, tissue, treatment, etc.)
5. Click Create

Sample page

Each sample's page shows:

• Basic info — Name, material type, characteristics
• Source process — The process that created this sample
• Downstream processes — Processes that use this sample as input
• Storage location — Where the sample is physically stored (if recorded)
• Assays — Measurements and QC results linked to this sample
• Analysis runs — Computational analyses that processed this sample
• Ontology annotations — Structured metadata terms
• Provenance view — Visual lineage diagram showing the complete chain

Sample characteristics

Characteristics are key-value pairs that describe sample properties. They are included in ISA exports and can use ontology terms for machine readability.

Common characteristics:

Key	Example value	Ontology
Organism	Helicoverpa armigera	NCBI Taxonomy
Tissue	Fat body	UBERON
Sex	Female	PATO
Developmental stage	5th instar larva	UBERON
Treatment	Control	EFO

Provenance and lineage

The provenance view shows the complete history of a sample — every process it has passed through, from the original source material to the current state. This is visualised as a directed graph.

To view a sample's lineage:

1. Navigate to the sample page
2. The provenance diagram is displayed automatically, showing upstream and downstream connections

Linking samples to processes

To use an existing sample as input to a new process:

1. Navigate to the process page
2. Go to the Samples tab
3. Under Input Samples, click Link Sample
4. Search for the sample by name
5. Select and confirm

This creates the provenance link between the two processes.

Sample access control

Sample visibility follows the access rules of the process and investigation they belong to. Additionally, sample-level access checking ensures that users can only see samples from processes they have permission to view.

For sequencing QC dashboards, sample-run links connect ISA samples to platform-specific run data. Admin users can see all samples; non-admin users see only samples linked to their group's projects.

Submitter attribution — who generated the sample

Each sample can record a submitter — the person who physically generated or collected the sample, distinct from the operator who ran the bench process. This matters when a sample originates outside the operating lab: a collaborator who ships a lysate, a citizen-science contributor who drops off a field collection, or a core-facility customer whose material is processed internally.

The submitter points at the person layer, not the account layer. A submitter does not need a Libre Biotech account — contributors who never sign up can still be credited.

How it appears on the sample page

If a submitter is set, the sample page shows a Submitted by row in the metadata block. If no submitter is recorded, the row displays an em-dash.

How to set a submitter

Today, submitter attribution is set at sample creation time via the REST API or via CSV bulk import (not via the web form — that UI field is planned for a follow-up release). Two equivalent input paths:

• submitter_person_id — direct integer reference to the person's record, if you already know the ID
• submitter_email — the platform resolves the email to the person record. Works only when the email belongs to a Libre Biotech user who shares at least one group with you (prevents the endpoint from being a user-enumeration tool)

For non-account contributors (submitters who have a people record but no login), use submitter_person_id. See the Submitter attribution section of the API reference for exact field semantics and error responses.

Changing a submitter after creation

Modifying submitter_* on an existing sample requires you to be a Leader or Manager in the sample's owning group (or a platform admin). The sample creator alone cannot silently reassign credit.

Photos and file attachments

Samples support direct file attachments — photos of the physical specimen, purchase receipts, informed-consent scans, or any supporting document. Attached files render as a thumbnail grid on the sample detail page (images inline; other types as file-icon cards with filename and size).

Uploading

1. Open the sample's detail page
2. Scroll to the Attachments section
3. Expand the Upload files card
4. Select one or more files (images, PDFs, office documents — up to 10 MB each)
5. Optionally pick a role: Attachment (default), Photo, Receipt, or Document
6. Click Upload

Detaching

Each attachment thumbnail has a Detach link. Detaching removes only the link between the sample and the file — the file itself is preserved because other entities may still reference it. To fully delete the file, use the file-management surface under Files.

Your contribution log ("My Samples")

To see every sample attributed to you as the submitter, use Your Work → My Samples in the top navigation. This is your contribution history — samples you generated or collected appear here regardless of whether you're still a member of their owning group.

Individual samples in the list still enforce read permission: clicking through to a detail page returns 403 if you've since left the group that owns it, but the list itself always shows your history so you can track your own contributions over time.

Bulk sample import

For processes with many output samples, you can import samples in bulk:

1. Prepare a CSV file with columns: process_id, label, optional description, created_at, parents, anno:* columns for annotations, and (new) submitter_person_id or submitter_email to set attribution at creation time
2. Navigate to ?action=sample_import_new
3. Upload the CSV file (or a ZIP bundle containing samples.csv, lineage.csv, annotations.csv, and related files)
4. Review the import report for per-row warnings, then confirm