SNPio: A Python API for Population Genomic Data I/O, Filtering, Analysis, and Encoding

SNPio Logo

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!

🙏 Acknowledgments

Thanks for using SNPio. We hope it facilitates your population genomic research. Feel free to reach out with questions or feedback!

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.7.4)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for btmartin721 from gravatar.com btmartin721

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Drs. Bradley T. Martin and Tyler K. Chafin

License expression

GPL-3.0-or-later
View SPDX License List

Requires

Python <3.13, >=3.11

Provides Extra

docs dev ld-validation

Tags

genomics bioinformatics population genetics SNP VCF PHYLIP STRUCTURE missing data filtering filter MAF minor allele frequency MAC minor allele count biallelic monomorphic singleton population structure d-statistics Fst multiqc encoding

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

snpio-1.7.3.tar.gz (2.0 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

snpio-1.7.3-py3-none-any.whl (2.0 MB view details)

Uploaded Python 3

File details

Details for the file snpio-1.7.3.tar.gz.

File metadata

  • Download URL: snpio-1.7.3.tar.gz
  • Upload date:
  • Size: 2.0 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.12.13

File hashes

Hashes for snpio-1.7.3.tar.gz
Algorithm Hash digest
SHA256 c36507f800c49144b3e8e4760d2437aab4c7811f8c1ce0687b4eee3166bfa029
MD5 7e18dd5e800d8457fdccd932c5e2223e
BLAKE2b-256 fcaf93bf6c3874000f126b91ae5af18749404b09c17f16f0844e6b2abcc185cf

See more details on using hashes here.

File details

Details for the file snpio-1.7.3-py3-none-any.whl.

File metadata

  • Download URL: snpio-1.7.3-py3-none-any.whl
  • Upload date:
  • Size: 2.0 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.12.13

File hashes

Hashes for snpio-1.7.3-py3-none-any.whl
Algorithm Hash digest
SHA256 c56cca9645b4abf33526b3f00dd918503c35b97a01d36a71c3c15d947fa1f765
MD5 865e2aa0edf336e9e04802b15ec4b4a7
BLAKE2b-256 aec5c9f6b4a43861dbd722caaa6016b08c374dd607df26db4686b90ce2ba7fa2

See more details on using hashes here.

Release history Release notifications | RSS feed

1.7.4

2 files

This release

1.7.3 This release

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

1.6.16

2 files

1.6.15

2 files

1.6.14

2 files

1.6.13

2 files

1.6.12

2 files

1.6.11

2 files

1.6.10

2 files

1.6.9

2 files

1.6.8

2 files

1.6.7

2 files

1.6.6

2 files

1.6.5

2 files

1.6.4

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.15

2 files

1.5.14

2 files

1.5.13

2 files

1.5.12

2 files

1.5.11

2 files

1.5.10

2 files

1.5.9

2 files

1.5.8

2 files

1.5.7

2 files

1.5.6

2 files

1.5.5

2 files

1.5.4

2 files

1.5.3

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.0

2 files

1.3.29

2 files

1.3.28

2 files

1.3.27

2 files

1.3.26

2 files

1.3.23

2 files

1.3.22

2 files

1.3.21

2 files

1.3.18

2 files

1.3.17

2 files

1.3.16

2 files

1.3.15

2 files

1.3.13

2 files

1.3.11

2 files

1.3.9

2 files

1.3.7

2 files

1.3.6

2 files

1.3.5

2 files

1.3.4

2 files

1.3.3

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.45

2 files

1.2.44

2 files

1.2.20

2 files

1.2.19

2 files

1.2.18

2 files

1.2.17

2 files

1.2.16

2 files

1.2.15

2 files

1.2.14

2 files

1.2.13

2 files

1.2.12

2 files

1.2.11

2 files

1.2.10

2 files

1.2.9

2 files

1.2.8

2 files

1.2.7

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1.1

2 files

1.2.1

2 files

1.1.4

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

3 files

1.1.0

2 files

1.0.6.2

2 files

1.0.6

2 files

1.0.5.2

2 files

1.0.5.1

2 files

1.0.5

2 files

1.0.4.3

2 files

1.0.4.2

2 files

1.0.4.1

2 files

1.0.4

2 files

1.0.3.3

2 files

1.0.3.2

2 files

1.0.3.1

2 files

1.0.2.2

2 files

1.0.2.1

2 files

1.0.2.0

2 files

1.0.1.2

2 files

1.0.1.1

2 files

1.0.1

4 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page