dnacomb 1.0.0

Count the occurances of structured sequence reads and compare to an expected library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172

//! Library supporting the [DNAComb] structured sequence read processing tool.
//! The [GitHub] and [Crates.io] page give documentation for the CLI tool with
//! these pages documenting the library,
//!
//! DNAComb provides functionality for:
//! - defining expected construct structure with `LibrarySpec`,
//! - reading and filtering single-end or paired-end sequencing reads,
//! - extracting variable regions from structured reads,
//! - counting distinct observed region combinations,
//! - and optionally comparing observed regions to expected library sequences.
//!
//! The crate is designed primarily to support the `dnacomb` CLI, but the core
//! counting and library-comparison logic can also be used programmatically from
//! Rust.
//!
//! The main entry points are:
//! - [`LibrarySpec`] for describing construct structure,
//! - [`count_reads`] for extracting and counting observed read forms,
//! - [`ObservedCombinations`] for storing and post-processing counts,
//! - [`SubLibrary`] for compiling expected library sequence sets,
//! - and the `write_*` functions in [`output`] for generating TSV outputs.
//!
//! For CLI usage, see the project README and `dnacomb --help`.
//!
//! # Example
//!
//! ```no_run
//! use std::fs::File;
//!
//! use dnacomb::{
//!     count_reads, write_counts, Compression, CountMode, FilterConfig, LibrarySpec,
//!     ReadPairParser, SeqFormat, SeqPath,
//! };
//!
//! # fn run() -> Result<(), Box<dyn std::error::Error>> {
//! // Load a LibSpec
//! let lib_spec = LibrarySpec::from_file(
//!     "config/example_libspec.json",
//!     None,
//!     None,
//!     None,
//!     None,
//! )?;
//!
//! // Create input paths and parser
//! let forward = SeqPath::new(
//!     "reads_R1.fastq.gz".to_string(),
//!     SeqFormat::Auto,
//!     Compression::Auto,
//! );
//! let reverse = Some(SeqPath::new(
//!     "reads_R2.fastq.gz".to_string(),
//!     SeqFormat::Auto,
//!     Compression::Auto,
//! ));
//!
//! let reader = ReadPairParser::from_paths(
//!     forward,
//!     reverse,
//!     None,
//!     0,
//!     b'I',
//! )?;
//!
//! // Configure filtering
//! let filter_config = FilterConfig::new(
//!     Some(20.0),
//!     None,
//!     Some(50),
//!     Some(300),
//!     true,
//! );
//!
//! // Count reads
//! let counts = count_reads(
//!     reader,
//!     &Some(lib_spec),
//!     CountMode::Pattern,
//!     false,
//!     filter_config,
//!     None,
//!     Some(12),
//!     Some(2),
//!     true,
//!     1,
//!     None,
//! )?;
//!
//! // Write full count table
//! let out = File::create("example.counts.tsv")?;
//! write_counts(&counts, out, true, false)?;
//!
//! # Ok(())
//! # }
//! ```
//!
//! [DNAComb]: https://github.com/allydunham/dnacomb
//! [GitHub]: https://github.com/allydunham/dnacomb
//! [Crates.io]: https://crates.io/crates/dnacomb
pub mod combination;
pub mod combinations;
pub mod counting;
pub mod errors;
pub mod filters;
pub mod groups;
pub mod interning;
pub mod lib_spec;
pub mod library;
pub mod library_combination;
pub mod logging;
pub mod output;
pub mod parsing;
pub mod region;
pub mod seq_diff;
pub mod seqs;
pub mod utils;

/// Parse single-end or paired-end sequence files into `ReadPair`s.
pub use parsing::ReadPairParser;

/// Path plus format/compression metadata for sequence-file input.
pub use parsing::SeqPath;

/// Sequence file format selection.
pub use parsing::SeqFormat;

/// Compression mode for sequence-file input.
pub use parsing::Compression;

/// Specification of construct structure and expected read layout.
pub use lib_spec::LibrarySpec;

/// Compiled expected sequence library for one sublibrary.
pub use library::SubLibrary;

/// Distance metric used for library comparison.
pub use library::DistanceMetric;

/// Filter reads with various configuration options.
pub use filters::FilterConfig;

/// Count observed read forms.
pub use counting::count_reads;

/// Supported modes for extracting regions from reads
pub use counting::CountMode;

/// Alignment scoring scheme for template-based region extraction.
pub use counting::AlignmentScorer;

/// Container for observed region combinations and their counts.
pub use combinations::ObservedCombinations;

/// Write the full observed-combination count table as TSV.
pub use output::write_counts;

/// Write the filtered-read summary table as TSV.
pub use output::write_filter_summary;

/// Write the library-combination summary table as TSV.
pub use output::write_library_counts;

/// Write the high-level read summary table as TSV.
pub use output::write_summary;

/// Configure loggins
pub use logging::ProgressStyle;

#[cfg(not(any(target_pointer_width = "64", target_pointer_width = "32")))]
compile_error!(
    "Only 32bit and 64 bit targets are supported as usize is assumed to be >= u32 in various places"
);