Metadata-Version: 2.4
Name: ask-ecdna
Version: 0.1.3
Summary: AmpliconSeeK: a Python toolkit for detecting amplified genomic structures and candidate extrachromosomal DNA from sequencing data
Home-page: https://github.com/nanawei11/AmpliconSeeK/
Author: Nana Wei
Author-email: nanawei11@163.com
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: memory-profiler
Requires-Dist: pandas
Requires-Dist: pysam
Requires-Dist: matplotlib
Requires-Dist: scipy
Requires-Dist: statsmodels
Requires-Dist: seaborn
Requires-Dist: scikit-learn
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


# AmpliconSeeK (ASK)

AmpliconSeeK (ASK) detects amplified genomic regions and reconstructs candidate extrachromosomal DNA (ecDNA) circles from aligned sequencing reads. It combines copy-number signal with breakpoint evidence (soft-clipped, split and supplementary alignments), and supports three tasks:

| Task                                                     | Command        | Input                          |
| -------------------------------------------------------- | -------------- | ------------------------------ |
| Find amplicons and candidate ecDNA in a sample           | `ask`        | Sorted, indexed BAM            |
| Assign single cells to each ecDNA                        | `ask -sc`    | Barcode-tagged BAM + fragments |
| Check whether a known ecDNA is present in another sample | `ask-search` | Known structure table + BAM    |

ASK has been applied to WGS, WES, ChIP-seq, MNase-seq, ATAC-seq, scATAC-seq and target-capture data.

