barcadia 3.2.0__py3-none-any.whl

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.
@@ -0,0 +1,466 @@
1
+ Metadata-Version: 2.4
2
+ Name: barcadia
3
+ Version: 3.2.0
4
+ Summary: A high-performance, memory-efficient toolkit for fast generation and validation of large-scale NGS barcodes
5
+ Author: Danting Jiang
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Repository, https://github.com/danting/barcadia
8
+ Project-URL: PyPI, https://pypi.org/project/barcadia/
9
+ Keywords: bioinformatics,NGS,barcodes
10
+ Classifier: Development Status :: 5 - Production/Stable
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
13
+ Classifier: Environment :: Console
14
+ Classifier: Programming Language :: Python :: 3 :: Only
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Operating System :: POSIX :: Linux
17
+ Classifier: Operating System :: MacOS :: MacOS X
18
+ Classifier: Natural Language :: English
19
+ Requires-Python: >=3.12
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: numpy==2.2.6
23
+ Requires-Dist: numba==0.61.2
24
+ Requires-Dist: llvmlite==0.44.0
25
+ Requires-Dist: psutil==7.0.0
26
+ Dynamic: license-file
27
+
28
+ # Barcadia (v3.2.0)
29
+ *Best-in-class toolkit for large-scale NGS barcode generation and validation*
30
+
31
+ ![version](https://img.shields.io/badge/version-3.2.0-blue)
32
+ ![license](https://img.shields.io/badge/license-Apache%202.0-brightgreen)
33
+ ![platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-lightgrey)
34
+
35
+ ---
36
+
37
+ Barcadia is a **fast, memory-efficient, open-source toolkit** for generating and validating massive DNA barcode libraries for next-generation sequencing (NGS) applications. Designed for speed and scalability, it **outperforms existing tools** for both small- and large-scale operations.
38
+
39
+ - **High performance & scalability** – Generates 100K barcodes in under 3 minutes and 1M in 40 minutes, largely outperforming existing tools limited to ~100K barcodes and requiring hours of compute.
40
+ - **Memory & compute efficient** – Runs on standard laptops with minimal resources (under 1 GB RAM used for generating 1M barcodes); no multi-core processing required.
41
+ - **Extended functionality** – Supports paired barcode generation for dual-indexing, extension from seed lists, validation of existing barcode sets, and estimation of library size limits — features not found in other tools.
42
+
43
+ Barcadia makes it easy to design small or large NGS barcode sets that are optimized for **robust performance in high-throughput sequencing workflows**.
44
+
45
+ ## Table of Contents
46
+ - [Background](#background)
47
+ - [Problem Statement](#problem-statement)
48
+ - [Existing Methods and their Limitations](#existing-methods-and-their-limitations)
49
+ - [This Toolkit and its Advantages](#this-toolkit-and-its-advantages)
50
+ - [Default Filter Parameters](#default-filter-parameters)
51
+ - [Theoretical Bounds](#theoretical-bounds)
52
+ - [Benchmarking Highlights](#benchmarking-highlights)
53
+ - [Installation](#installation)
54
+ - [Setup](#setup)
55
+ - [Requirements](#requirements)
56
+ - [Quick Start](#quick-start)
57
+ - [Package Overview](#package-overview)
58
+ - [Project Structure](#project-structure)
59
+ - [Main Commands](#main-commands)
60
+ - [Shared Modules](#shared-modules)
61
+ - [Utility Scripts](#utility-scripts)
62
+ - [Citation](#citation)
63
+ - [Changelog](#changelog)
64
+
65
+ ## Background
66
+
67
+ ### Problem Statement
68
+
69
+ **Next-generation sequencing (NGS) is a high-throughput method that enables millions of DNA fragments to be sequenced in parallel, serving as the core technology for decoding genomes across all living organisms**. In this process, researchers use DNA barcodes to uniquely label and track individual biomolecules. Common examples include multiplex sample indexes and unique molecular identifiers (UMIs).
70
+
71
+ The practical utility of a DNA barcode library depends on controlling key features: **GC content** (the percentage of G and C nucleotides), **homopolymer repeats** (the length of the longest stretch of identical nucleotides), and **edit distance** (the measure of dissimilarity among sequences). GC content and homopolymer repeats are **within-sequence** criteria that ensure molecular stability during sequencing and are computationally inexpensive to evaluate. **In contrast, edit distance is a between-sequence constraint that provides error tolerance during analysis, but is computationally demanding to assess for large datasets**.
72
+
73
+ ### Existing Methods and their Limitations
74
+
75
+ For a set of n sequences, the number of pairwise distance comparisons grows quadratically:
76
+
77
+ $$\binom{n}{2} = \frac{n(n-1)}{2}$$
78
+
79
+ **This makes brute-force approaches computationally prohibitive for large datasets**. Apart from the approach described by [Lyons et al. (2017)](https://www.nature.com/articles/s41598-017-12825-2), existing tools are not built to accommodate large-scale barcode library design (≥100K sequences). Lyons et al. circumvented computational limitations using a probabilistic Markov chain model; however, their resulting barcode sets are no longer accessible (invalid URLs in the paper), and the underlying code was not released (likely due to proprietary restrictions).
80
+
81
+ ### This Toolkit and its Advantages
82
+
83
+ **Here, I introduce Barcadia, a toolkit for efficient large-scale NGS barcode generation that integrates modern computational optimization with novel distance-constrained algorithms I developed to deliver best-in-class scalability and speed**. The software is openly available to promote reproducibility and is designed to run efficiently on minimal computing resources (e.g., standard laptops), ensuring broad accessibility.
84
+
85
+ In comparison with [TagGD](https://doi.org/10.1371/journal.pone.0057521)—the only other open-source software reported to support barcode generation at the scale of up to 100,000 sequences—Barcadia generated 20,000 18-bp barcodes in just **1 minute** using only 100 MB of RAM on a comparable 8-core laptop, as opposed to the **5 minutes** highlighted in the TagGD abstract. For 100,000 18-bp barcodes, Barcadia completed the process in **under 5 minutes** with 180 MB of RAM, which is significantly faster than the **1.5 hours** reported in Table 1 of the TagGD paper.
86
+
87
+ **Notably, Barcadia can handle the generation of million-scale barcodes within reasonable time (i.e., 40 minutes) on minimal compute setups (e.g., standard laptops; <1 GB RAM and no multi-core processing required), far exceeding the capacity of TagGD and other existing tools**. More detailed benchmarking results are presented in a later section of this document.
88
+
89
+ **Additionally, it offers unique features not found in other tools**: paired barcode generation for dual-indexing applications, extension from user-provided seed sequences, and a comprehensive validation script for assessing the quality of existing barcode sets (which together enable the estimation of realistic bounds for achievable library sizes under all specified constraints).
90
+
91
+ ## Default Filter Parameters
92
+
93
+ Barcadia uses carefully chosen default parameters that **optimize synthetic stability and sequencing reliability** in NGS workflows. Users can configure these based on their specific needs.
94
+
95
+ ### GC Content: 40-60%
96
+ - **Rationale**: Sequences with extreme GC content (very low or very high) can form secondary structures and exhibit poor amplification efficiency during PCR
97
+ - **Impact**: Moderate GC content ensures reliable sequencing performance across different platforms
98
+
99
+ ### Maximum Homopolymer Length: 2
100
+ - **Rationale**: Long homopolymer runs (e.g., AAAA, TTTT) cause sequencing errors on most NGS platforms, particularly Illumina and Ion Torrent
101
+ - **Impact**: Short homopolymers prevent read quality degradation and reduce sequencing artifacts
102
+
103
+ ### Minimum Hamming Distance: 3
104
+ - **Rationale**: Distance ≥3 allows correction of single-base sequencing errors while maintaining sequence distinguishability
105
+ - **Impact**: Provides error tolerance for typical NGS error rates (~0.1-1% per base)
106
+
107
+ ## Theoretical Bounds
108
+
109
+ Leveraging established results from coding theory, **one can calculate lower and upper bounds on the number of valid barcode sequences under specified edit distance constraints**, assuming equal-length barcodes and applying the Hamming distance metric, which counts the base-pair mismatches.
110
+
111
+ ### Gilbert-Varshamov Bound (Lower Bound)
112
+
113
+ The Gilbert-Varshamov bound provides a lower bound guarantee that a code of at least this size exists. For DNA sequences (i.e., alphabet of 4 characters: A, T, G, C), it states:
114
+
115
+ $$M \geq \frac{4^n}{V(n,d-1)}$$
116
+
117
+ where `V(n,d-1)` is the volume of a Hamming sphere of radius `d-1`:
118
+
119
+ $$V(n,d-1) = \sum_{i=0}^{d-1} \binom{n}{i} \cdot 3^i$$
120
+
121
+ ### Hamming Bound (Upper Bound)
122
+
123
+ The Hamming bound provides the theoretical maximum number of codewords that can exist for a given sequence length and minimum distance constraint. For DNA sequences of length `n` with minimum Hamming distance `d`, the bound is:
124
+
125
+ $$M \leq \frac{4^n}{V(n,t)}$$
126
+
127
+ where `t = ⌊(d-1)/2⌋` and `V(n,t)` is the volume of a Hamming sphere of radius `t`:
128
+
129
+ $$V(n,t) = \sum_{i=0}^{t} \binom{n}{i} \cdot 3^i$$
130
+
131
+ **As the sequence space is exhausted in search of valid barcodes, approaching the theoretical upper bound causes the search to slow down progressively**. In particular, a significant—often exponential—slowdown can be expected once the target size surpasses the Gilbert-Varshamov (GV) bound.
132
+
133
+ For typical barcode applications (6-16 bp, as longer sequences may introduce molecular complexity) using the default minimum distance of 3, the theoretical bounds are summarized below:
134
+
135
+ <div align="center">
136
+
137
+ | Length (bp) | GV Bound (Lower) | Hamming Bound (Upper) |
138
+ |:-----------:|:----------------:|:---------------------:|
139
+ | 6 | 26 | 215 |
140
+ | 7 | 77 | 744 |
141
+ | 8 | 236 | 2.6K |
142
+ | 9 | 744 | 9.4K |
143
+ | 10 | 2.4K | 34K |
144
+ | 11 | 7.9K | 123K |
145
+ | 12 | 27K | 453K |
146
+ | 13 | 90K | 1.7M |
147
+ | 14 | 311K | 6.2M |
148
+ | 15 | 1.1M | 23M |
149
+ | 16 | 3.8M | 88M |
150
+
151
+ </div>
152
+
153
+ When no seeds are provided—or when all provided seeds are the same length as the new barcodes to generate—**Barcadia will automatically calculate and display the theoretical bounds**. For the specified barcode length and minimum distance, it issues a warning if the requested count exceeds the GV lower bound (performance slowdown expected), or raises an error if the request is beyond the Hamming upper bound (not achievable).
154
+
155
+ However, these theoretical bounds only capture the minimum distance constraints. **In practice, within-sequence biological filters (GC content and homopolymer restrictions) will further reduce the achievable library size**. Notably, Barcadia can be used to estimate more realistic bounds that account for all three constraints, following the procedures outlined below:
156
+
157
+ 1. **Generate sequences with only distance constraints** (no biological filters):
158
+ ```bash
159
+ barcadia generate --count <large_number> --length <your_length> --gc-min 0 --gc-max 1 --homopolymer-max <your_length> --output-dir <your_output_dir>
160
+ ```
161
+ *Note: Use a count near the GV bound for your parameters, and set homopolymer-max to your barcode length. This overrides the default biological filters (gc-min=0.4, gc-max=0.6, homopolymer-max=2).*
162
+
163
+ 2. **Check how many pass biological filters** (skipping distance validation):
164
+ ```bash
165
+ barcadia validate --input <your_output_dir>/barcodes.txt --skip-distance --output-dir <your_output_dir>
166
+ ```
167
+ *Note: By default, this validation step uses the biological filters (gc-min=0.4, gc-max=0.6, homopolymer-max=2) to check how many sequences pass. You can also set custom filter values if desired.*
168
+
169
+ 3. **Calculate empirical bounds**: Multiply the theoretical bounds by the observed pass rate from step 2 to get realistic achievable library sizes under all constraints.
170
+
171
+ ## Benchmarking Highlights
172
+
173
+ Below are performance benchmarks for **barcode generation** on a MacBook Pro 2019 (8-core, 16GB RAM) using default parameters with target sizes near the Gilbert-Varshamov bound (generating equal-length libraries from scratch without seed sequences provided):
174
+
175
+ <div align="center">
176
+
177
+ | Length (bp) | Library Size | Time (Peak Memory) |
178
+ |:-----------:|:------------:|:---------------------:|
179
+ | 6 | 10 | 0.2 seconds (82 MB) |
180
+ | 8 | 100 | 0.2 seconds (82 MB) |
181
+ | 10 | 1,000 | 0.6 seconds (82 MB) |
182
+ | 12 | 10,000 | 12.3 seconds (88 MB) |
183
+ | 14 | 100,000 | 2.8 minutes (160 MB) |
184
+ | 16 | 1,000,000 | 40 minutes (950 MB) |
185
+
186
+ </div>
187
+
188
+ Below are performance benchmarks for **barcode validation** on a MacBook Pro 2019 (8-core, 16GB RAM) using default parameters with pool sizes near the Gilbert-Varshamov bound (validating barcodes that pass all the within-sequence and between-sequence filters):
189
+
190
+ <div align="center">
191
+
192
+ | Length (bp) | Library Size | Time (Peak Memory) |
193
+ |:-----------:|:------------:|:---------------------:|
194
+ | 6 | 10 | 0.2 seconds (81 MB) |
195
+ | 8 | 100 | 0.2 seconds (81 MB) |
196
+ | 10 | 1,000 | 0.5 seconds (81 MB) |
197
+ | 12 | 10,000 | 6.1 seconds (88 MB) |
198
+ | 14 | 100,000 | 1.5 minutes (160 MB) |
199
+ | 16 | 1,000,000 | 20 minutes (943 MB) |
200
+
201
+ </div>
202
+
203
+ ## Installation
204
+
205
+ ### Setup
206
+
207
+ #### Method 1: Install from PyPI (Recommended)
208
+ ```bash
209
+ pip install barcadia
210
+ ```
211
+
212
+ #### Method 2: Install from Source (Development)
213
+ ```bash
214
+ git clone https://github.com/danting/barcadia.git
215
+ cd barcadia
216
+ pip install -e .
217
+ ```
218
+
219
+ ### Requirements
220
+ - Python 3.12+
221
+ - Dependencies (automatically installed):
222
+ - numpy==2.2.6
223
+ - numba==0.61.2 (for JIT compilation acceleration)
224
+ - llvmlite==0.44.0
225
+ - psutil==7.0.0
226
+
227
+ This installs Barcadia as a Python package with the `barcadia` command-line tool.
228
+
229
+ ## Quick Start
230
+
231
+ ```bash
232
+ # Generate 1000 barcodes of length 12
233
+ barcadia generate --count 1000 --length 12
234
+
235
+ # Validate existing barcodes
236
+ barcadia validate --input test/barcodes.txt
237
+
238
+ # Check version
239
+ barcadia --version
240
+
241
+ # Get help for any command
242
+ barcadia --help
243
+ barcadia generate --help
244
+ barcadia validate --help
245
+ ```
246
+
247
+ ## Package Overview
248
+
249
+ ### Project Structure
250
+
251
+ ```
252
+ barcadia/ # Main package
253
+ ├── __init__.py # Public API
254
+ ├── cli.py # Command-line interface
255
+ ├── generate_barcodes.py # Barcode generation
256
+ ├── validate_barcodes.py # Barcode validation
257
+ ├── config_utils.py # Configuration utilities
258
+ ├── filter_utils.py # Core filtering utilities
259
+ └── tools/ # Utility scripts
260
+ ├── generate_random_sequences.py # Random sequence generator
261
+ └── memory_benchmark.py # Performance monitoring
262
+ ```
263
+
264
+ ### Main Commands
265
+
266
+ #### 1. `barcadia generate` - Barcode Generation
267
+
268
+ **Purpose**: Generate high-performance NGS barcodes efficiently using a novel iterative growth algorithm (extension from seeds and paired mode supported).
269
+
270
+ **Algorithm Overview**:
271
+ 1. Load seed sequence files as existing pool and report length distribution (will generate from scratch if no seeds are provided)
272
+ 2. Generate a batch of unique random sequence candidates passing biological filters (GC content, homopolymer repeats)
273
+ 3. **Two-step distance filtering with adaptive method selection (neighbor enumeration or pairwise)**:
274
+ - Filter candidates against existing pool (if pairwise, parallelized for large sets when multiple CPUs available)
275
+ - Filter remaining candidates against each other within the current batch (always sequential)
276
+ 4. Add verified batch of passing candidates to existing pool and repeat until target count reached
277
+
278
+ **Key Features**:
279
+ - Uses Hamming distance for generation when no seeds are provided (always equal-length)
280
+ - Supports **extension from seed sequence** file(s) (when `--seeds` is specified) and can accommodate:
281
+ - Multiple seed files of equal or variable lengths (concatenated automatically as seed pool)
282
+ - Differences in lengths between seed pool and newly-generated sequences (NOTE: new sequences are always the same length as specified by `--length`)
283
+ - Uses Hamming distance for equal-length comparisons, Levenshtein distance for mixed lengths (compared to seed pool)
284
+ - Incompatible with `--paired` mode
285
+ - Supports **paired barcode generation** (when `--paired` flag is on) by generating 2x the target count and splitting output into 2 files with suffixes `_paired1.txt` and `_paired2.txt`
286
+ - Supports paired barcode generation with **paired seed** files (when`--paired-seed1` and `--paired-seed2` are specified), but is more restrictive than `--seeds` in unpaired mode:
287
+ - Only accepts one file each and both must be specified
288
+ - Both files must have the same number of sequences with all sequences being the same length within and across both files
289
+ - Similar to `--seeds`, can accommodate differences in lengths between seed pool and newly-generated sequences (Hamming for equal/Levenshtein for mixed)
290
+ - Incompatible with `--seeds`
291
+ - **Adaptive method selection for distance filtering**:
292
+ - Small barcode sets (<10K sequences including seeds): Pairwise distance checking (fast for small sets)
293
+ - Large mixed-length (within seeds and/or between seeds and new barcodes): Pairwise distance checking (neighbor enumeration requires complex Levenshtein handling)
294
+ - Large equal-length (no seeds or everything equal-length): Choose between pairwise and neighbor enumeration based on min_distance
295
+ * Pairwise distance checking: when min_distance > 4 (large number of neighbors to check)
296
+ * Neighbor enumeration: when min_distance <= 4 (limited number of neighbors to check)
297
+
298
+ **Basic Usage**:
299
+ ```bash
300
+ # Generate 1000 barcodes of length 12 from scratch (no seeds)
301
+ barcadia generate --count 1000 --length 12
302
+
303
+ # Build from a seed sequence file
304
+ barcadia generate --count 1000 --length 12 --seeds seed.txt
305
+
306
+ # Build from multiple seed sequence files (concatenated automatically)
307
+ barcadia generate --count 1000 --length 12 --seeds seed_file1.txt seed_file2.txt
308
+
309
+ # Generate paired barcodes from scratch (no seeds)
310
+ barcadia generate --count 1000 --length 12 --paired
311
+
312
+ # Generate paired barcodes with paired seed files
313
+ barcadia generate --count 1000 --length 12 --paired --paired-seed1 seed_paired1.txt --paired-seed2 seed_paired2.txt
314
+ ```
315
+
316
+ **Required Arguments**:
317
+ - `--count`: Number of barcodes or barcode pairs to generate
318
+ - `--length`: Length of barcodes or barcode pairs to generate
319
+
320
+ **Optional Arguments**:
321
+ - `--gc-min`: Minimum GC content (default: 0.4)
322
+ - `--gc-max`: Maximum GC content (default: 0.6)
323
+ - `--homopolymer-max`: Maximum homopolymer repeat length (default: 2)
324
+ - `--min-distance`: Minimum edit distance between sequences (default: 3)
325
+ - `--cpus`: Number of CPU cores to use during the parallel filtering step (default: all available)
326
+ - `--seeds`: Seed sequence files (any number of files, one sequence per line as .txt; if not provided, will generate from scratch; incompatible with --paired mode; default: None)
327
+ - `--paired`: Generate paired barcodes (doubles target count, splits output randomly into two equal parts; incompatible with --seeds; default: off)
328
+ - `--paired-seed1`: Paired seed sequence file 1 (used only with --paired and --paired-seed2, only one file is accepted, all sequences must be same length and match count/length of --paired-seed2; default: None)
329
+ - `--paired-seed2`: Paired seed sequence file 2 (used only with --paired and --paired-seed1, only one file is accepted, all sequences must be same length and match count/length of --paired-seed1; default: None)
330
+
331
+ - `--output-dir`: Output directory (default: test)
332
+ - `--output-prefix`: Output filename prefix (default: barcodes)
333
+
334
+ **Output Files**:
335
+ - `{prefix}.txt` or `{prefix}_paired1.txt` & `{prefix}_paired2.txt`: Generated barcodes
336
+ - `generate_barcodes_{timestamp}.log`: Detailed generation log
337
+
338
+ **Important Notes**:
339
+ - **Seed sequences are not validated**: If using seed files (paired or unpaired), run `barcadia validate` first to ensure they pass all filters
340
+ - In paired mode with seeds, both `--paired-seed1` and `--paired-seed2` must be provided and have the same count/length
341
+ - Seeds are preserved in the output files (paired or unpaired)
342
+
343
+ ---
344
+
345
+ #### 2. `barcadia validate` - Barcode Validation
346
+
347
+ **Purpose**: Validate existing barcode lists against quality filters with support for variable-length sequences.
348
+
349
+ **Algorithm Overview**:
350
+ 1. Load and parse input file(s) and report lengths distribution
351
+ 2. Check if sequences fail both biological filters (GC content, homopolymer repeats)
352
+ 3. **Computational complexity-optimized distance validation**:
353
+ - **Method selection**: Automatically chooses optimal validation approach based on barcode set and distance filter characteristics
354
+ - **Early stopping**: Terminates on first violation found (prevents unnecessary computation)
355
+ 4. Generate detailed validation report with comprehensive violation details
356
+
357
+ **Key Features**:
358
+ - Supports multiple input files (automatically concatenated) with variable lengths
359
+ - Uses Hamming distance for equal-length sequences, Levenshtein for mixed lengths (for sequences passing biological filters)
360
+ - **Adaptive method selection for distance validation**:
361
+ - Small barcode sets (<10K sequences): Sequential pairwise validation
362
+ - Large barcode sets (≥10K sequences) with mixed lengths and/or min_distance > 4: Parallel pairwise validation (when multiple CPUs available)
363
+ - Large equal-length barcode sets (≥10K sequences) with min_distance ≤ 4: Neighbor enumeration
364
+ - Early stopping on first violation
365
+ - Can be skipped when `--skip-distance` flag is on
366
+ - Comprehensive reporting with violation cases (for both biological and distance constraints)
367
+
368
+ **Basic Usage**:
369
+ ```bash
370
+ # Validate a single file
371
+ barcadia validate --input test/barcodes.txt
372
+
373
+ # Validate multiple files (automatically concatenated)
374
+ barcadia validate --input file1.txt file2.txt file3.txt
375
+
376
+ # Skip distance validation entirely (biological filters only)
377
+ barcadia validate --input test/barcodes.txt --skip-distance
378
+ ```
379
+
380
+ **Required Arguments**:
381
+ - `--input`: Input file(s) containing DNA barcodes (one per line)
382
+
383
+ **Optional Arguments**:
384
+ - `--gc-min`: Minimum GC content (default: 0.4)
385
+ - `--gc-max`: Maximum GC content (default: 0.6)
386
+ - `--homopolymer-max`: Maximum homopolymer repeat length (default: 2)
387
+ - `--min-distance`: Minimum edit distance between sequences (default: 3)
388
+ - `--skip-distance`: Skip distance validation entirely (default: off)
389
+ - `--cpus`: Number of CPUs for pairwise parallel validation (default: all available)
390
+ - `--output-dir`: Output directory for logs and reports (default: test)
391
+
392
+ **Output Files**:
393
+ - `validation_report_{timestamp}.txt`: Detailed validation report
394
+ - `validate_barcodes_{timestamp}.log`: Validation process log
395
+
396
+ ---
397
+
398
+ ### Shared Modules
399
+
400
+ #### `config_utils.py`
401
+ Configuration utilities and DNA encoding/decoding:
402
+ - DNA bases encoded as 0-3 integers (A=0, T=1, G=2, C=3) for enhanced efficiency
403
+ - Convert between DNA strings and integer arrays for optimized processing
404
+ - Logging setup and file reading utilities (ExistingSequenceSet class)
405
+
406
+ #### `filter_utils.py`
407
+ High-performance filtering algorithms with Numba JIT compilation:
408
+ - Simple validation on filter arguments (GC content, homopolymer, min-distance)
409
+ - GC content and homopolymer repeat filtering with early stopping
410
+ - Hamming distance for equal-length sequences with early stopping
411
+ - Levenshtein distance for variable-length sequences with early stopping
412
+ - Adaptive method selection between pairwise and neighbor enumeration approaches
413
+ - Neighbor enumeration for efficient distance constraint checking
414
+
415
+ ### Utility Scripts
416
+
417
+ #### 1. `generate_random_sequences.py` - Test Data Generation
418
+
419
+ **Purpose**: Generate random DNA sequences for testing validation scripts.
420
+
421
+ **Usage**:
422
+ ```bash
423
+ python -m barcadia.tools.generate_random_sequences --count <num> --lengths <length1> [length2...] [--output <file>]
424
+ ```
425
+
426
+ **Output**: Auto-generated filename in `test/` directory based on `count` and `length` if `--output` not specified.
427
+
428
+ ---
429
+
430
+ #### 2. `memory_benchmark.py` - Performance Monitoring
431
+
432
+ **Purpose**: Monitor memory usage and performance of the main scripts.
433
+
434
+ **Usage**:
435
+ ```bash
436
+ # General usage
437
+ python -m barcadia.tools.memory_benchmark [--mem-output-dir <dir>] <command> [args...]
438
+
439
+ # Examples
440
+ python -m barcadia.tools.memory_benchmark barcadia generate --args
441
+ python -m barcadia.tools.memory_benchmark barcadia validate --args
442
+ ```
443
+
444
+ **Output**: Memory usage report with peak memory consumption and execution time. Log saved to specified directory (default: `test/`).
445
+
446
+ ## Citation
447
+
448
+ If you use Barcadia in your research, please cite:
449
+
450
+ ```bibtex
451
+ @software{barcadia2025,
452
+ title={Barcadia: a high-performance, memory-efficient toolkit for fast generation and validation of large-scale NGS barcodes},
453
+ author={Jiang, Danting},
454
+ year={2025},
455
+ date={2025-09-12},
456
+ url={https://pypi.org/project/barcadia/},
457
+ note={Code repository: https://github.com/danting/barcadia},
458
+ version={3.2.0}
459
+ }
460
+ ```
461
+
462
+ A preprint will be posted soon. Citation information will be updated with a DOI once available.
463
+
464
+ ## Changelog
465
+
466
+ See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
@@ -0,0 +1,14 @@
1
+ barcadia/__init__.py,sha256=A1BaAko0niRWfqnNaYJSBJLqtuspY0r7qnHwp6-9E7s,697
2
+ barcadia/cli.py,sha256=DgtFb7gdmR5ggY8A6kPfFfpHy7B8XC5mTnrehBgpooU,1864
3
+ barcadia/config_utils.py,sha256=CfJvSjsGHxTcSew1aNkpAjEzkYQ54GyCZQYqUxP8j9w,8757
4
+ barcadia/filter_utils.py,sha256=QPIVbXJfBBn3cO3X_gSq10Je35hDdkK9GZMKzHC3hvI,6553
5
+ barcadia/generate_barcodes.py,sha256=V1ry3zNbpCt9whNTmw-2rjCeX7bANUIQmT8ZGokuw54,31499
6
+ barcadia/validate_barcodes.py,sha256=lxoJFINU2V26Hl1R7lB0QsmsLJsmTr6iKWjycy_qaoc,18215
7
+ barcadia/tools/generate_random_sequences.py,sha256=gfo69qgyA0M186nwk7j9xfH6dTXXuBfExznJt_WH5rU,3721
8
+ barcadia/tools/memory_benchmark.py,sha256=BtG4YN4M2aXZbzp6fi_mu7TISKm9ayxEhhukLhBLSnM,4699
9
+ barcadia-3.2.0.dist-info/licenses/LICENSE,sha256=nNChwEt8KgkqiCgNEzhIizDyZYImrfMAqNnuXukmt-Y,11344
10
+ barcadia-3.2.0.dist-info/METADATA,sha256=3TaZ2aOkipmjQa307Yq3D1-NYm4FB4ZeqPipPPXJl3g,25629
11
+ barcadia-3.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
12
+ barcadia-3.2.0.dist-info/entry_points.txt,sha256=JEHBM8E3wpBYhYiwjfSglzhKZApiR52xO57Fy9RhQqI,47
13
+ barcadia-3.2.0.dist-info/top_level.txt,sha256=3-Qgyc37l1w4uXq69KskFG9AU6b1jxda5HrgWZp6FCA,9
14
+ barcadia-3.2.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (80.9.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ barcadia = barcadia.cli:main