idtdna/pasta repository overview

⁠PASTA — Primer Anchored Statistical Translocation Analysis (Docker)

Detect chromosomal translocations from amplicon sequencing data — packaged as a ready-to-run Docker image. No local Python, conda, Java, or samtools installation required. Everything the tool needs is baked into the image.

⁠What this tool does

PASTA (Primer Anchored Statistical Translocation Analysis) takes demultiplexed amplicon sequencing reads (uBAM files) and:

1. Reconstructs the expected primers/amplicons from a BED file and reference genome.
2. Identifies primer pairs in each read to find candidate translocation junctions.
3. Statistically tests treatment vs. control samples (using DESeq2 or a hypergeometric test) to call significant translocations.
4. Aggregates and summarizes results into per-comparison and combined CSV reports.

It is designed for primer-anchored assays where P5 and P7 indices are both fixed or random.

⁠Quick start

⁠1. Pull the image

docker pull idtdna/pasta:v1.1.0

⁠2. See the available options

The image's entrypoint is the PASTA orchestrator, so you can pass --help directly:

docker run --rm idtdna/pasta:v1.1.0 --help

⁠3. Run an analysis

PASTA reads all sample metadata and file paths from a single YAML configuration file. Because your data (uBAMs, reference genome, BED files) and the config live on your machine, you must mount them into the container and make sure the paths inside the config match the mounted locations.

docker run --rm \
  -v /path/to/your/data:/data \
  -v /path/to/results:/results \
   idtdna/pasta:v1.1.0 \
  --config /data/pasta_config.yaml \
  --threads 8 \
  --tool-threads 4 \
  --outdir /results

• -v /path/to/your/data:/data — mounts your local data folder (config, uBAMs, genome, BED files) into the container at /data.
• -v /path/to/results:/results — mounts a local folder where outputs will be written.
• Everything after the image name is passed straight to PASTA.

⁠Command options

Performance guidance: PASTA manages the whole workflow within a single process (no external workflow manager). For best results use one large machine and scale --threads cautiously — some steps are memory intensive and too many workers can exhaust available memory.

⁠Preparing your configuration file

Create a YAML file (for example pasta_config.yaml) describing each sample. A minimal example:

Samples:
  Sample_Control:
    uBAM: /data/uBAM/control.unmapped.bam
    ComparisonGroup: ['1']          # groups this sample participates in
    SampleType: 'Control'           # 'Control' or 'Treatment'
    Description: Control_Rep1
    Amplicon_Sequences: /data/primers/amplicons_6col_amp.bed
    pasta_downsample: TRUE          # 'TRUE'/'FALSE' — enable per-sample downsampling
    pasta_downsample_value: 100000  # reads to downsample to when enabled
    pasta_pvalue: 0.01              # significance threshold
    pasta_signal: 0.01              # minimum % translocation signal
    pasta_method: 'deseq2'       # 'hypergeom' or 'deseq2'
    pasta_min_cov: 100              # minimum coverage before flagging
    pasta_calc: 'mean'              # translocation frequency calc method
    SummaryGraphs: true             # optional — render summary graphs
    Genome:
      hg38:
        Sequence: /data/genome/hg38_primary.fa
        CustomGenomeFasta: /data/genome/hg38_primary.fa
        TargetBed: /data/primers/amplicons.bed
        SnpEffGenome: hg38

  Sample_Treatment:
    uBAM: /data/uBAM/treatment.unmapped.bam
    ComparisonGroup: ['1']
    SampleType: 'Treatment'
    Description: Treatment_Rep1
    Amplicon_Sequences: /data/primers/amplicons_6col_amp.bed
    pasta_method: 'hypergeom'
    pasta_pvalue: 0.01
    pasta_signal: 0.01
    pasta_min_cov: 100
    pasta_calc: 'mean'
    Genome:
      hg38:
        Sequence: /data/genome/hg38_primary.fa
        CustomGenomeFasta: /data/genome/hg38_primary.fa
        TargetBed: /data/primers/amplicons.bed
        SnpEffGenome: hg38

Requirements for a valid comparison: each ComparisonGroup must contain at least one Control and one Treatment sample. Groups that don't meet this are skipped.

⁠Key parameters

⁠Outputs

Point --outdir at a mounted folder. PASTA writes:

results/
├── bamfiles/              # BAMs produced during primer identification
├── primers/               # Primer inputs, identified primers, and amplicon files (troubleshooting)
├── group_translocations/  # Per-comparison translocation CSVs + summaries (key deliverable)
├── sample_translocations/ # Legacy directory (slated for deprecation)
├── graphs/                # Summary graphs (when SummaryGraphs is enabled)
└── all_identified_translocations.csv   # Final aggregated results (also printed to the console)

