Command line¶
Installing the package also installs a command line, called both
universalmotif and umotif, which runs the main functions of the package
on files. It suits shell scripts and workflow managers such as Snakemake and
Nextflow, where each step reads files and writes new ones. It can also be
run as python -m universalmotif.
umotif --help
umotif scan --help
Commands¶
| Command | What it does |
|---|---|
convert |
Convert motifs between formats and types, or reverse complement them. |
fetch |
Download motifs from JASPAR, HOCOMOCO or CIS-BP, keeping a local cache. |
summary |
Summarize motifs as a table. |
filter |
Keep the motifs that pass every filter given. |
trim |
Trim low-information positions from motif edges. |
merge |
Merge similar motifs, or all of them into one. |
tree |
Cluster motifs into a tree, written as Newick, or cut it into clusters. |
logo |
Draw logos, in one aligned figure or one file per motif. |
scan |
Scan sequences, whole genomes or genomic ranges for motif hits. |
compare |
Compare motifs with each other or with a database. |
enrich |
Test motifs for enrichment in target sequences. |
find |
Discover motifs de novo. |
shuffle |
Shuffle sequences, keeping their k-mer counts. |
extract |
Write the sequences of genomic ranges as FASTA. |
bkg |
Draw background sequences matched to targets on GC content, length and bigWig signal. |
matrix |
Make a peak by motif matrix of matches for single-cell ATAC analyses. |
proximity |
Test whether motif hits sit closer to genomic anchors than chance. |
coocc |
Test pairs of motifs for co-occurrence. |
posenr |
Test motifs for positional enrichment within sequences. |
Inputs and outputs¶
A few conventions hold across the commands.
- Motifs can be in any of the supported formats: MEME, JASPAR, HOMER,
TRANSFAC, CIS-BP, UniPROBE or plain matrices, gzipped or not, and CIS-BP
archives downloaded as
.zipfiles. The format is recognized from the extension, or else from the contents, and can be given with-f. Several motif files can be given at once, and-reads from standard input. Motifs are written in the format given with-t, or the one matching the output file's extension, and MEME otherwise. - Sequences are FASTA files, gzipped or not, given with
-s. - Genomes are given with
-g, as plain FASTA, FASTA compressed withbgzipor 2bit files, and only the parts needed are read. Ordinary gzip compression cannot be read in pieces, so a gzipped genome must first be recompressed withbgzip, as described in Scanning large genomes. - Ranges, such as peaks, are given with
-ras BED files, including narrowPeak and broadPeak files, or as tab-separated tables with a header namingchrom,startandendorwidthcolumns. Positions count from 0 and leave the end out, as in BED files. A strand column, or the sixth column of a BED file, marks ranges on the minus strand, which are reverse complemented. - Tables are written as tab-separated text with a header row, with
missing values written as
NAand lists joined by commas. Positions count from 0 and leave the end out, so the first three columns of a table of hits on a genome can be read as BED. - Output goes to standard output unless a file is given with
-o, so commands can be chained with pipes. Files ending in.gzare written gzipped. - Threads are set with
-pand default to 1, and--seedmakes the commands that draw random numbers reproducible.
Warnings, such as for motifs that cannot reach a P-value cutoff, are
printed to standard error, and errors end the command with a short message
and a non-zero exit status. --debug, given before the command, shows the
full traceback instead.
An example¶
Let us go from a set of ChIP-seq peaks to the motifs enriched in them, in
much the same way as the ChIP-seq workflow
guide does in Python. Say the peaks are in peaks.narrowPeak and the genome
in genome.fa.gz, compressed with bgzip.
First, the plant motifs of JASPAR 2024, and the sequences of the peaks:
umotif fetch jaspar --tax-group plants --release 2024 -o jaspar.meme
umotif extract -g genome.fa.gz -r peaks.narrowPeak -o peaks.fa
Then background sequences matched to the peaks on GC content and length,
drawn from windows of the genome that keep clear of the peaks. If there is
a bigWig file of signal, such as ATAC-seq coverage, adding
--bigwig atac.bw matches on it as well.
umotif bkg -g genome.fa.gz -r peaks.narrowPeak --seed 1 -o bkg.fa
Now the enrichment test, which lists the enriched motifs in order of significance. Broad peaks can have hundreds of enriched motifs, so here we keep the twenty most significant, and then find their hits on the genome and draw their logos:
umotif enrich jaspar.meme -s peaks.fa -b bkg.fa -p 4 -o enriched.tsv
cut -f1 enriched.tsv | sed -n '2,21p' > top.txt
umotif filter jaspar.meme $(sed 's/^/--name /' top.txt) -o enriched.meme
umotif scan enriched.meme -g genome.fa.gz -r peaks.narrowPeak -p 4 -o hits.tsv
umotif logo enriched.meme -o enriched.pdf
The hits come back in genomic coordinates, ready to be loaded alongside the peaks in a genome browser or a table. Finally, the motifs found can be checked against the whole of JASPAR, and de novo motifs looked for in the peaks:
umotif compare enriched.meme --db jaspar.meme --complete -o similar.tsv
umotif find -s peaks.fa -b bkg.fa --seed 1 --table found.tsv -o found.meme
Reference¶
The help of every command follows, as printed by umotif COMMAND --help.
convert¶
usage: umotif convert [-h] [-f FORMAT] [-o OUTPUT] [-t FORMAT]
[--type {PCM,PPM,PWM,ICM}] [--pseudocount PSEUDOCOUNT]
[--relative-entropy] [--rc] [--switch-alph]
MOTIFS [MOTIFS ...]
Convert motifs between formats and types.
positional arguments:
MOTIFS motif files in any supported format, recognized from the
extension or contents, or CIS-BP archives (.zip); - reads
standard input
options:
-h, --help show this help message and exit
-f, --format FORMAT the format of the motif files, if it cannot be
recognized: meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix
-o, --output OUTPUT where to write the motifs (default: standard output)
-t, --to FORMAT output format, one of meme, jaspar, homer, transfac,
cisbp, uniprobe, matrix (default: from the output file's
extension, or meme)
--type {PCM,PPM,PWM,ICM} convert the motifs to this type
--pseudocount PSEUDOCOUNT pseudocount to use for the conversion
--relative-entropy with --type ICM, use relative entropy against the
background
--rc reverse complement the motifs
--switch-alph switch DNA motifs to RNA and RNA motifs to DNA
fetch¶
usage: umotif fetch [-h] DATABASE ...
Download motifs from a database, keeping a local cache.
positional arguments:
DATABASE
jaspar motifs from the JASPAR REST API
hocomoco motifs from HOCOMOCO
cisbp motifs from CIS-BP
options:
-h, --help show this help message and exit
fetch jaspar¶
usage: umotif fetch jaspar [-h] [--collection COLLECTION] [--tax-group TAX_GROUP]
[--name NAME] [--tax-id TAX_ID] [--tf-class TF_CLASS]
[--tf-family TF_FAMILY] [--data-type DATA_TYPE]
[--release RELEASE] [--all-versions] [--refresh]
[-o OUTPUT] [-t FORMAT]
Download motifs from the JASPAR REST API.
options:
-h, --help show this help message and exit
--collection COLLECTION collection (default: CORE)
--tax-group TAX_GROUP taxonomic group, such as plants or vertebrates
--name NAME transcription factor name
--tax-id TAX_ID NCBI taxonomy ID of the species
--tf-class TF_CLASS transcription factor class
--tf-family TF_FAMILY transcription factor family
--data-type DATA_TYPE experiment type, such as ChIP-seq
--release RELEASE JASPAR release, such as 2024
--all-versions keep every version of each matrix, not only the latest
--refresh download again rather than using the cache
-o, --output OUTPUT where to write the motifs (default: standard output)
-t, --to FORMAT output format, one of meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix (default: from the output file's
extension, or meme)
fetch hocomoco¶
usage: umotif fetch hocomoco [-h] [--version {11,12}] [--collection COLLECTION]
[--species {HUMAN,MOUSE}] [--refresh] [-o OUTPUT]
[-t FORMAT]
Download motifs from HOCOMOCO, for human and mouse.
options:
-h, --help show this help message and exit
--version {11,12} HOCOMOCO version (default: 12)
--collection COLLECTION collection: CORE, INVIVO, INVITRO or RSNP for version 12,
and CORE or FULL for version 11 (default: CORE)
--species {HUMAN,MOUSE} keep only motifs from human or mouse data
--refresh download again rather than using the cache
-o, --output OUTPUT where to write the motifs (default: standard output)
-t, --to FORMAT output format, one of meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix (default: from the output file's
extension, or meme)
fetch cisbp¶
usage: umotif fetch cisbp [-h] [--family FAMILY] [--inferred] [--refresh] [-o OUTPUT]
[-t FORMAT]
species
Download the motifs of one species from CIS-BP.
positional arguments:
species species, as named by CIS-BP, such as Arabidopsis_thaliana
options:
-h, --help show this help message and exit
--family FAMILY keep this TF family (repeatable)
--inferred include motifs inferred from similar proteins
--refresh download again rather than using the cache
-o, --output OUTPUT where to write the motifs (default: standard output)
-t, --to FORMAT output format, one of meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix (default: from the output file's extension, or
meme)
summary¶
usage: umotif summary [-h] [-f FORMAT] [-o OUTPUT] MOTIFS [MOTIFS ...]
Summarize motifs as a table, one row per motif.
positional arguments:
MOTIFS motif files in any supported format, recognized from the
extension or contents, or CIS-BP archives (.zip); - reads
standard input
options:
-h, --help show this help message and exit
-f, --format FORMAT the format of the motif files, if it cannot be recognized:
meme, jaspar, homer, transfac, cisbp, uniprobe, matrix
-o, --output OUTPUT where to write the table (default: standard output)
filter¶
usage: umotif filter [-h] [-f FORMAT] [-o OUTPUT] [-t FORMAT] [--name NAME]
[--altname ALTNAME] [--family FAMILY] [--organism ORGANISM]
[--alphabet ALPHABET] [--type TYPE] [--strand STRAND]
[--regex REGEX] [--width WIDTH] [--icscore ICSCORE]
[--nsites NSITES] [--pval PVAL] [--qval QVAL] [--eval EVAL]
MOTIFS [MOTIFS ...]
Keep the motifs that pass every filter given.
positional arguments:
MOTIFS motif files in any supported format, recognized from the
extension or contents, or CIS-BP archives (.zip); - reads
standard input
options:
-h, --help show this help message and exit
-f, --format FORMAT the format of the motif files, if it cannot be recognized:
meme, jaspar, homer, transfac, cisbp, uniprobe, matrix
-o, --output OUTPUT where to write the motifs (default: standard output)
-t, --to FORMAT output format, one of meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix (default: from the output file's extension, or
meme)
--name NAME keep motifs with this name (repeatable)
--altname ALTNAME keep motifs with this altname (repeatable)
--family FAMILY keep motifs with this family (repeatable)
--organism ORGANISM keep motifs with this organism (repeatable)
--alphabet ALPHABET keep motifs with this alphabet (repeatable)
--type TYPE keep motifs with this type (repeatable)
--strand STRAND keep motifs with this strand (repeatable)
--regex REGEX keep motifs whose name or altname matches this pattern
--width WIDTH minimum width
--icscore ICSCORE minimum total information content
--nsites NSITES minimum number of sites
--pval PVAL maximum P-value
--qval QVAL maximum q-value
--eval EVAL maximum E-value
trim¶
usage: umotif trim [-h] [-f FORMAT] [-o OUTPUT] [-t FORMAT] [--min-ic MIN_IC]
[--trim-from {both,left,right}]
MOTIFS [MOTIFS ...]
Trim low-information positions from motif edges.
positional arguments:
MOTIFS motif files in any supported format, recognized from
the extension or contents, or CIS-BP archives (.zip);
- reads standard input
options:
-h, --help show this help message and exit
-f, --format FORMAT the format of the motif files, if it cannot be
recognized: meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix
-o, --output OUTPUT where to write the motifs (default: standard output)
-t, --to FORMAT output format, one of meme, jaspar, homer, transfac,
cisbp, uniprobe, matrix (default: from the output
file's extension, or meme)
--min-ic MIN_IC positions below this information content are trimmed
(default: 0.25)
--trim-from {both,left,right}
which edges to trim (default: both)
merge¶
usage: umotif merge [-h] [-f FORMAT] [-o OUTPUT] [-t FORMAT] [-q QVALUE]
[--null {empirical,parametric}] [--min-overlap MIN_OVERLAP]
[--no-rc] [--weighted] [--all] [--name NAME] [--clusters CLUSTERS]
[-p THREADS]
MOTIFS [MOTIFS ...]
Merge motifs that are significantly similar into one motif per cluster, or merge all
of them into one with --all.
positional arguments:
MOTIFS motif files in any supported format, recognized from
the extension or contents, or CIS-BP archives (.zip);
- reads standard input
options:
-h, --help show this help message and exit
-f, --format FORMAT the format of the motif files, if it cannot be
recognized: meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix
-o, --output OUTPUT where to write the motifs (default: standard output)
-t, --to FORMAT output format, one of meme, jaspar, homer, transfac,
cisbp, uniprobe, matrix (default: from the output
file's extension, or meme)
-q, --qvalue QVALUE q-value below which motifs count as similar (default:
0.01)
--null {empirical,parametric}
null model for the similarity P-values (default:
empirical)
--min-overlap MIN_OVERLAP minimum overlap of aligned motifs (default: 5)
--no-rc do not align motifs as reverse complements
--weighted weight motifs by their nsites
--all merge all the motifs into one
--name NAME name of the merged motif, with --all
--clusters CLUSTERS also write a table of which motifs were merged
-p, --threads THREADS threads to use; 0 uses all available (default: 1)
tree¶
usage: umotif tree [-h] [-f FORMAT] [-o OUTPUT]
[--method {complete,average,single,ward.D,ward.D2,mcquitty,median,centroid}]
[--min-overlap MIN_OVERLAP] [--no-rc] [-k K] [--height HEIGHT]
[--plot PLOT] [--layout {rectangular,slanted,circular,fan}]
[--logos] [-p THREADS]
MOTIFS [MOTIFS ...]
Cluster motifs by similarity and write the tree in Newick format, or with -k or
--height a table of clusters.
positional arguments:
MOTIFS motif files in any supported format, recognized from
the extension or contents, or CIS-BP archives (.zip);
- reads standard input
options:
-h, --help show this help message and exit
-f, --format FORMAT the format of the motif files, if it cannot be
recognized: meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix
-o, --output OUTPUT where to write the tree or clusters (default: standard
output)
--method {complete,average,single,ward.D,ward.D2,mcquitty,median,centroid}
linkage method (default: complete)
--min-overlap MIN_OVERLAP minimum overlap of aligned motifs (default: 6)
--no-rc do not align motifs as reverse complements
-k K cut the tree into this many clusters
--height HEIGHT cut the tree at this height
--plot PLOT also draw the tree to this file (PNG, PDF or SVG)
--layout {rectangular,slanted,circular,fan}
layout of the drawn tree (default: rectangular)
--logos draw logos at the tips
-p, --threads THREADS threads to use; 0 uses all available (default: 1)
logo¶
usage: umotif logo [-h] [-f FORMAT] [-o OUTPUT] [--each FOLDER] [--ext {svg,png,pdf}]
[--type {ICM,PPM,PWM,PCM}] [--relative-entropy] [--no-rc]
[--sort-by {none,ic,similarity}] [--dpi DPI] [-p THREADS]
MOTIFS [MOTIFS ...]
Draw motifs as sequence logos, aligned in one figure written with -o, or one file per
motif in a folder with --each.
positional arguments:
MOTIFS motif files in any supported format, recognized from
the extension or contents, or CIS-BP archives (.zip);
- reads standard input
options:
-h, --help show this help message and exit
-f, --format FORMAT the format of the motif files, if it cannot be
recognized: meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix
-o, --output OUTPUT file for one figure of all the motifs (PNG, PDF, SVG)
--each FOLDER write one logo per motif into this folder
--ext {svg,png,pdf} file type for --each (default: svg, which needs no
extra packages)
--type {ICM,PPM,PWM,PCM} what the letter heights show (default: ICM)
--relative-entropy information content relative to the background
--no-rc do not reverse complement motifs to align them
--sort-by {none,ic,similarity}
order of the motifs in the figure: as given, by
decreasing information content, or clustered by
similarity (default: none)
--dpi DPI resolution of PNG files (default: 150)
-p, --threads THREADS threads to use; 0 uses all available (default: 1)
scan¶
usage: umotif scan [-h] [-f FORMAT] [-s SEQUENCES] [-g GENOME] [-r RANGES] [-o OUTPUT]
[-P PVALUE] [--no-rc] [--no-overlaps]
[--overlaps-by {pvalue,score}] [--across-strands] [--across-motifs]
[--no-gaps] [--correct-gaps] [--local] [--genomic] [-p THREADS]
MOTIFS [MOTIFS ...]
Scan sequences for motif hits. Sequences come from a FASTA file with -s, which is read
a batch at a time, from a whole genome with -g, or from ranges of a genome with -g and
-r, whose hits are reported in genomic coordinates.
positional arguments:
MOTIFS motif files in any supported format, recognized from
the extension or contents, or CIS-BP archives (.zip);
- reads standard input
options:
-h, --help show this help message and exit
-f, --format FORMAT the format of the motif files, if it cannot be
recognized: meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix
-s, --sequences SEQUENCES FASTA file of sequences
-g, --genome GENOME genome (FASTA, bgzipped FASTA or 2bit) to scan whole,
or in parts with -r
-r, --ranges RANGES BED file or table of the ranges of the sequences, with
-g
-o, --output OUTPUT where to write the hits (default: standard output)
-P, --pvalue PVALUE P-value cutoff for motif hits (default: 0.0001)
--no-rc scan only the forward strand
--no-overlaps remove overlapping hits of each motif, keeping the
best
--overlaps-by {pvalue,score} what makes the best hit with --no-overlaps (default:
pvalue)
--across-strands with --no-overlaps, compare hits on both strands
--across-motifs with --no-overlaps, compare hits of different motifs
--no-gaps ignore the gaps of gapped motifs
--correct-gaps correct gapped motifs' P-values for the gap sizes
tried
--local with -r, report positions within each range, not on
the genome
--genomic with -s, read each sequence's place in the genome from
names like chrom:start-end and report hits in genomic
coordinates
-p, --threads THREADS threads to use; 0 uses all available (default: 1)
compare¶
usage: umotif compare [-h] [-f FORMAT] [-o OUTPUT] [--db DB [DB ...]]
[--db-format FORMAT] [-q QVALUE] [--all]
[--min-overlap MIN_OVERLAP] [--no-rc]
[--null {empirical,parametric}] [--complete]
[--matrix {score,pvalue,qvalue}] [-p THREADS]
MOTIFS [MOTIFS ...]
Compare motifs with each other, or with a database of motifs given with --db,
reporting the matches that pass a q-value cutoff.
positional arguments:
MOTIFS motif files in any supported format, recognized from
the extension or contents, or CIS-BP archives (.zip);
- reads standard input
options:
-h, --help show this help message and exit
-f, --format FORMAT the format of the motif files, if it cannot be
recognized: meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix
-o, --output OUTPUT where to write the table (default: standard output)
--db DB [DB ...] motif files to compare the motifs with
--db-format FORMAT format of the --db files
-q, --qvalue QVALUE q-value cutoff for reported matches (default: 0.1)
--all report every pair, whatever its q-value
--min-overlap MIN_OVERLAP minimum overlap of aligned motifs (default: 5)
--no-rc do not align motifs as reverse complements
--null {empirical,parametric}
null model for the P-values (default: empirical)
--complete score whole queries rather than only the overlap
--matrix {score,pvalue,qvalue}
write an all-against-all matrix of this value instead
-p, --threads THREADS threads to use; 0 uses all available (default: 1)
enrich¶
usage: umotif enrich [-h] [-f FORMAT] [-s SEQUENCES] [-g GENOME] [-r RANGES] [-b BKG]
[-o OUTPUT] [-P PVALUE] [--no-rc] [-q QVALUE]
[--test {seqs,hits}] [--shuffle-k SHUFFLE_K] [--seed SEED]
[-p THREADS]
MOTIFS [MOTIFS ...]
Test motifs for enrichment in target sequences against background sequences, or
against shuffled targets when no background is given.
positional arguments:
MOTIFS motif files in any supported format, recognized from the
extension or contents, or CIS-BP archives (.zip); - reads
standard input
options:
-h, --help show this help message and exit
-f, --format FORMAT the format of the motif files, if it cannot be
recognized: meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix
-s, --sequences SEQUENCES FASTA file of target sequences
-g, --genome GENOME genome (FASTA, bgzipped FASTA or 2bit) to take the target
sequences from, with -r
-r, --ranges RANGES BED file or table of the ranges of the target sequences,
with -g
-b, --bkg BKG FASTA file of background sequences
-o, --output OUTPUT where to write the table (default: standard output)
-P, --pvalue PVALUE P-value cutoff for motif hits (default: 0.0001)
--no-rc scan only the forward strand
-q, --qvalue QVALUE q-value cutoff for reported motifs (default: 0.1)
--test {seqs,hits} count sequences with hits, or hits (default: seqs)
--shuffle-k SHUFFLE_K k-mer size kept when shuffling targets for a background
(default: 2)
--seed SEED random seed, for reproducible results
-p, --threads THREADS threads to use; 0 uses all available (default: 1)
find¶
usage: umotif find [-h] [-s SEQUENCES] [-g GENOME] [-r RANGES] [-b BKG] [-o OUTPUT]
[-t FORMAT] [--table TABLE] [--min-width MIN_WIDTH]
[--max-width MAX_WIDTH] [--nmotifs NMOTIFS]
[--hit-pvalue HIT_PVALUE] [--stop-pvalue STOP_PVALUE] [-q QVALUE]
[--no-rc] [--shuffle-k SHUFFLE_K] [--seed SEED] [-p THREADS]
Discover motifs enriched in target sequences, writing the motifs with -o and a table
of results with --table.
options:
-h, --help show this help message and exit
-s, --sequences SEQUENCES FASTA file of target sequences
-g, --genome GENOME genome (FASTA, bgzipped FASTA or 2bit) to take the target
sequences from, with -r
-r, --ranges RANGES BED file or table of the ranges of the target sequences,
with -g
-b, --bkg BKG FASTA file of background sequences
-o, --output OUTPUT where to write the motifs (default: standard output)
-t, --to FORMAT output format, one of meme, jaspar, homer, transfac,
cisbp, uniprobe, matrix (default: from the output file's
extension, or meme)
--table TABLE also write a table of the motifs found
--min-width MIN_WIDTH smallest width (default: 6)
--max-width MAX_WIDTH largest width (default: 15)
--nmotifs NMOTIFS most motifs to find per width (default: 10)
--hit-pvalue HIT_PVALUE P-value of a site counting as a hit (default: 1e-4)
--stop-pvalue STOP_PVALUE enrichment P-value at which to stop (default: 1e-3)
-q, --qvalue QVALUE q-value cutoff for reported motifs (default: 0.05)
--no-rc search only the forward strand
--shuffle-k SHUFFLE_K k-mer size kept when shuffling targets for a background
(default: 2)
--seed SEED random seed, for reproducible results
-p, --threads THREADS threads to use; 0 uses all available (default: 1)
shuffle¶
usage: umotif shuffle [-h] -s SEQUENCES [-o OUTPUT] [-k K]
[--method {euler,linear,markov}] [--seed SEED] [-p THREADS]
Shuffle sequences, keeping k-mer counts.
options:
-h, --help show this help message and exit
-s, --sequences SEQUENCES FASTA file of sequences
-o, --output OUTPUT where to write the shuffled sequences (default:
standard output)
-k K size of the k-mers kept (default: 1)
--method {euler,linear,markov}
shuffling method (default: euler)
--seed SEED random seed, for reproducible results
-p, --threads THREADS threads to use; 0 uses all available (default: 1)
extract¶
usage: umotif extract [-h] -g GENOME -r RANGES [-o OUTPUT] [--width WIDTH]
[-p THREADS]
Write the sequences of genomic ranges as FASTA, reverse complementing those on the
minus strand.
options:
-h, --help show this help message and exit
-g, --genome GENOME genome (FASTA, bgzipped FASTA or 2bit)
-r, --ranges RANGES BED file or table of ranges
-o, --output OUTPUT where to write the sequences (default: standard output)
--width WIDTH FASTA line width (default: 80)
-p, --threads THREADS threads to use; 0 uses all available (default: 1)
bkg¶
usage: umotif bkg [-h] [-s SEQUENCES] [-r RANGES] [-g GENOME] [-u UNIVERSE]
[-o OUTPUT] [--table TABLE] [-n N] [--exclude EXCLUDE]
[--chromosomes CHROMOSOMES [CHROMOSOMES ...]]
[--candidates CANDIDATES] [--gc-bins GC_BINS]
[--length-bins LENGTH_BINS] [--bigwig [NAME=]PATH]
[--covariate-bins COVARIATE_BINS]
[--covariate-bin-type {quantile,equalwidth}] [--repeats]
[--seed SEED] [-p THREADS]
Draw background sequences matched to the targets on GC content and length, and
optionally on bigWig signal, from a universe of sequences or from random windows of a
genome.
options:
-h, --help show this help message and exit
-s, --sequences SEQUENCES FASTA file of target sequences
-r, --ranges RANGES BED file or table of the targets' ranges, with -g;
windows overlapping them are not drawn
-g, --genome GENOME genome to draw windows from
-u, --universe UNIVERSE FASTA file of candidate background sequences
-o, --output OUTPUT where to write the background sequences (default:
standard output)
--table TABLE also write a table of the matches
-n N background sequences per target (default: 1)
--exclude EXCLUDE BED file of ranges to avoid (repeatable)
--chromosomes CHROMOSOMES [CHROMOSOMES ...]
chromosomes to draw windows from
--candidates CANDIDATES genome windows to draw candidates from (default:
max(10000, 10 x targets))
--gc-bins GC_BINS GC content bins (default: 20)
--length-bins LENGTH_BINS length bins (default: 10)
--bigwig [NAME=]PATH also match on the mean signal of this bigWig file
(repeatable)
--covariate-bins COVARIATE_BINS
bins for each bigWig signal (default: 10)
--covariate-bin-type {quantile,equalwidth}
how bigWig signal is binned (default: quantile)
--repeats allow a background sequence to be drawn more than once
--seed SEED random seed, for reproducible results
-p, --threads THREADS threads to use; 0 uses all available (default: 1)
matrix¶
usage: umotif matrix [-h] [-f FORMAT] [-s SEQUENCES] [-g GENOME] [-r RANGES]
[-o OUTPUT] [-P PVALUE] [--no-rc]
[--value {matches,counts,scores}] [--no-overlaps] [-p THREADS]
MOTIFS [MOTIFS ...]
Make a sparse peak by motif matrix of motif matches, hit counts or best scores,
written as .h5ad, as Matrix Market (.mtx, with the row and column names alongside), or
otherwise as a long table.
positional arguments:
MOTIFS motif files in any supported format, recognized from
the extension or contents, or CIS-BP archives (.zip);
- reads standard input
options:
-h, --help show this help message and exit
-f, --format FORMAT the format of the motif files, if it cannot be
recognized: meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix
-s, --sequences SEQUENCES FASTA file of peaks
-g, --genome GENOME genome (FASTA, bgzipped FASTA or 2bit) to take the
peaks from, with -r
-r, --ranges RANGES BED file or table of the ranges of the peaks, with -g
-o, --output OUTPUT where to write the matrix (default: standard output)
-P, --pvalue PVALUE P-value cutoff for motif hits (default: 5e-05)
--no-rc scan only the forward strand
--value {matches,counts,scores}
what the matrix holds (default: matches)
--no-overlaps count overlapping hits of a motif once
-p, --threads THREADS threads to use; 0 uses all available (default: 1)
proximity¶
usage: umotif proximity [-h] [-f FORMAT] -a ANCHORS [-g GENOME] [-s SEQUENCES]
[--hits HITS] [--universe UNIVERSE] [-o OUTPUT] [-P PVALUE]
[--no-rc] [--method {binomial,permutation,ks}]
[--count {hits,anchors}]
[--orientation {undirected,upstream,downstream}]
[--distances DISTANCES] [--n-perm N_PERM] [--global-perm]
[--stranded] [-q QVALUE] [--nearest] [--seed SEED]
[-p THREADS]
[MOTIFS ...]
Test whether motif hits sit closer to genomic anchors than chance, scanning a genome
for the motifs or using a table of hits.
positional arguments:
MOTIFS motif files in any supported format, recognized from
the extension or contents, or CIS-BP archives (.zip);
- reads standard input
options:
-h, --help show this help message and exit
-f, --format FORMAT the format of the motif files, if it cannot be
recognized: meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix
-a, --anchors ANCHORS BED file or table of anchors
-g, --genome GENOME genome to scan, or whose lengths make the universe
-s, --sequences SEQUENCES FASTA file of chromosomes to scan instead
--hits HITS table of hits, such as from scan -g, instead of
scanning
--universe UNIVERSE regions hits could fall in: a BED file, chrom.sizes or
.fai file, or a genome (default: the whole genome)
-o, --output OUTPUT where to write the table (default: standard output)
-P, --pvalue PVALUE P-value cutoff for motif hits (default: 0.0001)
--no-rc scan only the forward strand
--method {binomial,permutation,ks}
null model (default: binomial)
--count {hits,anchors} count hits near anchors, or anchors with hits
(default: hits)
--orientation {undirected,upstream,downstream}
zone around stranded anchors (default: undirected)
--distances DISTANCES comma-separated distances to test
--n-perm N_PERM permutations with --method permutation (default: 1000)
--global-perm move anchors anywhere in the universe, not within
their chromosome
--stranded count overlapping hits on the two strands separately
-q, --qvalue QVALUE q-value cutoff for reported motifs (default: 0.1)
--nearest include each hit's distance to its nearest anchor
--seed SEED random seed, for reproducible results
-p, --threads THREADS threads to use; 0 uses all available (default: 1)
coocc¶
usage: umotif coocc [-h] [-f FORMAT] [-s SEQUENCES] [-g GENOME] [-r RANGES]
[--hits HITS] [--n-sequences N_SEQUENCES] [-o OUTPUT] [-P PVALUE]
[--no-rc] [--no-overlaps] [--max-distance MAX_DISTANCE]
[--min-coocc MIN_COOCC] [--pseudocount PSEUDOCOUNT] [--self-pairs]
[-p THREADS]
MOTIFS [MOTIFS ...]
Test pairs of motifs for co-occurring in the same sequences more often than chance.
positional arguments:
MOTIFS motif files in any supported format, recognized from
the extension or contents, or CIS-BP archives (.zip); -
reads standard input
options:
-h, --help show this help message and exit
-f, --format FORMAT the format of the motif files, if it cannot be
recognized: meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix
-s, --sequences SEQUENCES FASTA file of sequences
-g, --genome GENOME genome (FASTA, bgzipped FASTA or 2bit) to take the
sequences from, with -r
-r, --ranges RANGES BED file or table of the ranges of the sequences, with
-g
--hits HITS table of hits instead of scanning, with --n-sequences
--n-sequences N_SEQUENCES number of sequences the hits came from
-o, --output OUTPUT where to write the table (default: standard output)
-P, --pvalue PVALUE P-value cutoff for motif hits (default: 0.0001)
--no-rc scan only the forward strand
--no-overlaps remove overlapping hits of each motif before counting
--max-distance MAX_DISTANCE also report how often pairs of hits are within this
distance
--min-coocc MIN_COOCC test only pairs sharing at least this many sequences
(default: 1)
--pseudocount PSEUDOCOUNT pseudocount added to every cell of the 2x2 table
(default: 0)
--self-pairs also count repeated sites of a single motif
-p, --threads THREADS threads to use; 0 uses all available (default: 1)
posenr¶
usage: umotif posenr [-h] [-f FORMAT] [-s SEQUENCES] [-g GENOME] [-r RANGES]
[--hits HITS] [--seq-length SEQ_LENGTH] [-o OUTPUT] [-P PVALUE]
[--no-rc] [--mode {central,local}] [-q QVALUE]
[--min-window MIN_WINDOW] [--max-window MAX_WINDOW]
[--window-step WINDOW_STEP] [--position-step POSITION_STEP]
[--centres] [-p THREADS]
[MOTIFS ...]
Test whether motif hits gather at the centre of the sequences, or anywhere along them
with --mode local, as around peak summits.
positional arguments:
MOTIFS motif files in any supported format, recognized from
the extension or contents, or CIS-BP archives (.zip);
- reads standard input
options:
-h, --help show this help message and exit
-f, --format FORMAT the format of the motif files, if it cannot be
recognized: meme, jaspar, homer, transfac, cisbp,
uniprobe, matrix
-s, --sequences SEQUENCES FASTA file of sequences
-g, --genome GENOME genome (FASTA, bgzipped FASTA or 2bit) to take the
sequences from, with -r
-r, --ranges RANGES BED file or table of the ranges of the sequences, with
-g
--hits HITS table of hits instead of scanning, with --seq-length
--seq-length SEQ_LENGTH length of the sequences (default: their length, if all
the same)
-o, --output OUTPUT where to write the table (default: standard output)
-P, --pvalue PVALUE P-value cutoff for motif hits (default: 0.0001)
--no-rc scan only the forward strand
--mode {central,local} windows centred on the sequences, or anywhere along
them (default: central)
-q, --qvalue QVALUE q-value cutoff for reported motifs (default: 0.1)
--min-window MIN_WINDOW smallest window (default: 10)
--max-window MAX_WINDOW largest window (default: half the sequence length)
--window-step WINDOW_STEP window size step (default: 10)
--position-step POSITION_STEP
window position step with --mode local (default: 5)
--centres include the centres of the hits used for each motif
-p, --threads THREADS threads to use; 0 uses all available (default: 1)