Skip to main content

Run the workflow

Choose a reference genome and container images, then launch the multiomics workflow on a cell screening run directory.

The multiomics workflow runs with Nextflow on a laptop, an HPC cluster, or a cloud executor. Most runs need only the run directory, an output directory, and the container image parameters. Reference data comes from the selected genome.

Prerequisites​

  • Nextflow 25.04.0 or later (Java 17 or later). On Nextflow 26.04 or later, run export NXF_SYNTAX_PARSER=v1 before launching, because the workflow does not yet support the strict syntax parser that 26.04 enables by default.
  • Docker, Singularity, or Apptainer
  • An AVITI24™ cell screening run directory (local path or S3 URI) that contains RunParameters.json, RunManifest.csv, and Panel.json
  • Network access to pull the release container images (see Container images)
  • For data on S3: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_DEFAULT_REGION set in your environment

Reference data​

--genome selects the reference. GRCh38, the default and the only supported genome, provides the genome FASTA and index files, a STAR index built with STAR 2.7, and the GENCODE release 47 gene annotation. These files are read from the Element Biosciences reference bucket, which allows anonymous read access. To avoid remote reads, copy that layout to your own storage and point --igenomes_base at the copy.

NeedHow
Default referencesNothing to set. --genome GRCh38 is the default.
A different gene annotation on GRCh38Pass --genes_gtf with another GENCODE release for GRCh38.
A custom genomeSet --igenomes_ignore true and pass --fasta, --star_index, and --genes_gtf together. The STAR index must be built with STAR 2.7.4a or later from that FASTA, and the annotation must be a GENCODE-format GTF, which in practice means human or mouse.

Passing --fasta or --star_index with --genome is rejected, so a STAR index cannot be paired with a different genome by accident.

GENCODE human release 47 is the validated annotation. Other GENCODE releases use the same format and are expected to run. Release 31 is the minimum, because earlier releases split the lncRNA biotype that the default gene filter selects. Counts from other releases are not validated.

Pin one GTF release per analysis. gene_name is the count unit and symbols change between releases, so count matrices built against different GTF versions are not directly comparable.

Container images​

The workflow runs four Element tools in containers — Cells2Stats, Bases2Fastq™, elembio-diss-tools, and elembio-spatialdata-build — and defaults to the image tags validated for the release you run. To use different images (for example a private mirror), override the *_container_url / *_container_tag parameters at launch; the full list is in the parameter reference linked below.

Launch​

Nextflow fetches the workflow from the repository, whose README lists the images and references each release was validated with.

nextflow run Elembio/elembio-multiomics-nf \
    --run_dir /path/to/aviti24/run/directory \
    -profile AVITI24,docker

Results are written to ./results unless you set --outdir. For data on S3, use S3 URIs for --run_dir and --outdir. The run directory is read in place; only the tiles you process are downloaded.

Profiles​

ProfileDescription
dockerRun with Docker containers.
AVITI24Per-process CPU, memory, and time allocations for full AVITI24 runs. AVITI is an alias.
testSingle-tile smoke run on the public Cytos™ 3′ demo run with chromosome 20 references from the Element reference bucket.

Compute queues and cloud settings come from your executor configuration, for example a Seqera Platform compute environment or a -c overlay. Institutional configs from Elembio/configs load automatically when the machine is online.

Key options​

Most runs need only --run_dir. To process a subset of tiles or batches, reuse existing segmentation, or change the 3′ counting policy, see Parameters.

Resume​

Add -resume to the same command to continue a failed run from its last completed task.

Troubleshooting​

MessageCause and fix
--genome '...' is not supportedOnly the genomes listed in the message are available. Use GRCh38, or supply a custom genome with --igenomes_ignore true.
--fasta cannot be combined with --genomeThe FASTA and STAR index come from --genome. Remove --fasta and --star_index, or set --igenomes_ignore true and pass all three reference files.
--igenomes_ignore requires --fasta, --star_index and --genes_gtf togetherA custom genome needs all three files. The message lists the missing ones.
Config parsing failed with Unexpected inputNextflow 26.04 or later is using its strict syntax parser. Run export NXF_SYNTAX_PARSER=v1 and launch again.
STAR versionGenome mismatchA custom STAR index was built with STAR older than 2.7.4a. Rebuild it with STAR 2.7.4a or later.
No such file or directory: .../gencode.v47.annotation.gtf--igenomes_base points at a copy that lacks the GENCODE annotation. Copy the full reference layout, or pass --genes_gtf.
Access denied on S3AWS credentials are not set in the launching environment.

See also​

Last updated on