mtrip 0.3.0__tar.gz → 0.4.1__tar.gz

mtrip-0.4.1/.clang-format

@@ -0,0 +1,10 @@
+# C style for lib/. clang-format is pinned in the dev dependency group so that
+# local and CI output match:
+#   uv run clang-format -i lib/*.c lib/*.h
+---
+Language: Cpp
+BasedOnStyle: LLVM
+IndentWidth: 4
+ColumnLimit: 80
+# Preprocessor directives, including "#pragma omp", sit flush left.
+IndentPPDirectives: None

mtrip-0.4.1/.git-blame-ignore-revs

@@ -0,0 +1,5 @@
+# Formatting-only commits; use with: git config blame.ignoreRevsFile .git-blame-ignore-revs
+# ruff format
+3741393ce89326663f4dea0531a5854ddbc9d92d
+# clang-format
+52c6118ba50292c3604fbe6585a649c95d6c1164

mtrip-0.4.1/.gitignore

@@ -0,0 +1,94 @@
+# Prerequisites
+*.d
+
+# Object files
+*.o
+*.ko
+*.obj
+*.elf
+
+# Linker output
+*.ilk
+*.map
+*.exp
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Libraries
+*.lib
+*.a
+*.la
+*.lo
+
+# Shared objects (inc. Windows DLLs)
+*.dll
+*.so
+*.so.*
+*.dylib
+
+# Executables
+*.exe
+*.out
+*.app
+*.i*86
+*.x86_64
+*.hex
+
+# Debug files
+*.dSYM/
+*.su
+*.idb
+*.pdb
+
+# Kernel Module Compile Results
+*.mod*
+*.cmd
+.tmp_versions/
+modules.order
+Module.symvers
+Mkfile.old
+dkms.conf
+
+# Useless data
+*.dat
+*.p
+#
+# These are generated by cython
+bitsnbobs.c
+scipy_comb.c
+triplet_omp_py.c
+
+# Goes without saying :)
+__pycache__/
+build/
+dist/
+.*_coal_unit 
+notebooks/
+.ipynb_checkpoints/
+*.swp
+*.spec
+src/mtrip.egg-info/
+*.swo
+.condaauto
+
+# Python environments and tool caches
+.venv/
+venv/
+.ruff_cache/
+.pytest_cache/
+*.egg-info/
+
+# CMake build output (in-source builds)
+CMakeFiles/
+CMakeCache.txt
+cmake_install.cmake
+
+# Wheel builds
+wheelhouse/
+
+# Editors
+.idea/
+.vscode/
+.DS_Store

mtrip-0.4.1/CLAUDE.md