[Documentation](https://ampliconseek.readthedocs.io/) · [Notebook tutorial](tutorial/ASK_pipeline_tutorials.ipynb) · [ecAtlas](https://wulab.bjmu.edu.cn/ask)

<p align="center"><img src="Figure/Figure1.png" width="60%" alt="AmpliconSeeK workflow" /></p>

## Contents

- [Installation](#installation)
- [Quick start](#quick-start)
- [FASTQ to BAM and ASK](#from-fastq-to-bam-and-ask)
- [Single-cell assignment](#single-cell-assignment)
- [Search for a known ecDNA](#search-for-a-known-ecdna)
- [Key outputs](#key-outputs)
- [Citation and contact](#citation-and-contact)

## Installation

Install [Miniconda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/linux.html) first if needed. On Linux x86_64:

```bash
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
```

Set up the Bioconda channels:

```bash
conda config --add channels bioconda
conda config --add channels conda-forge
conda config --set channel_priority strict
```

Create an environment with Python 3.11:

```bash
conda create -n ask -c conda-forge python=3.11
```

Activate the environment and install ASK from source:

```bash
conda activate ask
git clone https://github.com/nanawei11/AmpliconSeeK.git
cd AmpliconSeeK
python -m pip install -e .
```

Now you are ready to run ASK:

```bash
ask --help
ask-search --help
```

## Quick start

A coordinate-sorted, indexed BAM and matching genome build are required. The bundled `testdata.bam` uses hg19:

```bash
ask -i exampledata/testdata.bam -g hg19 \
  -o results/testdata/samplename
```

Common options:

| Option           | Meaning                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| `-g`           | Genome build of the BAM (`hg19` or `hg38`; default `hg38`).                                     |
| `--subseg`     | Infer sub-segments within amplified regions (on by default; disable with `--no-subseg`).            |
| `-c`           | Copy-number threshold for amplified segments (default 5).                                             |

ASK always filters SA evidence by NM ≤ `--nmmax` (default 1). The output prefix names the result files; for example, `results/testdata/samplename_ask_amplicon_circular.tsv` contains main circles. The bundled BAM is cropped, so it is intended for a workflow example rather than whole-sample CN calibration. See the [quickstart](docs/source/quickstart.rst) and [output guide](docs/source/outputs.rst).

The bundled BAM example produces this output layout:

```text
results/testdata/
├── samplename_ask_amplicon_circular.tsv
├── samplename_ask_amplicon_circular_stat.tsv
├── samplename_ask_amplicon_circular_derived.tsv
├── samplename_ask_amplicon_circular_derived_stat.tsv
├── samplename_ask_amplicon_linear.tsv
├── samplename_ask_amplified_segment.tsv
├── samplename_ask_bin_count.tsv
├── samplename_ask_bin_count_norm.tsv
├── samplename_ask_breakpoint.tsv
├── samplename_ask_breakpoint_pair.tsv
├── samplename_ask_breakpoint_pair_raw.tsv
├── samplename_ask_breakpoint_seg.tsv
├── samplename_ask_circle_representative_map.tsv
├── samplename_ask_clip_count.bedgraph
├── samplename_ask_cn_segmentation.tsv
├── samplename_ask_junctionseq/
│   └── circ_0.tsv
├── samplename_ask_plot/
│   ├── ampseg_0.pdf
│   ├── circular_circ_0.pdf
│   ├── circular_circ_0_derived_0.pdf
│   ├── circular_circ_0_derived_1.pdf
│   └── circular_circ_0_derived_2.pdf
├── samplename_ask_run_manifest.json
├── samplename_ask_stats.tsv
├── samplename_ask_step1.pdat
├── samplename_ask_step2.pdat
├── samplename_ask_step3.pdat
└── samplename_ask_step4.pdat
```

The number of circles, junction files, and plots depends on the sample. Single-cell and search runs add their own files, listed below.

## From FASTQ to BAM and ASK

For paired-end bulk reads, align to the same genome build selected for ASK. The reference FASTA must be indexed with `bwa index` before alignment:

```bash
set -o pipefail
bwa index reference/hg38.fa
bwa mem -t 5 reference/hg38.fa test_R1.fastq.gz test_R2.fastq.gz \
  | samtools sort -n -u -@ 5 -T tmp_test_name - \
  | samtools fixmate -u -@ 5 -m - - \
  | samtools sort -u -@ 5 -T tmp_test_coord - \
  | samtools markdup -@ 5 -S -s - test.bam
samtools index test.bam
ask -i test.bam -o results/test/test
```

For single-end bulk reads, skip `fixmate` and sort by genomic position before marking duplicates:

```bash
set -o pipefail
bwa index reference/hg38.fa
bwa mem -t 5 reference/hg38.fa test.fastq.gz \
  | samtools sort -@ 5 -T tmp_test_se - \
  | samtools markdup -@ 5 -S -s - test_se.bam
samtools index test_se.bam
ask -i test_se.bam -o results/test_se/test_se
```

Run the block that matches your library. See the [FASTQ guide](docs/source/fastq.rst) for the `map_bwa.sh` helper and batch metadata. Generic BWA alignment does not recover single-cell barcodes; single-cell FASTQ needs library-specific preprocessing that writes corrected `CB` tags.

## Single-cell assignment

Supply a barcode-tagged BAM and either an existing five-column fragment table or request fragment generation from the BAM. A barcode whitelist is optional.

```bash
ask -i exampledata/scExampleData.bam -g hg19 -d bias -sc \
  --fragments exampledata/scExampleData.fragments.tsv.gz \
  -o results/scExampleData/scExampleData
```

If no fragments table exists, install sinto and samtools, then run:

```bash
ask-make-fragments -i exampledata/scExampleData.bam \
  -o preprocessing/scExampleData_fragments
ask -i exampledata/scExampleData.bam -g hg19 -d bias -sc \
  --fragments preprocessing/scExampleData_fragments/fragments.tsv.gz \
  -o results/scExampleData_from_bam/scExampleData
```

The example uses ASK's automatic junction-read threshold. Fragment generation requires a coordinate-sorted paired-end BAM with corrected `CB` tags. See the [single-cell guide](docs/source/single_cell.rst) for the fragment format, filtering, and interpretation of the cell-by-ecDNA matrix.

## Search for a known ecDNA

`ask-search` accepts an ASK circular amplicon table, such as `<prefix>_ask_amplicon_circular.tsv`. A manually prepared reference must be a headered TSV with at least `AmpliconID`, `Chrom`, `Start`, `End`, and `Strand`. For one segment, the table can contain:

| AmpliconID | Chrom |    Start |      End | Strand |
| ---------- | ----- | -------: | -------: | :----: |
| circ_0     | chr7  | 54830975 | 56117062 |   +   |

For a multi-segment circle, list its segments in traversal order under the same `AmpliconID`:

| AmpliconID | Chrom |    Start |      End | Strand |
| ---------- | ----- | -------: | -------: | :----: |
| circ_0     | chr7  | 54830975 | 55200000 |   +   |
| circ_0     | chr7  | 55500000 | 56117062 |   +   |

Use the same genome build for the reference table and query BAM:

```bash
ask-search \
  --circular reference=results/testdata/samplename_ask_amplicon_circular.tsv \
  --bam exampledata/testdata.bam --genome hg19 \
  --outdir results/testdata_search \
  --outprefix results/testdata_search/query
```

Search reports at most one compatible structure per reference circle. A second `--circular` argument can include derived references. See the [search guide](docs/source/search.rst) for CN and junction criteria, and the [CLI reference](docs/source/cli_reference.rst) for all parameters.

## Key outputs

`<prefix>` is the value passed to `-o` (or search `--outprefix`). For example, `-o results/testdata/samplename` writes `results/testdata/samplename_ask_amplicon_circular.tsv`.

| Workflow      | Output                                                                                                   | What it contains                                                                                         |
| ------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Detection     | `<prefix>_ask_amplicon_circular.tsv`                                                                   | Main circles; one row per ordered genomic segment, grouped by `AmpliconID`.                            |
| Detection     | `<prefix>_ask_amplicon_circular_derived.tsv`                                                           | Alternative reconstructions associated with a main circle; may be empty.                                 |
| Detection     | `<prefix>_ask_amplicon_circular_stat.tsv` and `<prefix>_ask_amplicon_circular_derived_stat.tsv`      | One score/statistics row per main or derived circle.                                                     |
| Detection     | `<prefix>_ask_circle_representative_map.tsv`                                                           | Mapping from original circle IDs to main and derived IDs.                                                |
| Detection     | `<prefix>_ask_plot/`                                                                                   | PDF plots for the reported main and derived circles.                                                     |
| Detection     | `<prefix>_ask_breakpoint_pair_raw.tsv` and `<prefix>_ask_breakpoint_pair.tsv`                        | Candidate pairs with available read evidence, and the filtered pairs used for reconstruction.            |
| Detection     | `<prefix>_ask_amplified_segment.tsv` and `<prefix>_ask_bin_count_norm.tsv`                           | Amplified regions and normalized bin-level copy-number values.                                           |
| Single cell   | `<prefix>_ask_sc_cell_by_ecDNA_binary.tsv`                                                             | Cell × main-circle matrix of 0/1 assignments.                                                           |
| Single cell   | `<prefix>_ask_sc_cell_assignment_evidence_Q1_no_pair.tsv`                                              | Per-cell, per-circle evidence and assignment reasons.                                                    |
| Single cell   | `<prefix>_ask_sc_cell_by_breakpoint_support.tsv` and `<prefix>_ask_sc_cell_by_breakpoint_normal.tsv` | Cell × breakpoint-pair read counts; these are evidence matrices, not binary calls.                      |
| Search        | `reference_circle_matches.tsv` in `--outdir`                                                         | One row per input reference circle, including the match status and reported query circle.                |
| Search        | `<prefix>_ask_jcs.tsv` and `<prefix>_ask_reference_junction_evidence.tsv`                            | Per-reference JCS/CN decision and supporting-read evidence for each reference junction.                  |
| All workflows | `<prefix>_ask_run_manifest.json`                                                                       | Run command, effective parameters, input and output absolute paths, code version, and completion status. |

The run manifest is written at startup and updated when analysis finishes or fails. `outputs_created_or_updated` distinguishes this run's files from older results at the same prefix. Other files include linear candidates, CN segmentation, breakpoint annotations, and checkpoints. The [output guide](docs/source/outputs.rst) lists them and explains the single-cell and search counting conventions.

Circular reconstructions are computational hypotheses. Interpret them with assay coverage, structural ambiguity, and independent evidence in mind.

## Citation and contact

If you use ASK, cite the software as: Wei, N. (2026). *AmpliconSeeK* (version 0.1.3) [Software]. [GitHub repository](https://github.com/nanawei11/AmpliconSeeK). For questions, open a [GitHub issue](https://github.com/nanawei11/AmpliconSeeK/issues). ASK is distributed under the [MIT License](LICENSE).
