dotmatch 0.2.0__tar.gz → 0.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. {dotmatch-0.2.0 → dotmatch-0.2.2}/CITATION.cff +1 -2
  2. dotmatch-0.2.2/PKG-INFO +285 -0
  3. dotmatch-0.2.2/README.md +241 -0
  4. {dotmatch-0.2.0 → dotmatch-0.2.2}/codemeta.json +4 -4
  5. {dotmatch-0.2.0 → dotmatch-0.2.2}/include/qdalign.h +1 -1
  6. {dotmatch-0.2.0 → dotmatch-0.2.2}/pyproject.toml +7 -6
  7. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/__init__.py +1 -1
  8. dotmatch-0.2.2/python/dotmatch.egg-info/PKG-INFO +285 -0
  9. dotmatch-0.2.0/PKG-INFO +0 -898
  10. dotmatch-0.2.0/README.md +0 -855
  11. dotmatch-0.2.0/python/dotmatch.egg-info/PKG-INFO +0 -898
  12. {dotmatch-0.2.0 → dotmatch-0.2.2}/LICENSE +0 -0
  13. {dotmatch-0.2.0 → dotmatch-0.2.2}/MANIFEST.in +0 -0
  14. {dotmatch-0.2.0 → dotmatch-0.2.2}/docs/assay-evidence.json +0 -0
  15. {dotmatch-0.2.0 → dotmatch-0.2.2}/include/qdmetal.h +0 -0
  16. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/assaycode/__init__.py +0 -0
  17. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/assaycode/cli.py +0 -0
  18. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/assayruntime.py +0 -0
  19. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/assayscript.py +0 -0
  20. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/assaysim.py +0 -0
  21. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/assayspec.py +0 -0
  22. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/assaywatch.py +0 -0
  23. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/calibration.py +0 -0
  24. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/calibration_io.py +0 -0
  25. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/cli.py +0 -0
  26. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/core.py +0 -0
  27. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/multiqc.py +0 -0
  28. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/native.py +0 -0
  29. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/panel.py +0 -0
  30. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/tl.py +0 -0
  31. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch.egg-info/SOURCES.txt +0 -0
  32. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch.egg-info/dependency_links.txt +0 -0
  33. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch.egg-info/entry_points.txt +0 -0
  34. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch.egg-info/requires.txt +0 -0
  35. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch.egg-info/top_level.txt +0 -0
  36. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/quickdna/__init__.py +0 -0
  37. {dotmatch-0.2.0 → dotmatch-0.2.2}/python/quickdna/core.py +0 -0
  38. {dotmatch-0.2.0 → dotmatch-0.2.2}/setup.cfg +0 -0
  39. {dotmatch-0.2.0 → dotmatch-0.2.2}/setup.py +0 -0
  40. {dotmatch-0.2.0 → dotmatch-0.2.2}/src/qda.c +0 -0
  41. {dotmatch-0.2.0 → dotmatch-0.2.2}/src/qdalign.c +0 -0
  42. {dotmatch-0.2.0 → dotmatch-0.2.2}/src/qdmetal.mm +0 -0
  43. {dotmatch-0.2.0 → dotmatch-0.2.2}/src/qdmetal_stub.c +0 -0
@@ -8,8 +8,7 @@ authors:
8
8
  orcid: "https://orcid.org/0009-0003-5012-7229"
9
9
  repository-code: "https://github.com/dnncha/dotmatch"
10
10
  license: Apache-2.0
11
- version: "0.2.0"
12
- doi: 10.5281/zenodo.20541628
11
+ version: "0.2.2"
13
12
  abstract: "DotMatch is a deterministic known-target short-DNA assignment engine for CRISPR guide counting, barcode demultiplexing, and fixed-target FASTQ workflows."
14
13
  keywords:
15
14
  - bioinformatics