@@ -0,0 +1,109 @@
+# CLAUDE.md
+
+Guidance for Claude Code (claude.ai/code) when working in this repository.
+
+## Project
+
+`mtrip` finds exact median triplet trees: every rooted species tree that shares
+the most triplets with a set of gene trees. It implements RTIST (Zhelezov &
+Degnan, Bioinformatics 2022). The repo is `rtist`, the PyPI package and the
+commands are `mtrip`. License: GPL-3.0-only.
+
+Hybrid C / Cython / Python, built with CMake through scikit-build-core, and
+developed with uv. Supported: Linux (glibc and musl) and macOS, x86_64 and
+arm64, Python 3.10+. No Windows.
+
+## Commands
+
+```bash
+uv sync                                     # dev env in .venv (editable install + dev tools)
+uv run pytest                               # all tests
+uv run pytest tests/test_cli.py -k quiet    # a subset
+uv run mtrip examples/example_5tips.nwk -n -p
+uv run ruff format && uv run ruff check     # Python
+uv run clang-format -i lib/*.c lib/*.h      # C (LLVM style, 4 spaces; see .clang-format)
+uv build                                    # sdist + wheel into dist/
+```
+
+`uv run` rebuilds the compiled modules automatically when a C, header, `.pyx`
+or CMake file changes (`[tool.uv] cache-keys` in pyproject.toml). Build options:
+`-Ccmake.define.MTRIP_OPENMP=OFF` (serial build) and
+`-Ccmake.define.MTRIP_NATIVE=ON` (host-tuned, non-portable); in CI the serial
+build uses `SKBUILD_CMAKE_DEFINE=MTRIP_OPENMP=OFF`. On macOS, OpenMP comes from
+Homebrew's `libomp`, found automatically.
+
+ruff and clang-format are pinned to exact versions in the `dev` dependency
+group, and CI checks formatting with those versions; run them through `uv run`
+so your output matches CI.
+
+## Layout
+
+- `lib/`: C core, built as the static library `ctriplet` (`lib/CMakeLists.txt`,
+  buildable on its own). `weights_omp.c` has the OpenMP-parallel
+  `fill_compressed_weight_representation`; `lookup_table.c` has the base-2 to
+  base-3 ("two2three") index table. Every OpenMP call is guarded by
+  `#ifdef _OPENMP` so the code also builds serially.
+- `CMakeLists.txt`: transpiles and builds the three Cython extensions
+  (`mtrip.triplet_omp` from `triplet_omp_py.pyx`, `mtrip.bitsnbobs`,
+  `mtrip.scipycomb` from `scipy_comb.pyx`) with cython-cmake, and links
+  `triplet_omp` against `ctriplet`.
+- `src/mtrip/median_tree_reconstruction.py`: the algorithm, in Python.
+- `src/mtrip/cli/`: the three commands, `find.py` (`mtrip`), `suboptimal.py`
+  (`mtrip-suboptimal`), `combine.py` (`mtrip-combine`), with shared code in
+  `_common.py` (argument parsing, logging setup, colors, weights-file I/O).
+- `tests/`: pytest. `brute.py` has independent brute-force reference
+  implementations; `common.py` has shared helpers (import it, there is no
+  conftest). Examples in `examples/` double as test inputs.
+- `.github/workflows/`: `ci.yml` (lint + tests on 4 platforms + a no-OpenMP
+  build), `wheels.yml` (cibuildwheel; config in `[tool.cibuildwheel]`),
+  `publish.yml` (manual; uploads to PyPI/TestPyPI via Trusted Publishing after
+  CI and wheels pass).
+
+## Algorithm pipeline
+
+1. **Parse** (`simplify_nwk`, `get_names`): strip branch lengths and internal
+   labels; map each taxon to a bit, so a set of taxa is an int bitmask.
+2. **Bipartitions** (`get_biparts`, `splitter`): each internal node of a gene
+   tree is a split `(a, b)` of disjoint bitmasks. `get_weights` (or
+   `get_weights_parallel`, multiprocessing) counts them over all gene trees;
+   `get_subset_biparts` groups them by `a | b`.
+3. **Weight expansion** (C): `py_compressed_weight_rep` calls
+   `fill_compressed_weight_representation`, which computes, for every possible
+   bipartition of every subset, the number of gene-tree triplets it agrees
+   with. The array is indexed by a base-3 encoding of `(a, b)` (each taxon is
+   in a, in b, or neither), so it has about 2·3^(n−1) entries.
+4. **Subset DP** (`get_stack`): over subsets in order of size (Gosper's hack,
+   `get_binary_subsets`), the best score of each subset is the best over its
+   splits of weight + best(a) + best(b). Every optimal split is kept.
+5. **Reconstruction** (`get_all_trees`): walk the kept splits from the full set
+   down to leaves to enumerate *all* optimal trees.
+
+`process_nwks` does steps 1–3; `median_triplet_trees` runs everything.
+`mtrip-suboptimal` reuses the saved weights (step 3 output) to sample trees
+whose score is within a fraction of the best.
+
+## Conventions
+
+- **stdout is for results only** (trees from `-p`, `mtrip-suboptimal`'s
+  output). Everything else goes through `logging` (loggers under `mtrip`;
+  the commands use `mtrip.cli`) to stderr. Library code never prints.
+- Commands exit 0 on success, 1 on runtime errors, 2 on usage errors (use
+  `parser.error`).
+- Color only when stderr is a terminal and `NO_COLOR` is unset (`style()` in
+  `_common.py`).
+- Weights files are pickles with a fixed layout (`save_weights`/`load_weights`);
+  keep it backward compatible so old `.p` files still load.
+- Results must not depend on the thread count or on whether OpenMP is used; the
+  tests check this against brute force.
+- The version lives only in `pyproject.toml`; `mtrip.__version__` reads it from
+  the installed metadata.
+- cysignals' `sig_on()` is compiled into `triplet_omp`, and its ABI changed in
+  1.12.6, so the module only works with cysignals from the side it was built
+  against. The cysignals requirements in `[build-system]` and `dependencies`
+  must stay identical (split at Python 3.13; see the comment in
+  pyproject.toml). The wheel tests install dependencies from wheels only, so a
+  pin without wheels for some platform fails there.
+
+## Known limitations
+
+- 20 or more taxa overflow the 32-bit indices in C (2·3^19 > INT_MAX).

