mgnipy 0.1.1

MGni.py: A Python Wrapper for the MGnify API

MGni.py

MGni.py (pronounced MAG-nee-pie) is a Python wrapper for the MGnify API. It provides a high-level, Pythonic interface to query metagenomics data and metadata from the MGnify database.

Features

• Simple, Pythonic API — Query MGnify studies, samples, analyses, etc. using an intuitive syntax
• Sync and Async support — Built on httpx with async/await support
• Data export — Multiple output formats including pandas and polars DataFrames
• Caching — Option for disk caching to reduce redundant API calls and allow resuming

Available API Endpoints

• Studies: MGnify studies (collections of samples, runs, assemblies and analyses derived from ENA studies/projects).
• Samples: MGnify samples (based on ENA/BioSamples; individual biological samples).
• Runs: Sequencing runs (ENA run accessions; individual sequencing runs of a sample).
• Assemblies: Metagenome assemblies (equivalent to ENA assemblies for one or more runs).
• Analyses: Pipeline analyses (results of running MGnify pipelines on runs or assemblies; includes taxonomic and functional annotations).
• Publications: Publications that describe or analyse MGnify Studies/datasets.
• Genomes: Annotated draft genomes (isolates or MAGs) arranged in biome-specific catalogues.
• Biomes: List all biomes in the MGnify database.

Note on private data:

• To access your private data in any of these API endpoints you just need your MGnify user and password to obtain a valid sliding auth token via the MGnify Authentication endpoints.
• for example you can put your login credentials in a .env file in your working directory (see .env.example) and
• mgnipy.MGnipyConfig takes care of getting and caching the auth token so that you can easily access your private data using MGni.py 🎉

Installation

From PyPI

pip install mgnipy

Development installation

git clone https://github.com/EBI-Metagenomics/mgnipy.git
cd mgnipy
uv sync --all-groups  # or: pip install -e ".[dev,docs]"

Quick Start

Initialize and explore

from mgnipy import MGnipy

# Create the main client, with default configuration
mg = MGnipy()

# See available endpoints
mg.list_resources()

Query resources with filtering

# Search for studies keyword
studies = mg.studies(
    search="disease"
)

# Can preview requests before fetching
studies.explain()

# get page by page via .get(), getting 3 pages
for _ in range(3)
    studies.get()

# or via .page(), getting another 3 pages
for i in range(4,7):
    studies.page(i)

# OR potentially all at once in large batches (also async option .abulk_fetch())
studies.bulk_fetch()

Multiple output formats

pd_metadata = studies.to_df()

# As polars DataFrame
pl_metadata = studies.to_polars()

# as json
json_metadata = studies.to_json()

Downloading the analyzed data

# accessing the mgazine of datasets
mgazine = studies.datasets

# preview
print(mgazine)

# download file by file 
mgazine.download(to_dir="downloads_folder", alias="mgnify_file_alias.fasta.gz")

# or download all 
mgazine.download_all(to_dir="downloads_folder")

Additional Documentation

• MGnify API Docs
• openapi-python-client
• package docs

Development

see Contributing.md

License

TODO

Citation

TODO