universalmotif 0.1.0__tar.gz

universalmotif-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Jean-Marie Tremblay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

universalmotif-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: universalmotif
+Version: 0.1.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Dist: numpy>=1.24
+Requires-Dist: polars>=1.0
+Requires-Dist: anndata>=0.10 ; extra == 'anndata'
+Requires-Dist: scipy>=1.11 ; extra == 'anndata'
+Requires-Dist: pybigtools>=0.3 ; extra == 'bigwig'
+Requires-Dist: biopython>=1.81 ; extra == 'biopython'
+Requires-Dist: h5py>=3.0 ; extra == 'h5py'
+Requires-Dist: pandas>=2.0 ; extra == 'pandas'
+Requires-Dist: pyarrow>=14 ; extra == 'pandas'
+Requires-Dist: matplotlib>=3.8 ; extra == 'plot'
+Requires-Dist: polars-bio>=0.36 ; python_full_version >= '3.11' and python_full_version < '3.15' and extra == 'polars-bio'
+Requires-Dist: pyranges1>=1.0 ; python_full_version >= '3.12' and extra == 'pyranges'
+Requires-Dist: scipy>=1.11 ; extra == 'scipy'
+Provides-Extra: anndata
+Provides-Extra: bigwig
+Provides-Extra: biopython
+Provides-Extra: h5py
+Provides-Extra: pandas
+Provides-Extra: plot
+Provides-Extra: polars-bio
+Provides-Extra: pyranges
+Provides-Extra: scipy
+License-File: LICENSE
+Summary: Sequence motif manipulation and analysis, a Python port of universalmotif
+Keywords: bioinformatics,motif,pwm,genomics
+Author: Benjamin Jean-Marie Tremblay
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://bjmt.github.io/universalmotif-py/changelog/
+Project-URL: Documentation, https://bjmt.github.io/universalmotif-py/
+Project-URL: Issues, https://github.com/bjmt/universalmotif-py/issues
+Project-URL: Repository, https://github.com/bjmt/universalmotif-py
+
+# universalmotif (Python)
+
+A Python package for working with sequence motifs: creating them, converting
+between their representations, reading and writing them in the common file
+formats, and using them to scan, compare and test sequences. It is a port of
+the [universalmotif](https://bioconductor.org/packages/universalmotif/)
+R/Bioconductor package, built on its Rust version,
+[universalmotif-rs](https://github.com/bjmt/universalmotif-rs), which does
+the heavy lifting, so most of it is quick and can use several threads.
+Motifs are `Motif` objects, matrices come back as numpy arrays, and tables
+come back as [polars](https://pola.rs/) DataFrames.
+
+The [documentation](https://bjmt.github.io/universalmotif-py/) has guides
+covering everything from motif basics to a full ChIP-seq analysis, and a
+reference for every function. The package is at an early version, and its
+interface may still change.
+
+## Installation
+
+The package needs Python 3.10 or later and can be installed from PyPI:
+
+```sh
+pip install universalmotif
+```
+
+Wheels are built for Linux (x86_64 and aarch64), macOS (Intel and Apple
+Silicon) and Windows (x86_64). Elsewhere pip builds the package from source,
+which needs a [Rust toolchain](https://rustup.rs/).
+
+The only required dependencies are numpy and polars. Everything else is an
+optional extra, needed only by the functions that use it, so that for
+example `pip install "universalmotif[plot]"` adds matplotlib for drawing
+logos:
+
+| Extra | Brings in | For |
+| --- | --- | --- |
+| `plot` | matplotlib | logos, trees and the other plots |
+| `scipy` | SciPy | sparse motif match matrices |
+| `anndata` | AnnData, SciPy | match matrices stored with single-cell ATAC data |
+| `biopython` | Biopython | converting to and from `Bio.motifs` |
+| `h5py` | h5py | reading TF-MoDISco results |
+| `bigwig` | pybigtools | bigWig signal, and backgrounds matched on it |
+| `pyranges` | PyRanges | converting tables to PyRanges objects |
+| `polars-bio` | polars-bio | preparing tables for polars-bio |
+| `pandas` | pandas, pyarrow | pandas DataFrames, and logomaker export |
+
+## A quick look
+
+Using the example motifs and sequences that come with the package:
+
+```python
+import universalmotif as um
+
+# A motif from a few aligned sites, and its log-odds matrix.
+ap1 = um.create_motif(["TGACTCA", "TGAGTCA", "TGACTAA"], name="AP-1", pseudocount=1)
+print(um.convert_type(ap1, "PWM").matrix)
+
+# Scan sequences for the example motifs, and test them for enrichment
+# against a set of control sequences.
+motifs = um.example_motifs()
+targets = um.example_sequences("targets")
+controls = um.example_sequences("controls")
+hits = um.scan_sequences(motifs, targets, pvalue=1e-4)
+enriched = um.enrich_motifs(motifs, targets, controls)
+
+# How similar are the motifs, and what do they look like?
+similar = um.compare_motifs(motifs, compare_to="AP-1")
+um.view_motifs(motifs[:4]).savefig("logos.png")
+
+# Look for new motifs in the targets.
+found = um.motif_finder(targets, controls, seed=1)
+```
+
+## What it can do
+
+- **Motifs:** create them from sites, consensus strings or matrices, convert
+  between counts, probabilities, log-odds, information content and
+  contribution scores, and trim, round, merge, reverse complement and filter
+  them.
+- **Files:** MEME, JASPAR, HOMER, TRANSFAC, CIS-BP, UniPROBE and plain
+  matrices, and FASTA for sequences, gzipped or not.
+- **Databases:** motifs fetched from JASPAR, HOCOMOCO and CIS-BP and kept in
+  a local cache, and conversion to and from Biopython.
+- **Scanning:** exact P-value thresholds, both strands, any alphabet and
+  gapped motifs, with whole genomes scanned from a FASTA file in a few
+  hundred MB.
+- **Comparison:** similarity with P-values, scored either on the overlap or
+  on the whole query, merging of similar motifs, and trees.
+- **Statistics:** enrichment, co-occurrence, positional enrichment,
+  proximity to genomic anchors, composition-matched backgrounds and *de
+  novo* motif discovery.
+- **Genomes:** FASTA, bgzip and 2bit genomes read a piece at a time, the
+  sequences of peaks, bigWig signal over them, and hits moved back to
+  genomic coordinates, with ranges exchanged with PyRanges and polars-bio.
+- **Single-cell ATAC and deep learning:** sparse peak by motif matrices for
+  AnnData and pychromVAR, motifs as convolution filters and back, one-hot
+  sequences, and TF-MoDISco results.
+- **Sequences:** shuffling that keeps k-mer counts, random sequences, k-mer
+  backgrounds, complexity, masking and sliding windows.
+- **Plots:** sequence logos, motif trees and plots of the results above,
+  with motifs shown as logos in Jupyter and SVG logos for reports.
+
+Scanning, comparison, merging, clustering, enrichment and logos work for
+amino acid and custom alphabets as well as DNA and RNA.
+
+## Command line
+
+The package also installs a command line, as both `universalmotif` and
+`umotif`, which runs the main functions on files for shell scripts and
+workflow managers:
+
+```sh
+umotif fetch jaspar --tax-group plants --release 2024 -o jaspar.meme
+umotif extract -g genome.fa.gz -r peaks.narrowPeak -o peaks.fa
+umotif bkg -g genome.fa.gz -r peaks.narrowPeak --seed 1 -o bkg.fa
+umotif enrich jaspar.meme -s peaks.fa -b bkg.fa -p 4 -o enriched.tsv
+```
+
+`umotif --help` lists all 19 commands.
+
+## Differences from the R package
+
+Function names follow the R package, with underscores in place of dots, so
+`min.ic` becomes `min_ic`. Where the R package has both a full and a `_lite`
+version of a function, this package provides the lite one under the plain
+name. Readers always return a list of motifs, and MEME site tables come
+back as polars DataFrames. Functions that use random numbers take a `seed`,
+but seeds do not reproduce the R package's results, since the two use
+different random number generators.
+
+Bugs found in the R package while porting it are fixed here rather than
+reproduced.
+[DIVERGENCES.md](https://github.com/bjmt/universalmotif-rs/blob/main/DIVERGENCES.md)
+in the Rust crate lists the other differences, including the few features
+left out on purpose.
+
+## Documentation
+
+The documentation lives at <https://bjmt.github.io/universalmotif-py/>. It is built with MkDocs from `docs/`,
+with the API reference generated from the docstrings and guides written as
+notebooks. To build it and preview it locally:
+
+```sh
+uv sync --group docs --no-install-project
+uv run --no-sync maturin develop --release
+uv run --no-sync mkdocs serve
+```
+
+## Development
+
+Development uses [uv](https://docs.astral.sh/uv/) and
+[maturin](https://www.maturin.rs/), with the Rust crate checked out next to
+this one, since the package builds against it and the tests read the R
+reference values kept there:
+
+```sh
+git clone https://github.com/bjmt/universalmotif-rs.git
+git clone https://github.com/bjmt/universalmotif-py.git
+cd universalmotif-py
+uv sync --group dev --no-install-project
+uv run --no-sync maturin develop --release
+uv run --no-sync pytest
+```
+
+## Citation
+
+If this package has been useful for your research, please cite the article
+describing universalmotif:
+
+Tremblay BJM (2024). universalmotif: An R package for biological motif
+analysis. *Journal of Open Source Software* **9**, 7012.
+DOI: [10.21105/joss.07012](https://doi.org/10.21105/joss.07012)
+
+## Licence
+
+MIT. The letter shapes used in logos are outlines of the Roboto font,
+released under the Apache License 2.0, and were exported from the R
+package's `fontDFroboto` with `scripts/make_font.R`.
+

universalmotif-0.1.0/README.md

@@ -0,0 +1,178 @@
+# universalmotif (Python)
+
+A Python package for working with sequence motifs: creating them, converting
+between their representations, reading and writing them in the common file
+formats, and using them to scan, compare and test sequences. It is a port of
+the [universalmotif](https://bioconductor.org/packages/universalmotif/)
+R/Bioconductor package, built on its Rust version,
+[universalmotif-rs](https://github.com/bjmt/universalmotif-rs), which does
+the heavy lifting, so most of it is quick and can use several threads.
+Motifs are `Motif` objects, matrices come back as numpy arrays, and tables
+come back as [polars](https://pola.rs/) DataFrames.
+
+The [documentation](https://bjmt.github.io/universalmotif-py/) has guides
+covering everything from motif basics to a full ChIP-seq analysis, and a
+reference for every function. The package is at an early version, and its
+interface may still change.
+
+## Installation
+
+The package needs Python 3.10 or later and can be installed from PyPI:
+
+```sh
+pip install universalmotif
+```
+
+Wheels are built for Linux (x86_64 and aarch64), macOS (Intel and Apple
+Silicon) and Windows (x86_64). Elsewhere pip builds the package from source,
+which needs a [Rust toolchain](https://rustup.rs/).
+
+The only required dependencies are numpy and polars. Everything else is an
+optional extra, needed only by the functions that use it, so that for
+example `pip install "universalmotif[plot]"` adds matplotlib for drawing
+logos:
+
+| Extra | Brings in | For |
+| --- | --- | --- |
+| `plot` | matplotlib | logos, trees and the other plots |
+| `scipy` | SciPy | sparse motif match matrices |
+| `anndata` | AnnData, SciPy | match matrices stored with single-cell ATAC data |
+| `biopython` | Biopython | converting to and from `Bio.motifs` |
+| `h5py` | h5py | reading TF-MoDISco results |
+| `bigwig` | pybigtools | bigWig signal, and backgrounds matched on it |
+| `pyranges` | PyRanges | converting tables to PyRanges objects |
+| `polars-bio` | polars-bio | preparing tables for polars-bio |
+| `pandas` | pandas, pyarrow | pandas DataFrames, and logomaker export |
+
+## A quick look
+
+Using the example motifs and sequences that come with the package:
+
+```python
+import universalmotif as um
+
+# A motif from a few aligned sites, and its log-odds matrix.
+ap1 = um.create_motif(["TGACTCA", "TGAGTCA", "TGACTAA"], name="AP-1", pseudocount=1)
+print(um.convert_type(ap1, "PWM").matrix)
+
+# Scan sequences for the example motifs, and test them for enrichment
+# against a set of control sequences.
+motifs = um.example_motifs()
+targets = um.example_sequences("targets")
+controls = um.example_sequences("controls")
+hits = um.scan_sequences(motifs, targets, pvalue=1e-4)
+enriched = um.enrich_motifs(motifs, targets, controls)
+
+# How similar are the motifs, and what do they look like?
+similar = um.compare_motifs(motifs, compare_to="AP-1")
+um.view_motifs(motifs[:4]).savefig("logos.png")
+
+# Look for new motifs in the targets.
+found = um.motif_finder(targets, controls, seed=1)
+```
+
+## What it can do
+
+- **Motifs:** create them from sites, consensus strings or matrices, convert
+  between counts, probabilities, log-odds, information content and
+  contribution scores, and trim, round, merge, reverse complement and filter
+  them.
+- **Files:** MEME, JASPAR, HOMER, TRANSFAC, CIS-BP, UniPROBE and plain
+  matrices, and FASTA for sequences, gzipped or not.
+- **Databases:** motifs fetched from JASPAR, HOCOMOCO and CIS-BP and kept in
+  a local cache, and conversion to and from Biopython.
+- **Scanning:** exact P-value thresholds, both strands, any alphabet and
+  gapped motifs, with whole genomes scanned from a FASTA file in a few
+  hundred MB.
+- **Comparison:** similarity with P-values, scored either on the overlap or
+  on the whole query, merging of similar motifs, and trees.
+- **Statistics:** enrichment, co-occurrence, positional enrichment,
+  proximity to genomic anchors, composition-matched backgrounds and *de
+  novo* motif discovery.
+- **Genomes:** FASTA, bgzip and 2bit genomes read a piece at a time, the
+  sequences of peaks, bigWig signal over them, and hits moved back to
+  genomic coordinates, with ranges exchanged with PyRanges and polars-bio.
+- **Single-cell ATAC and deep learning:** sparse peak by motif matrices for
+  AnnData and pychromVAR, motifs as convolution filters and back, one-hot
+  sequences, and TF-MoDISco results.
+- **Sequences:** shuffling that keeps k-mer counts, random sequences, k-mer
+  backgrounds, complexity, masking and sliding windows.
+- **Plots:** sequence logos, motif trees and plots of the results above,
+  with motifs shown as logos in Jupyter and SVG logos for reports.
+
+Scanning, comparison, merging, clustering, enrichment and logos work for
+amino acid and custom alphabets as well as DNA and RNA.
+
+## Command line
+
+The package also installs a command line, as both `universalmotif` and
+`umotif`, which runs the main functions on files for shell scripts and
+workflow managers:
+
+```sh
+umotif fetch jaspar --tax-group plants --release 2024 -o jaspar.meme
+umotif extract -g genome.fa.gz -r peaks.narrowPeak -o peaks.fa
+umotif bkg -g genome.fa.gz -r peaks.narrowPeak --seed 1 -o bkg.fa
+umotif enrich jaspar.meme -s peaks.fa -b bkg.fa -p 4 -o enriched.tsv
+```
+
+`umotif --help` lists all 19 commands.
+
+## Differences from the R package
+
+Function names follow the R package, with underscores in place of dots, so
+`min.ic` becomes `min_ic`. Where the R package has both a full and a `_lite`
+version of a function, this package provides the lite one under the plain
+name. Readers always return a list of motifs, and MEME site tables come
+back as polars DataFrames. Functions that use random numbers take a `seed`,
+but seeds do not reproduce the R package's results, since the two use
+different random number generators.
+
+Bugs found in the R package while porting it are fixed here rather than
+reproduced.
+[DIVERGENCES.md](https://github.com/bjmt/universalmotif-rs/blob/main/DIVERGENCES.md)
+in the Rust crate lists the other differences, including the few features
+left out on purpose.
+
+## Documentation
+
+The documentation lives at <https://bjmt.github.io/universalmotif-py/>. It is built with MkDocs from `docs/`,
+with the API reference generated from the docstrings and guides written as
+notebooks. To build it and preview it locally:
+
+```sh
+uv sync --group docs --no-install-project
+uv run --no-sync maturin develop --release
+uv run --no-sync mkdocs serve
+```
+
+## Development
+
+Development uses [uv](https://docs.astral.sh/uv/) and
+[maturin](https://www.maturin.rs/), with the Rust crate checked out next to
+this one, since the package builds against it and the tests read the R
+reference values kept there:
+
+```sh
+git clone https://github.com/bjmt/universalmotif-rs.git
+git clone https://github.com/bjmt/universalmotif-py.git
+cd universalmotif-py
+uv sync --group dev --no-install-project
+uv run --no-sync maturin develop --release
+uv run --no-sync pytest
+```
+
+## Citation
+
+If this package has been useful for your research, please cite the article
+describing universalmotif:
+
+Tremblay BJM (2024). universalmotif: An R package for biological motif
+analysis. *Journal of Open Source Software* **9**, 7012.
+DOI: [10.21105/joss.07012](https://doi.org/10.21105/joss.07012)
+
+## Licence
+
+MIT. The letter shapes used in logos are outlines of the Roboto font,
+released under the Apache License 2.0, and were exported from the R
+package's `fontDFroboto` with `scripts/make_font.R`.

universalmotif-0.1.0/pyproject.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires = ["maturin>=1.9,<2"]
+build-backend = "maturin"
+
+[project]
+name = "universalmotif"
+version = "0.1.0"
+description = "Sequence motif manipulation and analysis, a Python port of universalmotif"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Benjamin Jean-Marie Tremblay" }]
+keywords = ["bioinformatics", "motif", "pwm", "genomics"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Rust",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = ["numpy>=1.24", "polars>=1.0"]
+
+[project.urls]
+Documentation = "https://bjmt.github.io/universalmotif-py/"
+Repository = "https://github.com/bjmt/universalmotif-py"
+Changelog = "https://bjmt.github.io/universalmotif-py/changelog/"
+Issues = "https://github.com/bjmt/universalmotif-py/issues"
+
+[project.scripts]
+universalmotif = "universalmotif._cli:main"
+umotif = "universalmotif._cli:main"
+
+[project.optional-dependencies]
+anndata = ["anndata>=0.10", "scipy>=1.11"]
+bigwig = ["pybigtools>=0.3"]
+biopython = ["biopython>=1.81"]
+h5py = ["h5py>=3.0"]
+pandas = ["pandas>=2.0", "pyarrow>=14"]
+plot = ["matplotlib>=3.8"]
+polars-bio = ["polars-bio>=0.36; python_version >= '3.11' and python_version < '3.15'"]
+pyranges = ["pyranges1>=1.0; python_version >= '3.12'"]
+scipy = ["scipy>=1.11"]
+
+[dependency-groups]
+dev = [
+    "anndata>=0.10",
+    "biopython>=1.81",
+    "h5py>=3.0",
+    "maturin>=1.9,<2",
+    "matplotlib>=3.8",
+    "pandas>=2.0",
+    "polars-bio>=0.36; python_version >= '3.11' and python_version < '3.15'",
+    "pybigtools>=0.3",
+    "pyranges1>=1.0; python_version >= '3.12'",
+    "pytest>=8",
+    "scipy>=1.15.3",
+]
+docs = [
+    "maturin>=1.9,<2",
+    "matplotlib>=3.8",
+    # MkDocs 2 drops the plugin system these rely on.
+    "mkdocs>=1.6,<2",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.27",
+    "mkdocs-jupyter>=0.25",
+    "ipykernel>=6.29",
+    "ruff>=0.6",
+]
+
+[tool.maturin]
+module-name = "universalmotif._core"
+features = ["pyo3/extension-module"]
+# The docs, guides and CI files are not needed to build or use the package.
+exclude = [
+    { path = "docs/**/*", format = "sdist" },
+    { path = "hooks/**/*", format = "sdist" },
+    { path = "scripts/**/*", format = "sdist" },
+    { path = ".github/**/*", format = "sdist" },
+    { path = "mkdocs.yml", format = "sdist" },
+]
+manifest-path = "universalmotif-py/Cargo.toml"
+python-source = "python"
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "python/universalmotif"]
+# Docstring examples run as tests too.
+addopts = "--doctest-modules"
+# The package warns about inputs that silently give empty or odd results, so
+# a warning in a test is an error unless the test expects it.
+filterwarnings = ["error::UserWarning"]