mtrip-0.4.1/CMakeLists.txt

@@ -0,0 +1,47 @@
+# Builds the mtrip Python package's compiled modules. Driven by
+# scikit-build-core: build with `uv build` or `pip install .`, not by running
+# cmake directly. (The C library alone can be built with cmake; see
+# lib/CMakeLists.txt.)
+cmake_minimum_required(VERSION 3.15...3.31)
+project(mtrip LANGUAGES C)
+
+if(NOT SKBUILD)
+    message(WARNING "This project is meant to be built through scikit-build-core, e.g. `uv build` or `pip install .`")
+endif()
+
+find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)
+find_package(Cython MODULE REQUIRED VERSION 3.0)
+include(UseCython)
+
+add_subdirectory(lib)
+
+# cysignals ships its .pxd files and C headers inside its Python package.
+execute_process(
+    COMMAND "${Python_EXECUTABLE}" -c "import cysignals, os; print(os.path.dirname(cysignals.__file__))"
+    OUTPUT_VARIABLE CYSIGNALS_DIR
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    RESULT_VARIABLE _cysignals_result
+)
+if(NOT _cysignals_result EQUAL 0)
+    message(FATAL_ERROR "mtrip: cysignals must be importable at build time")
+endif()
+get_filename_component(CYSIGNALS_PARENT_DIR "${CYSIGNALS_DIR}" DIRECTORY)
+
+# mtrip_cython_module(<module> <pyx file>): build src/mtrip/<pyx> as mtrip.<module>.
+function(mtrip_cython_module module pyx)
+    cython_transpile("src/mtrip/${pyx}"
+        LANGUAGE C
+        MODULE_NAME "mtrip.${module}"
+        INCLUDE_DIRECTORIES "${CYSIGNALS_PARENT_DIR}"
+        OUTPUT_VARIABLE c_source
+    )
+    python_add_library(${module} MODULE "${c_source}" WITH_SOABI)
+    target_link_libraries(${module} PRIVATE mtrip_build_flags)
+    install(TARGETS ${module} DESTINATION mtrip)
+endfunction()
+
+mtrip_cython_module(bitsnbobs bitsnbobs.pyx)
+mtrip_cython_module(scipycomb scipy_comb.pyx)
+mtrip_cython_module(triplet_omp triplet_omp_py.pyx)
+target_link_libraries(triplet_omp PRIVATE ctriplet)
+target_include_directories(triplet_omp PRIVATE "${CYSIGNALS_DIR}")

