README cleanup

README.md

@@ -4,38 +4,39 @@
 
 Version 2.0 (2026/10/18) · patch **2.0.1**
 
-BASIC reconstructs candidate immune-receptor transcripts from the short RNA
-sequencing reads of individual cells. Give it reads from one cell, choose a
-species and receptor type, and get assembled sequences with supporting reports.
-It supports B-cell receptor (**BCR**) heavy and light chains and T-cell receptor
-(**TCR**) chains. Human and mouse reference sequences are included.
+BASIC reconstructs candidate immune-receptor transcripts from a cell's short
+RNA-seq reads. It assembles B-cell receptor (**BCR**) heavy and light chains
+and T-cell receptor (**TCR**) chains. Each run takes the cell's reads, species,
+and receptor type and produces assembled sequences and reports. Human and
+mouse references are included.
 
 Reads must already be separated by cell. BASIC does not separate cell barcodes
 or deduplicate UMIs.
 
 ## The idea behind BASIC
 
-Sequencing reads cover short pieces of a transcript. **Assembly** joins reads
-that overlap into a longer sequence, called a **contig**. BASIC focuses this
-search on immune receptors:
+Each sequencing read covers a short part of a transcript. **Assembly** joins
+overlapping reads into a longer sequence, called a **contig**. BASIC assembles
+immune-receptor contigs in three steps:
 
-1. **Find starting reads.** Bowtie2 identifies reads matching known variable
-   and constant regions of a receptor. These reads become assembly *seeds*.
-2. **Extend through overlaps.** BASIC builds outward from the seeds using exact
-   sequence overlaps with other reads from the same cell.
-3. **Report candidate chains.** It writes assembled sequences and records
-   whether the variable and constant seeds connect, along with read support
-   and ambiguity information.
+1. **Find starting reads.** Bowtie2 finds reads that match known variable
+   and constant regions of a receptor. BASIC uses these reads as *seeds*.
+2. **Extend through overlaps.** BASIC extends the seeds using exact sequence
+   overlaps with other reads from the same cell.
+3. **Report candidate chains.** BASIC writes the assembled sequences and
+   reports whether the variable and constant seeds connect, the read support,
+   and any ambiguity encountered during assembly.
 
-A **complete** assembly connects its seeds. It does not by itself establish a
+A **complete** assembly connects its seeds. This does not guarantee a
 full coding sequence, a productive receptor, or a correct CDR3. Optional
 IgBLAST annotation can add gene calls, junction/CDR3 information, and predicted
 productivity.
 
 ## Install and try an example
 
-BASIC needs **Python 3.10+** and **Bowtie2**. On Linux or macOS, start from a
-checkout with the included examples. With Git and Conda installed:
+BASIC requires **Python 3.10+** and **Bowtie2**. On Linux or macOS, the following
+commands install BASIC and its dependencies and give you a copy of the
+examples. Git and Conda must already be installed:
 
 ```bash
 git clone https://github.com/akds/BASIC.git
@@ -46,8 +47,8 @@ python -m pip install .
 basic-assemble --version
 ```
 
