SNPio: A Python API for Population Genomic Data I/O, Filtering, Analysis, and Encoding
SNPio is a Python package designed to streamline the process of reading, filtering, encoding, and analyzing genotype alignments. It supports VCF, PHYLIP, STRUCTURE, and GENEPOP file formats, and provides high-level tools for visualization, downstream machine learning analysis, and population genetic inference.
SNPio Includes:
- File I/O (VCFReader, PhylipReader, StructureReader, GenePopReader)
- Genotype filtering (NRemover2)
- Genotype encoding for AI & machine learning applications (GenotypeEncoder)
- Population genetic statistics & Principal Component Analysis (PopGenStatistics)
- Finite-sample-unbiased unphased LD and LD-based recent effective population size (Ne), with grouped-locus bootstrap intervals and validation evidence
- Patterson, partitioned, and DFOIL statistics with random, deterministic least-missing, all-sample, or explicit individual selection
- Artifact-aware output organization and interactive MultiQC reporting
- Experimental: Phylogenetic tree parsing (TreeParser)
📖 Full Documentation
Detailed API usage, tutorials, and examples are available in the Documentation
🔧 Installation
You can install SNPio using one of the following methods:
✅ Pip Installation
python3 -m venv snpio-env
source snpio-env/bin/activate
pip install snpio
✅ Conda Installation
conda create -n snpio-env python=3.12
conda activate snpio-env
conda install -c btmartin721 snpio
🐳 Docker
To run the Docker image interactively in a terminal, run the following commands:
docker pull btmartin721/snpio:latest
docker run -it btmartin721/snpio:latest
If you'd like to run SNPio in a jupyter notebook, instructions to do so in the docker container will be printed to the terminal.
Note: All three installation versions (pip, conda, docker) are actively maintained and kept up-to-date with CI/CD routines.
Note: SNPio supports Unix-based systems. Windows users should install via WSL.
🚀 Getting Started
Import Modules
from snpio import (
NRemover2, VCFReader, PhylipReader, StructureReader,
GenePopReader, GenotypeEncoder, PopGenStatistics
)
Load Genotype Data (VCF Example)
vcf = "snpio/example_data/vcf_files/phylogen_subset14K_sorted.vcf.gz"
popmap = "snpio/example_data/popmaps/phylogen_nomx.popmap"
gd = VCFReader(
filename=vcf,
popmapfile=popmap,
force_popmap=True,
verbose=True,
plot_format="png",
prefix="snpio_example"
)
You can also specify include_pops and exclude_pops to control population-level filtering.
LD and Recent Effective Population Size
from snpio import PopGenStatistics
ld = PopGenStatistics(gd).calculate_linkage_disequilibrium(
n_bootstraps=200,
n_jobs=-1,
max_pairs=1_000_000,
seed=42,
)
print(ld.summary[["Population", "r2D", "rDz", "Ne"]])
The returned scientific table represents non-estimable Ne values as NaN.
The MultiQC population summary adds a human-readable Ne_Status column.
For ordinary VCF input, SNPio infers chromosome or scaffold groups and uses
only between-group locus pairs. Coordinate-free data must provide explicit
locus_groups or deliberately set assume_unlinked=True. See the
LD method guide
and validation protocol.
Output Layout
SNPio separates generated data, logs, MultiQC bundles, plots, and tabular
reports under <prefix>_output/. Results derived from an NRemover2 object
are placed under plots/nremover/<operation>/ and
reports/nremover/<operation>/; VCF metadata caches use data/vcf/ with
independent filtered states under data/vcf/nremover/.
🧪 Development Notes
To run the unit tests:
python -m pip install -e '.[dev]'
python -m pytest tests/
The optional forward-time LD calibration dependencies are isolated from the runtime installation:
python -m pip install -e '.[dev,ld-validation]'
🧾 License and Citation
SNPio is licensed under the GPL-3.0 License.
Please cite:
Martin, B. T., Monaco, D. R., Sharabi, N., Mussmann, S. M., and Chafin, T. K. (2026). SNPio: a Python interface for population genomic data processing. BMC Bioinformatics. https://doi.org/10.1186/s12859-026-06546-5
When reporting unphased LD or LD-based recent Ne, also cite Ragsdale and Gravel (2020), Molecular Biology and Evolution, 37(3), 923–932.
🤝 Contributing
We welcome community contributions!
- Report bugs or request features on GitHub Issues
- Submit a pull request
- See CONTRIBUTING.md for contributing guidelines.
🙏 Acknowledgments
Thanks for using SNPio. We hope it facilitates your population genomic research. Feel free to reach out with questions or feedback!
1 maintainer
Metadata
1 maintainer
Release files for snpio 1.7.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| snpio-1.7.7.tar.gz | 2.0 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| snpio-1.7.7-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 4.0 MB
Release files / snpio-1.7.7.tar.gz
| Download URL | snpio-1.7.7.tar.gz |
|---|---|
| Size | 2.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b34b773d4b7b90c4172f22fcc962ae31e9a9ecfc5d92789b560d2130ce1fe24e
|
|
BLAKE2b-256 checksum How to use checksums |
36df9cb749301f594fda05469390eef966a4a32da548a01c03a85da37ed54965
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / snpio-1.7.7-py3-none-any.whl
| Download URL | snpio-1.7.7-py3-none-any.whl |
|---|---|
| Size | 2.0 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
52cbcbba17e17f7dfc3f2742062bdf74714b68be9c1e1480f25ad6234a4bbf65
|
|
BLAKE2b-256 checksum How to use checksums |
5badf1ce6a733c00ce1986d3f7cd4fa3962c5fb20eed3be5cb521630d9117b7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
