Crate universalmotif 

Sequence motifs: creating, converting, reading and writing them, and using them to scan, compare, cluster and test sequences.

This crate is a port of the universalmotif R/Bioconductor package and the engine behind its Python version; besides fixes for bugs in the R package, DIVERGENCES.md lists where the two differ.

The motif type

A Motif is a position matrix over an Alphabet of DNA, RNA, amino acids or a custom set of letters, together with its metadata: name, background frequencies, pseudocount, site count, gaps and so on. Its MotifType says whether the matrix holds counts, probabilities, weights, information content or contributions. Motifs are immutable once built and always valid; MotifBuilder and MotifParts build them.

A first example

use universalmotif::create::{CreateOptions, from_strings};
use universalmotif::compare::{CompareOptions, compare_motifs};
use universalmotif::io::meme;
use universalmotif::scan::{ScanOptions, scan_table};

// Two motifs from aligned sites.
let opts = CreateOptions { nsites: Some(20.0), pseudocount: 1.0, ..Default::default() };
let ap1 = from_strings(&["TGACTCA", "TGAGTCA", "TGACTAA"], None, &opts)?;
let creb = from_strings(&["TGACGTCA", "TGACGTCA", "TTACGTAA"], None, &opts)?;

// Write them as MEME text and read them back.
let text = meme::write(&[ap1, creb], &meme::WriteOptions::default())?;
let motifs = meme::read(&text, &meme::ReadOptions::default())?;

// Scan both strands of a sequence at a P-value cutoff of 1e-3.
let seqs = ["CCCCTGACTCACCCCCATGACGTCATCCC"];
let hits = scan_table(&motifs, &seqs, &ScanOptions { pvalue: 1e-3, ..Default::default() })?;
assert!(hits.len() >= 2);
println!("{} at {}..{}", hits.matched(0, &seqs), hits.start[0], hits.end[0]);

// Compare the first motif with both.
let comparisons = compare_motifs(&motifs, &[0], &CompareOptions::default())?;
assert_eq!(comparisons.len(), 2);

Where things are

Task	Modules
Build and convert motifs	create, convert, ops, merge
Read and write motif and FASTA files	io
Read genomes a piece at a time from FASTA, bgzip and 2bit files	genome
P-values and match scores	pvalue, scoring, cdf
Scan sequences, including gapped motifs and whole genomes	scan, packed
Compare and cluster motifs	compare, cluster, metrics
Enrichment, co-occurrence and positional enrichment	enrich, coocc, peaks
Genomic anchors and matched backgrounds	proximity, background, ranges
Sequences: k-mers, complexity, shuffling, sampling, masking	kmer, complexity, shuffle, sample, mask
De novo motif discovery	finder

Functions that do a lot of work take a thread count, nthreads, in their options, where 0 means all cores.

Options are structs with public fields and a Default, so a call sets only the fields it needs and takes the rest from ..Default::default(). Until version 1.0, options may gain fields in new minor versions. Results, such as scan::Hit or compare::Comparison, are marked #[non_exhaustive], so they can gain fields without breaking code that reads them.

Re-exports

pub use alphabet::Alphabet;

pub use error::Error;

pub use error::Result;

pub use matrix::Matrix;

pub use motif::GapInfo;

pub use motif::Motif;

pub use motif::MotifBuilder;

pub use motif::MotifParts;

pub use motif::MotifType;

pub use motif::Strand;

Modules

alphabet

Motif alphabets.

background

Composition-matched background sequences, drawn by match_bkg.

cdf

Score distributions of motifs.

cluster

Hierarchical clustering.

compare

Motif comparison with compare_motifs.

complexity

Sequence complexity, of whole sequences with complexity and in sliding windows with sequence_complexity.

convert

Conversions between motif types, information content and consensus letters.

coocc

Co-occurring motif pairs, tested by motif_coocc.

create

Creating motifs from matrices, consensus strings, sets of sites, or at random.

dedup

Removing overlapping hits with dedup.

enrich

Motif enrichment with enrich_motifs.

error

The error type returned by the crate’s functions.

finder

De novo motif discovery with motif_finder.

genome

Random access to genome sequences on disk.

io

Reading and writing motif files.

kmer

k-mers, k-mer counts and background frequencies of sequences.

mask

Masking sequences by pattern with mask_seqs and by position with mask_ranges.

matrix

Dense motif matrices.

merge

Merging motifs with merge_motifs and merge_similar.

metrics

Column similarity metrics with compare_columns, and averages with average and average_ic.

motif

The motif type, its builder and its validation rules.

ops

Operations that transform a motif: reverse complement, trimming, rounding and renormalization.

packed

Sequences encoded for scanning.

peaks

Positional enrichment of motif hits, tested by motif_peaks.

proximity

Motif enrichment near genomic anchors, tested by motif_proximity.

pvalue

Motif P-values and score thresholds.

ranges

Genomic ranges and the few operations on them that motif proximity testing needs: reducing, intersecting, overlaps, flanks and distances.

sample

Sampling sites from motifs with sample_sites and implanting them into sequences with implant_motifs.

scan

Scanning sequences for motif hits.

scoring

Scores of individual matches: score ranges, the score of a word, every word above a score and the probability of a word under the background.

shuffle

Shuffling sequences and motifs with shuffle_sequences and shuffle_motifs, and generating random sequences with create_sequences.