-Already have Python and Bowtie2? Run `python -m pip install .` in your Python
-environment from the checkout. The [installation guide](docs/INSTALLATION.md)
+If Python 3.10+ and Bowtie2 are already installed, run `python -m pip install .`
+from the checkout in your Python environment. The [installation guide](docs/INSTALLATION.md)
 also covers [release wheels and checksums](https://github.com/akds/BASIC/releases/tag/v2.0.1),
 pipx, uv, and platform details. PyPI publication is deferred; the Bioconda
 `basic` update requires separate review and publication.
@@ -61,19 +62,19 @@ basic-assemble -SE examples/cell_A1/ERR1421621_1M_reads.fastq.gz \
 
 This example has one million single-end reads. Expect two contigs: a heavy
 chain of **878 nucleotides** and a light chain of **829 nucleotides**, saved in
-`results/cell_A1/result.fasta`. The reports are beside it. The comparison below
-checks both sequences against the supplied result.
+`results/cell_A1/result.fasta`. Reports are saved in the same directory. The
+comparison below checks both sequences against the supplied result.
 
-Add `--check` to check paths, indexes, and dependencies before assembly; it
+Add `--check` to verify paths, indexes, and dependencies before assembly; it
 does not read every FASTQ record. To rerun, choose a new output directory or
-add `--overwrite` to replace existing results explicitly.
+add `--overwrite` to replace existing results.
 
 ## Use your own reads
 
 Use reads with coverage across the receptor transcript. BASIC accepts
-single-end or paired-end FASTQ, plain or gzipped,
-with Phred+33 quality scores. Paired files must have matching identifiers and
-counts.
+single-end or paired-end FASTQ files, plain or gzipped, with Phred+33 quality
+scores. Paired files must contain the same number of reads with matching
+identifiers.
 
 Replace the filenames below with reads from one cell:
 
@@ -91,10 +92,11 @@ Use `-g mouse` for mouse reads. TCR outputs carry locus labels such as `TRA`
 and `TRB`; matching mouse reads and references also support gamma/delta
 (`TRG`/`TRD`) candidates. Recovery depends on the reads and available seeds.
 
-Incomplete assembly exits with an error by default. Add **`-a`** to retain
-partial or empty biological results; invalid input and execution errors still
-fail. Use `-p 4` for four Bowtie2 threads or `-b /path/to/bowtie2` to select the
-executable. Run `basic-assemble --help` for all options.
+By default, BASIC exits with an error if assembly is incomplete. Add **`-a`**
+to retain partial or empty assembly results. Invalid input and execution
+errors still cause the run to fail. Use `-p 4` for four Bowtie2 threads or
+`-b /path/to/bowtie2` to select the executable. Run `basic-assemble --help` for
+all options.
 
 ## Read the results
 
@@ -110,10 +112,10 @@ For the included example, look in `results/cell_A1/`:
 
 A chain is **complete** when its seeds connect, **partial** when a seed yields
 a contig but the seeds do not connect, or **unsupported** when neither seed is
-usable. Execution failures are recorded separately when possible. Gene calls,
-CDR3, and productivity remain empty
-unless annotation supplies them. Read support is a count of observations, not
-a molecule count or a confidence score.
+usable. Execution failures are recorded separately when possible. Gene-call,
+CDR3, and productivity fields remain empty unless annotation supplies them.
+Read support counts read observations, not molecules, and is not a confidence
+score.
 
 For automated workflows, use the run manifest as the completion marker and
 verify its output checksums. See [output and algorithm details](docs/ALGORITHMS.md).
@@ -131,16 +133,17 @@ python benchmarks/benchmark.py \
 ```
 
 Expect `exact_match_count: 2`, `exact_recall: 1.0`, and `exact_precision: 1.0`
-inside the JSON report's `sequences` object. Keep `-n result` in the example
-assembly command so the FASTA identifiers match. This checks reproducibility
-against an existing assembly; biological accuracy needs independent truth.
+in the JSON report's `sequences` object. Keep `-n result` in the example
+assembly command so the FASTA identifiers match. This checks that the run
+reproduces the stored assembly. Measuring biological accuracy requires
+independently validated sequences.
 
-For your own benchmark, replace `--expected-fasta` with independently validated
-sequences and `--actual-fasta` with your assemblies. Match FASTA identifiers
+For your own benchmark, pass the validated sequence file to `--expected-fasta`
+and your assembly file to `--actual-fasta`. Match FASTA identifiers
 and sequence orientation first: the script does not align or automatically
 pair contigs. Optional AIRR tables add gene-call, junction/CDR3, and productivity
-comparisons. The [benchmark guide](benchmarks/README.md) includes a timed example,
-metric definitions, and advice for fair comparisons. See the
+comparisons. The [benchmark guide](benchmarks/README.md) covers timing,
+metric definitions, and comparisons between tools or settings. See the
 [validation report](docs/VALIDATION.md) for measured results and their limits.
 
 ## Go further
@@ -160,15 +163,15 @@ catalogue or justify definitive gene calls across species.
 ## What's new in 2.0
 
 - **BCR and TCR assembly:** indexed overlap searches, shared read pools,
-  deterministic ties, and bounded searches; the default retains BASIC's
+  deterministic tie-breaking, and bounded searches; the default retains BASIC's
   original entropy-based extension rule.
 - **TCR reporting:** locus-aware chain labels, corrected historical mouse
   ordering, and support for matching mouse gamma/delta seeds.
-- **Everyday workflows:** stricter input checks, protected outputs, structured
+- **Workflows:** stricter input checks, protected outputs, structured
   reports, per-cell batches, optional annotation, and custom reference tools.
-- **Exploratory options:** quality and mate evidence, alternative assembly
-  paths, and multiple candidates. These remain experimental; no general
-  biological accuracy improvement is established.
+- **Experimental options:** quality and mate evidence, alternative assembly
+  paths, and multiple candidates. These have not been shown to improve
+  biological accuracy in general.
 
 Patch 2.0.1 fixes error handling when the operating system denies process-group
 cleanup. See the [changelog and migration notes](CHANGELOG.md),
@@ -180,7 +183,7 @@ For development, see [testing and release instructions](docs/RELEASING.md).
 Canzar S, Neu KE, Tang Q, Wilson PC, Khan AA. **BASIC: BCR assembly from single
 cells.** *Bioinformatics* 33(3), 1 February 2017.
 
-BASIC uses the [MIT license](LICENSE). Bundled references are preserved from
-BASIC 1.5.0; their original download dates are unknown. See
+BASIC is released under the [MIT license](LICENSE). The bundled references
+come from BASIC 1.5.0; their original download dates are unknown. See
 [reference provenance](db/provenance.json) and the [historical license notice](LICENSE-NOTICE.md).
-Reference data and external tools retain their respective terms.
+Reference data and external tools remain under their own terms.