Import sequencing data and start analysis

Import sequencing data and start analysis#

After a sample is registered in the PENDING state, importing sequencing data and running the analysis pipeline are two distinct steps:

Import the sequencing files into SeqsLab and associate them with the registered biosample.
Run the assay-specific workflow against the imported files.

How you import files depends on file size: small files can go through the Reporter console directly, while large files (for example, whole-genome FASTQ files that can exceed 30 GB per sample) should be uploaded and registered with the SeqsLab CLI and then associated with the sample from the Sample List page. Both paths converge on the same ANALYSIS state before a workflow is run.

Before you start#

Confirm that you have the MedicalTechnologist or BioinformaticsScientist role, depending on the action. MedicalTechnologist uploads and links sequencing data; BioinformaticsScientist runs the analysis pipeline.
The sample must be in the PENDING state, and must already be registered with an assay (see Register a patient and sample). The assay’s interpretation configuration is what later determines which workflows are offered in the Run Analysis dialog.
The required workflow or tool must be registered and available in your workspace, tagged with the same interpretation keyword as the assay. If it is missing, ask your administrator, BioinformaticsScientist, or ToolRegistryWriter.
For large-file imports, a working installation of the SeqsLab CLI. See Pull and run the SeqsLab CLI.

Supported file types#

The exact file formats depend on the assay and workflow. Common inputs include:

File type	Typical use
FASTQ	Raw sequencing reads.
BAM / CRAM	Aligned sequencing reads.
VCF	Variant calls for interpretation.
Phenopacket JSON	Structured patient phenotype information.

Your organization may define additional file-type requirements for specific assays.

Import sequencing files#

Choose one of the two paths below based on file size and where the data currently lives. Either path ends with the biosample carrying one or more drs:// file references and being ready to move into ANALYSIS.

Option A — Small files, directly from the Reporter console#

Use this path when the files are on your local computer or a mapped drive and are small enough to upload through the browser.

In Reporter → Management, open the PENDING lane, select the sample(s), and choose Upload datasets. This opens the Upload Datasets dialog.
Choose the target Workspace at the top of the dialog. This is the Data Hub workspace the files are stored in; files are transferred as DRS objects and referenced from the biosample by their drs:// URI.
For each biosample row, select the files through the file picker. File names must contain only letters, numbers, hyphens, periods, and underscores; uploads with other characters in the name are rejected before transfer starts.

Set File Attributes on each file so downstream tools can identify it correctly:

Attribute	Example values
`bio_sample_type`	DNA, RNA
`bio_clinical_status`	Tumor, Normal, Control
`tech_read_type`	paired, single
`tech_read_direction`	R1, R2
`file_format`	fastq, bam, vcf, tsv, fasta, bed

Pair R1/R2 FASTQ files for the same biosample by uploading them as separate rows with matching tech_read_type: paired and the corresponding tech_read_direction.

Click Upload. Once every file finishes uploading for a biosample, Reporter automatically transitions that biosample from PENDING to ANALYSIS; no separate confirmation step is needed.

Browser uploads are convenient but are not intended for very large files (for example, whole-genome FASTQ files that can exceed 30 GB per sample); use Option B instead for those.

Option B — Large files, via the SeqsLab CLI and Sample List association#

Use this path for large sequencing files, or when files are already staged on a server rather than your local machine. It has three steps:

Upload and register the files with the SeqsLab CLI. From the machine or server holding the FASTQ/BAM files, run seqslab datahub upload to transfer the files to the workspace’s Data Hub storage, then seqslab datahub register-blob file to register each uploaded file as a DRS object. See Upload and register files using the SeqsLab CLI for the full command reference and options (chunked, parallel, resumable transfer for large files). Registering with recognizable tags, aliases, or an id that includes the Sample ID makes the file easier to find in the next step.
Associate the registered files with the sample in Sample List. Go to Reporter → Sample List, select the biosample(s) that need files attached, and click Associate Files in the toolbar. In the dialog, optionally filter by file type, filename keyword, or label, then click Search — Reporter matches already-registered DRS objects to the selected samples by looking for the Sample ID inside the file name. Review the matched rows (Sample ID, File Name, File Attribute, File URI) in the editable grid, correct the File Attribute JSON if needed, and click Apply to attach the matched files to each biosample.
Switch the biosample into ANALYSIS. Unlike Option A, associating files this way does not automatically advance the sample’s state. Select the biosample(s) in Sample List, click Switch State in the toolbar, choose ANALYSIS, and click Apply.

Run the analysis#

Once a biosample is in ANALYSIS with its files attached, open Reporter → Management, select the sample in the ANALYSIS lane, and choose Run analysis to open the Run Analysis dialog.

How the workflow list is filtered#

Every assay is registered (see Register a patient and sample and the Add Assay dialog in Lab Test setup) with an interpretation configuration value, such as hereditary-genome or onco-exome, alongside a separate reporting configuration used later for report rendering. Tools in the Tool Registry are searchable by that same keyword, so the Run Analysis dialog automatically searches the registry using the biosample’s assay interpretation keyword and shows only the matching, assay-appropriate tools rather than the full catalog. If the tool you expect is missing from the list, confirm with your BioinformaticsScientist or ToolRegistryWriter that the tool has been registered with a name or tag matching the assay’s interpretation keyword.