⁠Full example

# Layout on the host:
#   /home/me/pasta_run/
#   ├── pasta_config.yaml
#   ├── uBAM/         (your *.unmapped.bam files)
#   ├── genome/       (hg38 FASTA)
#   └── primers/      (amplicon BED files)

docker run --rm \
  -v /home/me/pasta_run:/data \
  -v /home/me/pasta_run/results:/results \
   idtdna/pasta:latest \
  --config /data/pasta_config.yaml \
  --threads 8 \
  --tool-threads 4 \
  --outdir /results

When it finishes, your calls are in /home/me/pasta_run/results/ and the aggregated table is printed to the terminal.

⁠Tips & troubleshooting

• "File not found" errors almost always mean a path in the YAML points at a host path that isn't mounted. Mount the folder and use the in-container path (/data/...).
• Start with modest --threads / --tool-threads and scale up as resources allow.
• Add --user "$(id -u):$(id -g)" to the docker run command if you want output files owned by your host user instead of root.
• Review the console log — the orchestrator prints per-stage progress and diagnostics.

⁠License and Permitted Use

PASTA is made available for academic, educational, governmental, non-profit, and internal commercial research purposes.

Commercial organizations may use PASTA for internal research and development activities, including the discovery, development, testing, and evaluation of therapeutic, agricultural, industrial, and research applications.

⁠Restricted Commercial Uses

Without obtaining a separate commercial license from the copyright holder, PASTA may not be used by any person or organization whose primary business includes the commercial development, manufacture, marketing, sale, licensing, or provision of genome editing products, reagents, platforms, software, or services.

This restriction includes, but is not limited to, entities that:

• Manufacture or sell genome editing reagents or kits.
• Manufacture or sell CRISPR, TALEN, zinc-finger, base-editing, prime-editing, or similar genome engineering products.
• Provide genome editing design, optimization, validation, characterization, or analytical services to third parties.
• Provide off-target prediction, off-target validation, genome editing safety assessment, or related fee-for-service offerings.
• License, distribute, or commercialize genome editing software platforms, databases, or workflow solutions.
• Operate as contract research organizations (CROs) or service providers offering genome editing services to customers for compensation.

⁠Permitted Commercial Uses

The following are examples of permitted uses under this license:

• Academic and government research.
• Internal research and development conducted by biotechnology and pharmaceutical companies.
• Development of therapeutics, diagnostics, agricultural products, and other end-use products that may utilize genome editing technologies during research and development.
• Evaluation of genome editing outcomes within an organization's own research programs.
• Internal use by companies whose primary business is not the commercial sale of genome editing reagents, platforms, software, or services.

⁠Clarification

For the avoidance of doubt, the development of therapeutic products, diagnostic products, agricultural products, or other end-use applications is considered a permitted use under this license, provided that the user is not commercially offering genome editing reagents, genome editing platforms, genome editing software products, or genome editing analysis services to third parties.

Organizations developing drugs, biologics, cell therapies, gene therapies, or other therapeutic products for their own pipelines may use PASTA for internal research and development activities, even when those activities involve genome editing technologies.

The restrictions in this license are intended to apply primarily to organizations whose principal commercial activities involve the sale, licensing, manufacture, or provision of genome editing reagents, genome editing products, genome editing software, or genome editing services, and are not intended to restrict the internal use of PASTA by therapeutic developers, pharmaceutical companies, biotechnology companies, or similar organizations developing end-use products.

⁠Examples

⁠Permitted

• An biotech organization using PASTA to evaluate CRISPR-edited cells in an internal therapeutic discovery program.
• A therapeutic development organization using PASTA to support the development of a gene therapy candidate.
• A university laboratory using PASTA for publication-generating research.
• A healthcare, agricultural, or biotechnology company using PASTA to analyze genome editing outcomes generated as part of its own product development efforts, not related to subject areas where restrictions apply.

⁠Not Permitted Without a Separate Commercial License

• A company selling Cas9 mRNA, guide RNAs (gRNAs), CRISPR kits, or other genome editing reagents.
• A company offering CRISPR design services to customers.
• A company providing off-target safety assessment services for compensation.
• A company offering genome editing analytics as a fee-for-service business.
• A company commercializing genome editing software products, platforms, or workflow solutions.
• Any organization whose primary business is the commercial provision of genome editing products, reagents, software, or services and that uses PASTA in support of those offerings.

⁠Acceptance

By downloading, accessing, or using PASTA, you agree to the terms described above. Organizations wishing to engage in a restricted commercial use must obtain a separate written commercial license from the copyright holder before using PASTA for such purposes.