@@ -0,0 +1,285 @@
1
+ Metadata-Version: 2.4
2
+ Name: dotmatch
3
+ Version: 0.2.2
4
+ Summary: Known-target short-DNA assignment from FASTQ for CRISPR guides, barcodes, feature tags, primers, and other targets
5
+ Author: Donncha O'Toole
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://dnncha.github.io/dotmatch/
8
+ Project-URL: Repository, https://github.com/dnncha/dotmatch
9
+ Project-URL: Issues, https://github.com/dnncha/dotmatch/issues
10
+ Project-URL: Documentation, https://dotmatch.readthedocs.io/en/latest/
11
+ Project-URL: Changelog, https://github.com/dnncha/dotmatch/blob/main/CHANGELOG.md
12
+ Keywords: bioinformatics,computational biology,CRISPR,FASTQ,known-target assignment,feature barcodes,sequencing QC,barcode demultiplexing,edit distance
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: Programming Language :: C
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.9
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
24
+ Requires-Python: >=3.9
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Requires-Dist: tomli; python_version < "3.11"
28
+ Provides-Extra: pandas
29
+ Requires-Dist: pandas>=1.0; extra == "pandas"
30
+ Provides-Extra: anndata
31
+ Requires-Dist: anndata>=0.8; extra == "anndata"
32
+ Requires-Dist: pandas>=1.0; extra == "anndata"
33
+ Provides-Extra: polars
34
+ Requires-Dist: polars>=0.19; extra == "polars"
35
+ Provides-Extra: multiqc
36
+ Requires-Dist: multiqc>=1.20; extra == "multiqc"
37
+ Provides-Extra: dev
38
+ Requires-Dist: pytest; extra == "dev"
39
+ Requires-Dist: pandas>=1.0; extra == "dev"
40
+ Requires-Dist: anndata>=0.8; extra == "dev"
41
+ Requires-Dist: polars>=0.19; extra == "dev"
42
+ Requires-Dist: multiqc>=1.20; extra == "dev"
43
+ Dynamic: license-file
44
+
45
+ # DotMatch
46
+
47
+ DotMatch assigns short FASTQ read windows to a known list of DNA sequences. It
48
+ is useful when you already know the guides, barcodes, feature tags, primers, or
49
+ other targets that may be present and want every read reported as a unique
50
+ match, an ambiguous match, unmatched, or invalid.
51
+
52
+ [![CI](https://github.com/dnncha/dotmatch/actions/workflows/ci.yml/badge.svg)](https://github.com/dnncha/dotmatch/actions/workflows/ci.yml)
53
+ [![PyPI](https://img.shields.io/pypi/v/dotmatch?label=PyPI)](https://pypi.org/project/dotmatch/)
54
+ [![Documentation](https://readthedocs.org/projects/dotmatch/badge/?version=latest)](https://dotmatch.readthedocs.io/en/latest/)
55
+ [![Bioconda](https://img.shields.io/conda/vn/bioconda/dotmatch?label=Bioconda)](https://anaconda.org/bioconda/dotmatch)
56
+ [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/dnncha/dotmatch/blob/main/LICENSE)
57
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20541628.svg)](https://doi.org/10.5281/zenodo.20541628)
58
+
59
+ [Documentation](https://dotmatch.readthedocs.io/en/latest/) ·
60
+ [Getting started](https://dotmatch.readthedocs.io/en/latest/getting-started.html) ·
61
+ [Command reference](https://dotmatch.readthedocs.io/en/latest/command-reference.html) ·
62
+ [Examples](https://github.com/dnncha/dotmatch/tree/main/examples) ·
63
+ [Citation](https://dotmatch.readthedocs.io/en/latest/methods-and-citation.html)
64
+
65
+ ![FASTQ reads and a target table are compared at a fixed read window. DotMatch writes counts, split FASTQs, QC tables, and reports.](https://raw.githubusercontent.com/dnncha/dotmatch/main/public/dotmatch-read-assignment.svg)
66
+
67
+ ## Install
68
+
69
+ PyPI is the quickest route on Linux and macOS:
70
+
71
+ ```bash
72
+ python3 -m pip install dotmatch
73
+ dotmatch --version
74
+ ```
75
+
76
+ Conda users can install the current Bioconda build:
77
+
78
+ ```bash
79
+ conda create -n dotmatch -c conda-forge -c bioconda dotmatch
80
+ conda activate dotmatch
81
+ ```
82
+
83
+ The Bioconda recipe supports Linux, Intel macOS, and Apple Silicon
84
+ (`osx-arm64`). If a newly tagged version has not reached Bioconda yet, use the
85
+ PyPI package or install from source.
86
+
87
+ ## A small example
88
+
89
+ Prepare a tab-separated target file:
90
+
91
+ ```text
92
+ target_id sequence
93
+ guide_001 ACGTACGTACGTACGTACGT
94
+ guide_002 ACGTACGTACGTACGTAGGT
95
+ ```
96
+
97
+ Then assign a fixed 20-base window from each read:
98
+
99
+ ```bash
100
+ dotmatch count \
101
+ --targets guides.tsv \
102
+ --reads sample_R1.fastq.gz \
103
+ --sample-label sample_1 \
104
+ --target-start 23 \
105
+ --target-length 20 \
106
+ --k 1 \
107
+ --metric hamming \
108
+ --out counts.tsv \
109
+ --sample-qc sample_qc.tsv \
110
+ --summary summary.json
111
+ ```
112
+
113
+ DotMatch only counts a read when exactly one target is compatible under the
114
+ selected matching rule. Reads that fit several targets remain visible as
115
+ ambiguous instead of being assigned arbitrarily.
116
+
117
+ ## What it is for
118
+
119
+ - counting CRISPR guides and writing MAGeCK-compatible count tables;
120
+ - demultiplexing fixed-position inline barcodes;
121
+ - assigning feature-barcode and guide-capture reads;
122
+ - checking primer, adapter, amplicon-panel, or whitelist sequences;
123
+ - auditing target lists before enabling mismatch correction;
124
+ - designing and checking barcode panels;
125
+ - writing TSV, JSON, FASTQ, and HTML results for pipelines and lab review.
126
+
127
+ DotMatch is not a genome aligner, basecaller, UMI pipeline, variant caller, or
128
+ screen-level statistics package. It compares short read windows with a finite
129
+ target list.
130
+
131
+ ## Read outcomes
132
+
133
+ | Outcome | Meaning |
134
+ | --- | --- |
135
+ | `unique` | Exactly one target is compatible. |
136
+ | `ambiguous` | More than one target is compatible. |
137
+ | `none` | No target is within the selected distance. |
138
+ | `invalid` | The requested read window could not be extracted. |
139
+
140
+ These states appear in the assignment and QC outputs. They are not folded into
141
+ the unique counts.
142
+
143
+ ## Common workflows
144
+
145
+ ### Count CRISPR guides
146
+
147
+ For a new screen, DotMatch can prepare a small assay project and infer a likely
148
+ guide window for review:
149
+
150
+ ```bash
151
+ dotmatch crispr quickstart \
152
+ --library guides.csv \
153
+ --fastq 'fastqs/*.fastq.gz' \
154
+ --out crispr_screen/
155
+ ```
156
+
157
+ Review `crispr_screen/inference_report.json` and `assay.toml`, then run:
158
+
159
+ ```bash
160
+ dotmatch assay start crispr_screen/assay.toml
161
+ ```
162
+
163
+ For an explicit one-command run, use `dotmatch crispr-count`. The
164
+ [CRISPR tutorial](https://dotmatch.readthedocs.io/en/latest/tutorials/crispr-count-first-run.html)
165
+ covers both routes.
166
+
167
+ ### Demultiplex inline barcodes
168
+
169
+ ```bash
170
+ dotmatch demux \
171
+ --barcodes barcodes.tsv \
172
+ --reads pooled.fastq.gz \
173
+ --barcode-start 0 \
174
+ --barcode-length 8 \
175
+ --k 1 \
176
+ --metric hamming \
177
+ --out-dir demuxed/ \
178
+ --summary demux.summary.json
179
+ ```
180
+
181
+ If a run has an unexpectedly high unmatched or ambiguous rate, inspect it with:
182
+
183
+ ```bash
184
+ dotmatch barcode autopsy \
185
+ --barcodes barcodes.tsv \
186
+ --reads pooled.fastq.gz \
187
+ --scan-starts 0:12 \
188
+ --k-values 0,1 \
189
+ --out-dir autopsy/
190
+ ```
191
+
192
+ Open `autopsy/report.html` first. The tables beside it record offset scans,
193
+ near-neighbour barcodes, correction safety, and frequent unmatched windows.
194
+
195
+ ### Check a target library
196
+
197
+ Before allowing mismatch correction, check whether neighbouring targets can
198
+ produce ambiguous assignments:
199
+
200
+ ```bash
201
+ dotmatch audit \
202
+ --targets guides.tsv \
203
+ --k 1 \
204
+ --audit-mode auto \
205
+ --out-dir audit/
206
+ ```
207
+
208
+ The [barcode panel guide](https://dotmatch.readthedocs.io/en/latest/barcode-panel-design.html)
209
+ also covers panel design, optimisation, simulation, layout, and export.
210
+
211
+ ## Python API
212
+
213
+ ```python
214
+ import dotmatch
215
+
216
+ distance = dotmatch.distance("ACGT", "AGGT")
217
+ assert distance == 1
218
+
219
+ result = dotmatch.assign_posterior("ACGT", ["ACGT", "AGGT"], "IIII")
220
+ print(result.status)
221
+ ```
222
+
223
+ The posterior helper is experimental and is not used by the high-throughput
224
+ CLI path. The [Python API documentation](https://dotmatch.readthedocs.io/en/latest/streaming-api.html)
225
+ describes the supported streaming interfaces.
226
+
227
+ ## Outputs and workflow integration
228
+
229
+ Depending on the command, DotMatch writes count tables, split FASTQs,
230
+ `sample_qc.tsv`, per-read assignments, unmatched-read tables, `summary.json`,
231
+ and self-contained HTML reports. The formats are documented in the
232
+ [output schema reference](https://dotmatch.readthedocs.io/en/latest/schemas.html).
233
+
234
+ Examples for Nextflow, nf-core, Snakemake, Galaxy, and MultiQC live under
235
+ [`examples/workflows`](https://github.com/dnncha/dotmatch/tree/main/examples/workflows).
236
+ The desktop Workbench is maintained separately in
237
+ [`dotmatch-community`](https://github.com/dnncha/dotmatch-community).
238
+
239
+ ## Matching rules and performance
240
+
241
+ Hamming distance is the usual choice for fixed-length windows where only base
242
+ substitutions should be considered. Levenshtein distance can also account for
243
+ short insertions and deletions. The default radius policy requires a single
244
+ compatible target; the optional `best` policy exists for compatibility with
245
+ workflows that select the nearest target.
246
+
247
+ Indexed candidate generation and native distance kernels make fixed-window
248
+ assignment practical for large FASTQ inputs. Benchmark results, hardware,
249
+ commands, and known limitations are kept with the
250
+ [benchmark reports](https://dotmatch.readthedocs.io/en/latest/benchmarks/README.html).
251
+ Those reports cover the tested workloads; they are not a claim that DotMatch
252
+ replaces general alignment or every demultiplexing workflow.
253
+
254
+ ## Documentation
255
+
256
+ - [Getting started](https://dotmatch.readthedocs.io/en/latest/getting-started.html)
257
+ - [Command reference](https://dotmatch.readthedocs.io/en/latest/command-reference.html)
258
+ - [AssaySpec workflows](https://dotmatch.readthedocs.io/en/latest/assayspec.html)
259
+ - [CRISPR count QC](https://dotmatch.readthedocs.io/en/latest/crispr-qc.html)
260
+ - [Barcode panel design](https://dotmatch.readthedocs.io/en/latest/barcode-panel-design.html)
261
+ - [Output schemas](https://dotmatch.readthedocs.io/en/latest/schemas.html)
262
+ - [Methods and citation](https://dotmatch.readthedocs.io/en/latest/methods-and-citation.html)
263
+ - [Packaging notes](https://dotmatch.readthedocs.io/en/latest/packaging.html)
264
+
265
+ ## Citation
266
+
267
+ Run `dotmatch citation` to print the citation for the installed version. The
268
+ repository also includes [`CITATION.cff`](https://github.com/dnncha/dotmatch/blob/main/CITATION.cff),
269
+ and release archives are deposited with Zenodo.
270
+
271
+ ## Development
272
+
273
+ ```bash
274
+ git clone https://github.com/dnncha/dotmatch.git
275
+ cd dotmatch
276
+ make
277
+ make test
278
+ ```
279
+
280
+ See [CONTRIBUTING.md](https://github.com/dnncha/dotmatch/blob/main/CONTRIBUTING.md)
281
+ for the development setup and pull-request checks.
282
+
283
+ ## License
284
+
285
+ Apache-2.0. See [LICENSE](https://github.com/dnncha/dotmatch/blob/main/LICENSE).
@@ -0,0 +1,241 @@
1
+ # DotMatch
2
+
3
+ DotMatch assigns short FASTQ read windows to a known list of DNA sequences. It
4
+ is useful when you already know the guides, barcodes, feature tags, primers, or
5
+ other targets that may be present and want every read reported as a unique
6
+ match, an ambiguous match, unmatched, or invalid.
7
+
8
+ [![CI](https://github.com/dnncha/dotmatch/actions/workflows/ci.yml/badge.svg)](https://github.com/dnncha/dotmatch/actions/workflows/ci.yml)
9
+ [![PyPI](https://img.shields.io/pypi/v/dotmatch?label=PyPI)](https://pypi.org/project/dotmatch/)
10
+ [![Documentation](https://readthedocs.org/projects/dotmatch/badge/?version=latest)](https://dotmatch.readthedocs.io/en/latest/)
11
+ [![Bioconda](https://img.shields.io/conda/vn/bioconda/dotmatch?label=Bioconda)](https://anaconda.org/bioconda/dotmatch)
12
+ [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/dnncha/dotmatch/blob/main/LICENSE)
13
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20541628.svg)](https://doi.org/10.5281/zenodo.20541628)
14
+
15
+ [Documentation](https://dotmatch.readthedocs.io/en/latest/) ·
16
+ [Getting started](https://dotmatch.readthedocs.io/en/latest/getting-started.html) ·
17
+ [Command reference](https://dotmatch.readthedocs.io/en/latest/command-reference.html) ·
18
+ [Examples](https://github.com/dnncha/dotmatch/tree/main/examples) ·
19
+ [Citation](https://dotmatch.readthedocs.io/en/latest/methods-and-citation.html)
20
+
21
+ ![FASTQ reads and a target table are compared at a fixed read window. DotMatch writes counts, split FASTQs, QC tables, and reports.](https://raw.githubusercontent.com/dnncha/dotmatch/main/public/dotmatch-read-assignment.svg)
22
+
23
+ ## Install
24
+
25
+ PyPI is the quickest route on Linux and macOS:
26
+
27
+ ```bash
28
+ python3 -m pip install dotmatch
29
+ dotmatch --version
30
+ ```
31
+
32
+ Conda users can install the current Bioconda build:
33
+
34
+ ```bash
35
+ conda create -n dotmatch -c conda-forge -c bioconda dotmatch
36
+ conda activate dotmatch
37
+ ```
38
+
39
+ The Bioconda recipe supports Linux, Intel macOS, and Apple Silicon
40
+ (`osx-arm64`). If a newly tagged version has not reached Bioconda yet, use the
41
+ PyPI package or install from source.
42
+
43
+ ## A small example
44
+
45
+ Prepare a tab-separated target file:
46
+
47
+ ```text
48
+ target_id sequence
49
+ guide_001 ACGTACGTACGTACGTACGT
50
+ guide_002 ACGTACGTACGTACGTAGGT
51
+ ```
52
+
53
+ Then assign a fixed 20-base window from each read:
54
+
55
+ ```bash
56
+ dotmatch count \
57
+ --targets guides.tsv \
58
+ --reads sample_R1.fastq.gz \
59
+ --sample-label sample_1 \
60
+ --target-start 23 \
61
+ --target-length 20 \
62
+ --k 1 \
63
+ --metric hamming \
64
+ --out counts.tsv \
65
+ --sample-qc sample_qc.tsv \
66
+ --summary summary.json
67
+ ```
68
+
69
+ DotMatch only counts a read when exactly one target is compatible under the
70
+ selected matching rule. Reads that fit several targets remain visible as
71
+ ambiguous instead of being assigned arbitrarily.
72
+
73
+ ## What it is for
74
+
75
+ - counting CRISPR guides and writing MAGeCK-compatible count tables;
76
+ - demultiplexing fixed-position inline barcodes;
77
+ - assigning feature-barcode and guide-capture reads;
78
+ - checking primer, adapter, amplicon-panel, or whitelist sequences;
79
+ - auditing target lists before enabling mismatch correction;
80
+ - designing and checking barcode panels;
81
+ - writing TSV, JSON, FASTQ, and HTML results for pipelines and lab review.
82
+
83
+ DotMatch is not a genome aligner, basecaller, UMI pipeline, variant caller, or
84
+ screen-level statistics package. It compares short read windows with a finite
85
+ target list.
86
+
87
+ ## Read outcomes
88
+
89
+ | Outcome | Meaning |
90
+ | --- | --- |
91
+ | `unique` | Exactly one target is compatible. |
92
+ | `ambiguous` | More than one target is compatible. |
93
+ | `none` | No target is within the selected distance. |
94
+ | `invalid` | The requested read window could not be extracted. |
95
+
96
+ These states appear in the assignment and QC outputs. They are not folded into
97
+ the unique counts.
98
+
99
+ ## Common workflows
100
+
101
+ ### Count CRISPR guides
102
+
103
+ For a new screen, DotMatch can prepare a small assay project and infer a likely
104
+ guide window for review:
105
+
106
+ ```bash
107
+ dotmatch crispr quickstart \
108
+ --library guides.csv \
109
+ --fastq 'fastqs/*.fastq.gz' \
110
+ --out crispr_screen/
111
+ ```
112
+
113
+ Review `crispr_screen/inference_report.json` and `assay.toml`, then run:
114
+
115
+ ```bash
116
+ dotmatch assay start crispr_screen/assay.toml
117
+ ```
118
+
119
+ For an explicit one-command run, use `dotmatch crispr-count`. The
120
+ [CRISPR tutorial](https://dotmatch.readthedocs.io/en/latest/tutorials/crispr-count-first-run.html)
121
+ covers both routes.
122
+
123
+ ### Demultiplex inline barcodes
124
+
125
+ ```bash
126
+ dotmatch demux \
127
+ --barcodes barcodes.tsv \
128
+ --reads pooled.fastq.gz \
129
+ --barcode-start 0 \
130
+ --barcode-length 8 \
131
+ --k 1 \
132
+ --metric hamming \
133
+ --out-dir demuxed/ \
134
+ --summary demux.summary.json
135
+ ```
136
+
137
+ If a run has an unexpectedly high unmatched or ambiguous rate, inspect it with:
138
+
139
+ ```bash
140
+ dotmatch barcode autopsy \
141
+ --barcodes barcodes.tsv \
142
+ --reads pooled.fastq.gz \
143
+ --scan-starts 0:12 \
144
+ --k-values 0,1 \
145
+ --out-dir autopsy/
146
+ ```
147
+
148
+ Open `autopsy/report.html` first. The tables beside it record offset scans,
149
+ near-neighbour barcodes, correction safety, and frequent unmatched windows.
150
+
151
+ ### Check a target library
152
+
153
+ Before allowing mismatch correction, check whether neighbouring targets can
154
+ produce ambiguous assignments:
155
+
156
+ ```bash
157
+ dotmatch audit \
158
+ --targets guides.tsv \
159
+ --k 1 \
160
+ --audit-mode auto \
161
+ --out-dir audit/
162
+ ```
163
+
164
+ The [barcode panel guide](https://dotmatch.readthedocs.io/en/latest/barcode-panel-design.html)
165
+ also covers panel design, optimisation, simulation, layout, and export.
166
+
167
+ ## Python API
168
+
169
+ ```python
170
+ import dotmatch
171
+
172
+ distance = dotmatch.distance("ACGT", "AGGT")
173
+ assert distance == 1
174
+
175
+ result = dotmatch.assign_posterior("ACGT", ["ACGT", "AGGT"], "IIII")
176
+ print(result.status)
177
+ ```
178
+
179
+ The posterior helper is experimental and is not used by the high-throughput
180
+ CLI path. The [Python API documentation](https://dotmatch.readthedocs.io/en/latest/streaming-api.html)
181
+ describes the supported streaming interfaces.
182
+
183
+ ## Outputs and workflow integration
184
+
185
+ Depending on the command, DotMatch writes count tables, split FASTQs,
186
+ `sample_qc.tsv`, per-read assignments, unmatched-read tables, `summary.json`,
187
+ and self-contained HTML reports. The formats are documented in the
188
+ [output schema reference](https://dotmatch.readthedocs.io/en/latest/schemas.html).
189
+
190
+ Examples for Nextflow, nf-core, Snakemake, Galaxy, and MultiQC live under
191
+ [`examples/workflows`](https://github.com/dnncha/dotmatch/tree/main/examples/workflows).
192
+ The desktop Workbench is maintained separately in
193
+ [`dotmatch-community`](https://github.com/dnncha/dotmatch-community).
194
+
195
+ ## Matching rules and performance
196
+
197
+ Hamming distance is the usual choice for fixed-length windows where only base
198
+ substitutions should be considered. Levenshtein distance can also account for
199
+ short insertions and deletions. The default radius policy requires a single
200
+ compatible target; the optional `best` policy exists for compatibility with
201
+ workflows that select the nearest target.
202
+
203
+ Indexed candidate generation and native distance kernels make fixed-window
204
+ assignment practical for large FASTQ inputs. Benchmark results, hardware,
205
+ commands, and known limitations are kept with the
206
+ [benchmark reports](https://dotmatch.readthedocs.io/en/latest/benchmarks/README.html).
207
+ Those reports cover the tested workloads; they are not a claim that DotMatch
208
+ replaces general alignment or every demultiplexing workflow.
209
+
210
+ ## Documentation
211
+
212
+ - [Getting started](https://dotmatch.readthedocs.io/en/latest/getting-started.html)
213
+ - [Command reference](https://dotmatch.readthedocs.io/en/latest/command-reference.html)
214
+ - [AssaySpec workflows](https://dotmatch.readthedocs.io/en/latest/assayspec.html)
215
+ - [CRISPR count QC](https://dotmatch.readthedocs.io/en/latest/crispr-qc.html)
216
+ - [Barcode panel design](https://dotmatch.readthedocs.io/en/latest/barcode-panel-design.html)
217
+ - [Output schemas](https://dotmatch.readthedocs.io/en/latest/schemas.html)
218
+ - [Methods and citation](https://dotmatch.readthedocs.io/en/latest/methods-and-citation.html)
219
+ - [Packaging notes](https://dotmatch.readthedocs.io/en/latest/packaging.html)
220
+
221
+ ## Citation
222
+
223
+ Run `dotmatch citation` to print the citation for the installed version. The
224
+ repository also includes [`CITATION.cff`](https://github.com/dnncha/dotmatch/blob/main/CITATION.cff),
225
+ and release archives are deposited with Zenodo.
226
+
227
+ ## Development
228
+
229
+ ```bash
230
+ git clone https://github.com/dnncha/dotmatch.git
231
+ cd dotmatch
232
+ make
233
+ make test
234
+ ```
235
+
236
+ See [CONTRIBUTING.md](https://github.com/dnncha/dotmatch/blob/main/CONTRIBUTING.md)
237
+ for the development setup and pull-request checks.
238
+
239
+ ## License
240
+
241
+ Apache-2.0. See [LICENSE](https://github.com/dnncha/dotmatch/blob/main/LICENSE).
@@ -2,15 +2,15 @@
2
2
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
3
3
  "@type": "SoftwareSourceCode",
4
4
  "name": "DotMatch",
5
- "description": "Deterministic short-DNA known-target matching and QC for CRISPR guides, barcodes, primers, panels, and whitelist-style target sets.",
5
+ "description": "Assign short FASTQ read windows to known CRISPR guides, barcodes, feature tags, primers, and other DNA targets.",
6
6
  "applicationCategory": "Bioinformatics",
7
7
  "url": "https://github.com/dnncha/dotmatch",
8
8
  "codeRepository": "https://github.com/dnncha/dotmatch",
9
9
  "issueTracker": "https://github.com/dnncha/dotmatch/issues",
10
10
  "license": "https://spdx.org/licenses/Apache-2.0",
11
11
  "identifier": "https://doi.org/10.5281/zenodo.20541628",
12
- "version": "0.2.0",
13
- "softwareVersion": "0.2.0",
12
+ "version": "0.2.2",
13
+ "softwareVersion": "0.2.2",
14
14
  "programmingLanguage": [
15
15
  "C",
16
16
  "Python",
@@ -43,6 +43,6 @@
43
43
  "Python >=3.9",
44
44
  "zlib"
45
45
  ],
46
- "readme": "https://dotmatch.readthedocs.io/",
46
+ "readme": "https://dotmatch.readthedocs.io/en/latest/",
47
47
  "citation": "https://github.com/dnncha/dotmatch/blob/main/CITATION.cff"
48
48
  }
@@ -7,7 +7,7 @@
7
7
  extern "C" {
8
8
  #endif
9
9
 
10
- #define QDALN_VERSION "0.2.0"
10
+ #define QDALN_VERSION "0.2.2"
11
11
  #define QDALN_ALPHABET_POLICY "literal-byte; A/C/G/T/N/IUPAC symbols are ordinary byte symbols; no wildcard expansion"
12
12
 
13
13
  enum qdaln_match_status {
@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "dotmatch"
7
- version = "0.2.0"
8
- description = "AssayCode workflows and the DotMatch engine for auditable known-target short-DNA assignment across CRISPR, barcode, and FASTQ assays"
7
+ version = "0.2.2"
8
+ description = "Known-target short-DNA assignment from FASTQ for CRISPR guides, barcodes, feature tags, primers, and other targets"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.9"
11
11
  dependencies = [
@@ -22,8 +22,8 @@ keywords = [
22
22
  "CRISPR",
23
23
  "FASTQ",
24
24
  "known-target assignment",
25
- "assay compiler",
26
- "assay QC",
25
+ "feature barcodes",
26
+ "sequencing QC",
27
27
  "barcode demultiplexing",
28
28
  "edit distance",
29
29
  ]
@@ -49,10 +49,11 @@ multiqc = ["multiqc>=1.20"]
49
49
  dev = ["pytest", "pandas>=1.0", "anndata>=0.8", "polars>=0.19", "multiqc>=1.20"]
50
50
 
51
51
  [project.urls]
52
- Homepage = "https://github.com/dnncha/dotmatch"
52
+ Homepage = "https://dnncha.github.io/dotmatch/"
53
53
  Repository = "https://github.com/dnncha/dotmatch"
54
54
  Issues = "https://github.com/dnncha/dotmatch/issues"
55
- Documentation = "https://dotmatch.readthedocs.io/"
55
+ Documentation = "https://dotmatch.readthedocs.io/en/latest/"
56
+ Changelog = "https://github.com/dnncha/dotmatch/blob/main/CHANGELOG.md"
56
57
 
57
58
  [tool.setuptools]
58
59
  package-dir = {"" = "python"}
@@ -52,7 +52,7 @@ def _source_tree_version() -> Optional[str]:
52
52
  try:
53
53
  __version__ = _source_tree_version() or _metadata_version("dotmatch")
54
54
  except PackageNotFoundError:
55
- __version__ = "0.2.0"
55
+ __version__ = "0.2.2"
56
56
 
57
57
  __all__ = [
58
58
  "__version__",