Each candidate tool shows:

Verified — the tool has a registered checker workflow.
Signed — the selected tool version is cryptographically signed.

Select a version and submit; Reporter names the run {assay}-{sampleId}-{timestamp} automatically so you can match it back to the sample later.

Monitor the analysis#

While the sample is in ANALYSIS, click the sample card to inspect its run status dialog. The dialog header shows a status badge colored by state:

Status badge	Meaning
Blue (QUEUED, INITIALIZING, RUNNING, PAUSED, UNKNOWN)	The run is in progress or waiting on resources. This is normal; refresh later.
Green (COMPLETE)	The run finished successfully and the sample is ready to advance to REVIEW.
Red (EXECUTOR_ERROR, SYSTEM_ERROR, CANCELED)	The run failed or was stopped. See below for likely causes.

Below the badge, Workflow Execution Steps lists each pipeline step with a check icon (exit code 0), a red X (nonzero exit code), or a grey dot (not yet run), plus its start time and duration. Common, recognizable failure patterns include:

A single early step fails with a nonzero exit code (for example, an alignment or QC step) — usually indicates bad or mismatched input data, such as a missing FASTQ pair, wrong reference build, or a sample-swap in the uploaded files. Verify the biosample’s uploaded files and file attributes before rerunning.
The run is stuck in QUEUED for a long time — usually a workspace compute-quota or backend issue; escalate to your administrator rather than rerunning.
The run fails at a late step after earlier steps succeeded — often a parameter or reference-data issue specific to that step; a Resume From Failed Step rerun (see below) is normally safe once the cause is understood.

When in doubt about whether an input problem or an infrastructure problem caused the failure, escalate to the BioinformaticsScientist or your administrator rather than repeatedly rerunning.

Rerun an analysis safely#

When a run has failed (EXECUTOR_ERROR or SYSTEM_ERROR) or has completed, the status dialog offers two rerun strategies:

Resume From Failed Step — reuses cached, validated outputs from steps that already completed successfully (for example QC and alignment) and only re-executes from the point of failure. Use this when the cause of failure has been fixed and the already-completed steps are still valid. Not available once the run has completed successfully.
Full Fresh Rerun — disables the cache and re-executes every step from scratch. Use this when the input data changed, a different workflow version is needed, or you cannot be certain the cached outputs are still valid.

Before rerunning:

Document the reason for the rerun in the case notes or audit log.
Confirm that the previous run should not be used for reporting.
Select the correct workflow version and input datasets.
Submit the new run.

Transition to REVIEW#

When the workflow completes successfully, the sample can move to REVIEW. Depending on your organization’s configuration, this may be an automatic transition or may require an authorized user to advance the sample.

Roles and handoffs#

Action	Typical role	Result
Upload data via the Reporter console (Option A)	MedicalTechnologist	Sample enters ANALYSIS automatically.
Upload/register data via SeqsLab CLI (Option B, step 1)	MedicalTechnologist, BioinformaticsScientist	Files exist as DRS objects, not yet linked to any biosample.
Associate CLI-registered files in Sample List (Option B, step 2)	MedicalTechnologist	Files are linked to the biosample.
Switch state to ANALYSIS (Option B, step 3)	MedicalTechnologist	Sample enters ANALYSIS.
Run the analysis pipeline	BioinformaticsScientist	Workflow run is created for the sample.
Monitor and interpret logs	MedicalTechnologist, BioinformaticsScientist	Diagnostic information for failures.
Rerun failed analysis	BioinformaticsScientist	New run attempt; sample remains or returns to ANALYSIS.
Advance to review	BioinformaticsScientist	Sample enters REVIEW.

Troubleshooting#

Problem	Possible cause	Action
Run submission fails	Missing input files, wrong file type, or permission error.	Check the error message, confirm file availability, and verify your role.
Run stays in queued state	Workspace compute quota exhausted.	Contact your administrator to check quota and backend status.
Run fails at an early step	Input metadata does not match assay requirements.	Verify sample metadata in the PENDING record.
Cannot advance to REVIEW	Pipeline produced no usable outputs or a required approval is missing.	Review outputs and consult the run log.
Associate Files search finds no matches	The registered file name does not contain the exact Sample ID, or the CLI registration step was not completed.	Confirm the file was registered with `datahub register-blob`, and that its name or tag includes the Sample ID used in Reporter.
Sample stuck in PENDING after CLI upload	Files were uploaded/registered and associated, but the state was never switched.	In Sample List, select the sample, use Switch State, and set it to ANALYSIS.
Expected tool is missing from Run Analysis	The tool is not registered with a name/tag matching the assay’s interpretation keyword.	Ask your BioinformaticsScientist or ToolRegistryWriter to verify the tool’s registration against the assay’s interpretation configuration.