mtrip-0.4.1/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: mtrip
+Version: 0.4.1
+Summary: Find exact median triplet trees (phylogenetics)
+Author-Email: Gleb Zhelezov <gleb@glebzh.com>
+License-Expression: GPL-3.0-only
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Project-URL: Homepage, https://github.com/glebzhelezov/rtist
+Project-URL: Issues, https://github.com/glebzhelezov/rtist/issues
+Requires-Python: >=3.10
+Requires-Dist: cysignals<1.12.6,>=1.12.3; python_version < "3.13"
+Requires-Dist: cysignals>=1.13; python_version >= "3.13"
+Description-Content-Type: text/markdown
+
+# mtrip
+
+mtrip finds exact median triplet trees. You give it a set of rooted gene trees,
+and it finds every species tree that shares as many rooted triplets with them
+as possible. The paper below calls the method RTIST; the package and its
+commands are called `mtrip`.
+
+> Gleb Zhelezov and James H. Degnan. [*Trying out a million genes to find the
+> perfect pair with RTIST*](https://academic.oup.com/bioinformatics/article/38/14/3565/6596045).
+> Bioinformatics 38(14):3565-3573, 2022.
+
+## Installation
+
+```bash
+pip install mtrip
+```
+
+or run it without installing, using [uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx mtrip genes.nwk
+```
+
+pip installs a prebuilt wheel on Linux (x86_64 and arm64, Alpine included) and
+on macOS 11 or newer (Intel and Apple Silicon), for Python 3.10 and up. The
+wheels come with OpenMP built in, so mtrip uses all your CPU cores and you
+don't need to install anything else. On Windows, use
+[WSL](https://learn.microsoft.com/windows/wsl/). Anywhere else, pip compiles
+mtrip from source (see [Building from source](#building-from-source)).
+
+## Quick start
+
+`genes.nwk` has one rooted gene tree per line, in Newick format:
+
+```
+((A,B),(C,(D,E)));
+(((A,C),B),(D,E));
+(((A,D),B),(C,E));
+((A,E),((B,C),D));
+(A,(B,((C,D),E)));
+```
+
+```console
+$ mtrip genes.nwk -n -p
+...
+Best possible triplet count is 26, out of a maximum of 50.
+...
+((A,B),((C,D),E));
+((A,B),(C,(D,E)));
+```
+
+Each of these trees shares 26 triplets with the gene trees, and no tree shares
+more, so both are median triplet trees. When several trees tie for the best
+score, mtrip reports all of them.
+
+## Commands
+
+### `mtrip`: median triplet trees
+
+```bash
+mtrip genes.nwk                 # writes the trees to out_genes.nwk
+mtrip genes.nwk trees.nwk       # ...or to a file you name
+mtrip genes.nwk -n -p           # print the trees instead of saving them
+mtrip genes.nwk -b weights.p    # also save the weights, for the commands below
+```
+
+The input file has one Newick string per line. mtrip ignores branch lengths
+and internal node labels, and skips blank lines and lines starting with `#`.
+By default it uses all CPUs; `-t N` limits it to N threads.
+
+### `mtrip-suboptimal`: near-optimal trees
+
+This samples trees whose score is close to the best one, using a weights file
+saved with `mtrip -b`:
+
+```console
+$ mtrip-suboptimal weights.p -f 0.9 -n 5
+#26
+((A,B),((C,D),E));
+#25
+((A,B),(D,(C,E)));
+#24
+(A,(B,(C,(D,E))));
+...
+```
+
+The trees come out highest score first, each with its score on the line
+above. Set the cutoff with `-f`, as a fraction of the best score (default
+0.99), or with `-m`, as an absolute score. `-n` caps the number of trees
+(default 100), and `-s` seeds the random sampling.
+
+### `mtrip-combine`: combine runs
+
+Weights from separate runs (for example, on parts of a large data set) add up.
+Combine them, then work with the result as if it came from one run:
+
+```bash
+mtrip part1.nwk -b part1.p
+mtrip part2.nwk -b part2.p
+mtrip-combine part1.p part2.p -o all.p
+mtrip-suboptimal all.p -f 1         # the median trees of the combined data
+```
+
+All inputs must have the same taxa.
+
+> [!NOTE]
+> Weights files are Python pickles, and loading a pickle can run arbitrary
+> code. Only load weights files you created or trust. `mtrip-suboptimal` asks
+> before loading one; `-y` skips the question.
+
+All three commands take `-h` (the full list of options), `-v` (version) and
+`-q` (quiet).
+
+## Output and scripting
+
+The commands write only their results to standard output: the trees from
+`-p`, and the scored trees from `mtrip-suboptimal`. Progress and other messages
+go to standard error, so you can redirect or pipe the results:
+
+```bash
+mtrip genes.nwk -n -p > median_trees.nwk
+mtrip genes.nwk -n -p -q | some_other_tool    # -q: no progress messages
+```
+
+Messages are in color on a terminal, unless the `NO_COLOR` environment
+variable is set. The exit code is `0` on success, `1` on an error such as
+unreadable input or a malformed Newick string, and `2` on invalid command-line
+arguments.
+
+## Limits
+
+The search is exact, so its cost grows exponentially with the number of taxa
+*n* (it stores about 2·3<sup>n−1</sup> weights): about 1 GB of memory at 18
+taxa and about 3 GB at 19. The number of gene trees matters much less. Inputs
+with 20 or more taxa are not supported yet.
+
+## Building from source
+
+You need a C compiler and CMake 3.15 or newer. The build fetches its Python
+build dependencies (Cython, cysignals, scikit-build-core) itself.
+
+OpenMP is optional but makes the main computation parallel. On Linux, GCC
+supports it out of the box. On macOS, install `libomp` with Homebrew
+(`brew install libomp`); the build finds it automatically. Without OpenMP the
+build still succeeds and runs single-threaded.
+
+```bash
+git clone https://github.com/glebzhelezov/rtist.git
+cd rtist
+pip install .
+```
+
+Build options, passed through pip (or `uv pip`) with `-C`:
+
+- `-Ccmake.define.MTRIP_NATIVE=ON` tunes the code for the CPU you're building
+  on. It runs faster, but only on CPUs like yours.
+- `-Ccmake.define.MTRIP_OPENMP=OFF` builds without OpenMP even if it's
+  available.
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync                                    # .venv with mtrip (editable) and dev tools
+uv run pytest                              # test suite
+uv run mtrip examples/example_5tips.nwk -n -p
+uv run ruff format && uv run ruff check    # Python formatting and lint
+uv run clang-format -i lib/*.c lib/*.h     # C formatting
+```
+
+Edits to `.py` files take effect immediately. When a C, `.pyx` or CMake file
+changes, the next `uv run` rebuilds the compiled modules.
+
+On every push, GitHub Actions runs the lint checks and the tests on Linux and
+macOS (x86_64 and arm64), and builds and tests the wheels. The `Publish`
+workflow uploads releases to PyPI using Trusted Publishing.
+
+## Citation
+
+```bibtex
+@article{zhelezov2022trying,
+  title={Trying out a million genes to find the perfect pair with {RTIST}},
+  author={Zhelezov, Gleb and Degnan, James H},
+  journal={Bioinformatics},
+  volume={38},
+  number={14},
+  pages={3565--3573},
+  year={2022},
+  publisher={Oxford University Press}
+}
+```
+
+## License
+
+GPL-3.0. See [LICENSE](https://github.com/glebzhelezov/rtist/blob/HEAD/LICENSE).

mtrip-0.4.1/README.md

@@ -0,0 +1,196 @@
+# mtrip
+
+mtrip finds exact median triplet trees. You give it a set of rooted gene trees,
+and it finds every species tree that shares as many rooted triplets with them
+as possible. The paper below calls the method RTIST; the package and its
+commands are called `mtrip`.
+
+> Gleb Zhelezov and James H. Degnan. [*Trying out a million genes to find the
+> perfect pair with RTIST*](https://academic.oup.com/bioinformatics/article/38/14/3565/6596045).
+> Bioinformatics 38(14):3565-3573, 2022.
+
+## Installation
+
+```bash
+pip install mtrip
+```
+
+or run it without installing, using [uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx mtrip genes.nwk
+```
+
+pip installs a prebuilt wheel on Linux (x86_64 and arm64, Alpine included) and
+on macOS 11 or newer (Intel and Apple Silicon), for Python 3.10 and up. The
+wheels come with OpenMP built in, so mtrip uses all your CPU cores and you
+don't need to install anything else. On Windows, use
+[WSL](https://learn.microsoft.com/windows/wsl/). Anywhere else, pip compiles
+mtrip from source (see [Building from source](#building-from-source)).
+
+## Quick start
+
+`genes.nwk` has one rooted gene tree per line, in Newick format:
+
+```
+((A,B),(C,(D,E)));
+(((A,C),B),(D,E));
+(((A,D),B),(C,E));
+((A,E),((B,C),D));
+(A,(B,((C,D),E)));
+```
+
+```console
+$ mtrip genes.nwk -n -p
+...
+Best possible triplet count is 26, out of a maximum of 50.
+...
+((A,B),((C,D),E));
+((A,B),(C,(D,E)));
+```
+
+Each of these trees shares 26 triplets with the gene trees, and no tree shares
+more, so both are median triplet trees. When several trees tie for the best
+score, mtrip reports all of them.
+
+## Commands
+
+### `mtrip`: median triplet trees
+
+```bash
+mtrip genes.nwk                 # writes the trees to out_genes.nwk
+mtrip genes.nwk trees.nwk       # ...or to a file you name
+mtrip genes.nwk -n -p           # print the trees instead of saving them
+mtrip genes.nwk -b weights.p    # also save the weights, for the commands below
+```
+
+The input file has one Newick string per line. mtrip ignores branch lengths
+and internal node labels, and skips blank lines and lines starting with `#`.
+By default it uses all CPUs; `-t N` limits it to N threads.
+
+### `mtrip-suboptimal`: near-optimal trees
+
+This samples trees whose score is close to the best one, using a weights file
+saved with `mtrip -b`:
+
+```console
+$ mtrip-suboptimal weights.p -f 0.9 -n 5
+#26
+((A,B),((C,D),E));
+#25
+((A,B),(D,(C,E)));
+#24
+(A,(B,(C,(D,E))));
+...
+```
+
+The trees come out highest score first, each with its score on the line
+above. Set the cutoff with `-f`, as a fraction of the best score (default
+0.99), or with `-m`, as an absolute score. `-n` caps the number of trees
+(default 100), and `-s` seeds the random sampling.
+
+### `mtrip-combine`: combine runs
+
+Weights from separate runs (for example, on parts of a large data set) add up.
+Combine them, then work with the result as if it came from one run:
+
+```bash
+mtrip part1.nwk -b part1.p
+mtrip part2.nwk -b part2.p
+mtrip-combine part1.p part2.p -o all.p
+mtrip-suboptimal all.p -f 1         # the median trees of the combined data
+```
+
+All inputs must have the same taxa.
+
+> [!NOTE]
+> Weights files are Python pickles, and loading a pickle can run arbitrary
+> code. Only load weights files you created or trust. `mtrip-suboptimal` asks
+> before loading one; `-y` skips the question.
+
+All three commands take `-h` (the full list of options), `-v` (version) and
+`-q` (quiet).
+
+## Output and scripting
+
+The commands write only their results to standard output: the trees from
+`-p`, and the scored trees from `mtrip-suboptimal`. Progress and other messages
+go to standard error, so you can redirect or pipe the results:
+
+```bash
+mtrip genes.nwk -n -p > median_trees.nwk
+mtrip genes.nwk -n -p -q | some_other_tool    # -q: no progress messages
+```
+
+Messages are in color on a terminal, unless the `NO_COLOR` environment
+variable is set. The exit code is `0` on success, `1` on an error such as
+unreadable input or a malformed Newick string, and `2` on invalid command-line
+arguments.
+
+## Limits
+
+The search is exact, so its cost grows exponentially with the number of taxa
+*n* (it stores about 2·3<sup>n−1</sup> weights): about 1 GB of memory at 18
+taxa and about 3 GB at 19. The number of gene trees matters much less. Inputs
+with 20 or more taxa are not supported yet.
+
+## Building from source
+
+You need a C compiler and CMake 3.15 or newer. The build fetches its Python
+build dependencies (Cython, cysignals, scikit-build-core) itself.
+
+OpenMP is optional but makes the main computation parallel. On Linux, GCC
+supports it out of the box. On macOS, install `libomp` with Homebrew
+(`brew install libomp`); the build finds it automatically. Without OpenMP the
+build still succeeds and runs single-threaded.
+
+```bash
+git clone https://github.com/glebzhelezov/rtist.git
+cd rtist
+pip install .
+```
+
+Build options, passed through pip (or `uv pip`) with `-C`:
+
+- `-Ccmake.define.MTRIP_NATIVE=ON` tunes the code for the CPU you're building
+  on. It runs faster, but only on CPUs like yours.
+- `-Ccmake.define.MTRIP_OPENMP=OFF` builds without OpenMP even if it's
+  available.
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync                                    # .venv with mtrip (editable) and dev tools
+uv run pytest                              # test suite
+uv run mtrip examples/example_5tips.nwk -n -p
+uv run ruff format && uv run ruff check    # Python formatting and lint
+uv run clang-format -i lib/*.c lib/*.h     # C formatting
+```
+
+Edits to `.py` files take effect immediately. When a C, `.pyx` or CMake file
+changes, the next `uv run` rebuilds the compiled modules.
+
+On every push, GitHub Actions runs the lint checks and the tests on Linux and
+macOS (x86_64 and arm64), and builds and tests the wheels. The `Publish`
+workflow uploads releases to PyPI using Trusted Publishing.
+
+## Citation
+
+```bibtex
+@article{zhelezov2022trying,
+  title={Trying out a million genes to find the perfect pair with {RTIST}},
+  author={Zhelezov, Gleb and Degnan, James H},
+  journal={Bioinformatics},
+  volume={38},
+  number={14},
+  pages={3565--3573},
+  year={2022},
+  publisher={Oxford University Press}
+}
+```
+
+## License
+
+GPL-3.0. See [LICENSE](https://github.com/glebzhelezov/rtist/blob/HEAD/LICENSE).