A Sample represents an underlying next-generation sequencing (NGS) data file, either in the form of a de-multiplexed FASTQ or a FASTA file. Often, there will be a single sample for each physical specimen, though in some cases there may be multiple Samples for each individual specimen (e.g., in the case of replicates).

Samples should be in FASTA or FASTQ format, optionally gzipped, and may be up to 20GB in size. Uploading samples requires 2 direct API calls, one to start the upload and a second to actually POST the FASTA or FASTQ files. If you need to upload a compressed file over 20GB in size, please contact us for help at [email protected].

The below table summarizes all of the properties for the Sample resource, with the JSON schema type of each property listed below in italics. Details on how to upload your NGS data, as well as retrieve and modify your Samples follows.

Property

Description

$uri
string

The sample ID encoded as an addressable URI

created_at
date-time

Timestamp for when the sample was created on the One Codex platform, encoded as a RFC 3339 timestamp

filename
string

The sample filename (e.g., "sample.fastq")

size
integer

The size of the uploaded file in bytes.

visibility
string

Samples may be public , shared , or private (no icon or if owner by another user and shared via a private project). The visibility of a sample controls access to a sample resource, any analyses (and corresponding jobs) performed on that sample, as well as the sample's metadata, project, and tags. As such, sensitive samples should always be "private" and shared across accounts using private projects.
Note: Samples imported via an external service (e.g., BaseSpace) may also be marked as importing until One Codex's servers have successfully retrieved the file. These samples are always private to the owner of the sample.

owner
string

A reference to the user that uploaded and owns the sample, e.g., {"$ref": "/api/v1/users/5891ee65711c4d5e"}. Only sample owners can modify a sample (with some exceptions in the case of organization accounts configured for multiple users – please contact us if you'd like to discuss this use case).

metadata
string

A reference to a sample's accompanying Metadata, e.g., {"$ref": "/api/v1/metadata/481ad62997e647ba"}

project
string

A reference to the (optional) Project containing a sample. Samples can be part of zero or one projects.

primary_classification
string

A reference to a Classification for the sample. This will typically be the One Codex Database or Targeted Loci Database results as appropriate. Note that samples will not have a primary_classification while they are still importing or being uploaded.

tags
array of strings

An (optionally empty) array of references to Tags describing the sample. Tags are an additional unstructured organizational tool that complement Project and Metadata records.