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.
- {dotmatch-0.2.0 → dotmatch-0.2.2}/CITATION.cff +1 -2
- dotmatch-0.2.2/PKG-INFO +285 -0
- dotmatch-0.2.2/README.md +241 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/codemeta.json +4 -4
- {dotmatch-0.2.0 → dotmatch-0.2.2}/include/qdalign.h +1 -1
- {dotmatch-0.2.0 → dotmatch-0.2.2}/pyproject.toml +7 -6
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/__init__.py +1 -1
- dotmatch-0.2.2/python/dotmatch.egg-info/PKG-INFO +285 -0
- dotmatch-0.2.0/PKG-INFO +0 -898
- dotmatch-0.2.0/README.md +0 -855
- dotmatch-0.2.0/python/dotmatch.egg-info/PKG-INFO +0 -898
- {dotmatch-0.2.0 → dotmatch-0.2.2}/LICENSE +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/MANIFEST.in +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/docs/assay-evidence.json +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/include/qdmetal.h +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/assaycode/__init__.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/assaycode/cli.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/assayruntime.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/assayscript.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/assaysim.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/assayspec.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/assaywatch.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/calibration.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/calibration_io.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/cli.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/core.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/multiqc.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/native.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/panel.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch/tl.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch.egg-info/SOURCES.txt +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch.egg-info/dependency_links.txt +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch.egg-info/entry_points.txt +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch.egg-info/requires.txt +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/dotmatch.egg-info/top_level.txt +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/quickdna/__init__.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/python/quickdna/core.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/setup.cfg +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/setup.py +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/src/qda.c +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/src/qdalign.c +0 -0
- {dotmatch-0.2.0 → dotmatch-0.2.2}/src/qdmetal.mm +0 -0
- {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.
|
|
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
|
dotmatch-0.2.2/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://github.com/dnncha/dotmatch/actions/workflows/ci.yml)
|
|
53
|
+
[](https://pypi.org/project/dotmatch/)
|
|
54
|
+
[](https://dotmatch.readthedocs.io/en/latest/)
|
|
55
|
+
[](https://anaconda.org/bioconda/dotmatch)
|
|
56
|
+
[](https://github.com/dnncha/dotmatch/blob/main/LICENSE)
|
|
57
|
+
[](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
|
+

|
|
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).
|
dotmatch-0.2.2/README.md
ADDED
|
@@ -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
|
+
[](https://github.com/dnncha/dotmatch/actions/workflows/ci.yml)
|
|
9
|
+
[](https://pypi.org/project/dotmatch/)
|
|
10
|
+
[](https://dotmatch.readthedocs.io/en/latest/)
|
|
11
|
+
[](https://anaconda.org/bioconda/dotmatch)
|
|
12
|
+
[](https://github.com/dnncha/dotmatch/blob/main/LICENSE)
|
|
13
|
+
[](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
|
+

|
|
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": "
|
|
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.
|
|
13
|
-
"softwareVersion": "0.2.
|
|
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
|
}
|
|
@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "dotmatch"
|
|
7
|
-
version = "0.2.
|
|
8
|
-
description = "
|
|
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
|
-
"
|
|
26
|
-
"
|
|
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.
|
|
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"}
|