MGni.py

MGni.py ('mæɡ-ni-paɪ') is a lightweight python client and toolkit for the MGnify API.

Contents

• Features
• Available API Endpoints
• Installation
• Quick Start
• Additional Documentation
• Development
• License
• Citation

Features

• FAIR: More findable MGnify analyses and metadata, returned in familiar metagenomics data formats (e.g., GFF, Darwin Core, Dataframes[pandas, polars, anndata])
• Simplifies API interactions: Let MGni.Py handle the complexity of building, executing, and parsing API calls so you can focus on the data!
• Fast: MGni.Py uses caching to speed up API expolation, as well as supports both sync and async API calls

Available API Endpoints

• Studies: MGnify studies are based on ENA studies/projects, and are collections of samples, runs, assemblies, and analyses associated with a certain set of experiments.
• Samples: MGnify samples are based on ENA/BioSamples samples, and represent 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: MGnify analyses are runs of a standard pipeline on an individual sequencing run or assembly. They can include collections of taxonomic and functional annotations.
• Publications: Publications (e.g. journal articles) may describe or analyse the content of MGnify Studies or their corresponding datasets in ENA.
• Genomes: MGnify Genomes are annotated draft genomes based on either isolates, or metagenome-assembled genomes (MAGs). They are arranged in biome-specific catalogues.
• Biomes: The hierarchical GOLD ecosystem classifications biomes represented in MGnify.

Note: 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

🚀 1. Initialize mgnipy.MGnipy

from mgnipy import MGnipy

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

# See available endpoints
mg.list_resources()

🔎 2. Search resources with a mgnipy.MGnifier

Building the query set

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

# Can preview requests before fetching
studies.explain()

Executing the queries

# client context manager
with MG: 

    # get page by page via .get()
    studies.get()
    # or via .page(), getting a specific pg num 
    studies.page(2)
    # OR potentially all at once in large batches (also async option .aget_all())
    studies.get_all()

    # then can enrich list with detailed metadata
    studies.enrich_details()

Viewing the search results

# the mgnify list (without details)
study_list = studies.search_results
# detailed metadata, e.g. with enriched details
detailed_study_list = studies.metadata

# e.g. as dataframes
pl_metadata = detailed_study_metadata.to_polars()
pd_metadata = detailed_study_metadata.to_pandas()

# e.g. as json
json_metadata = detailed_study_metadata.to_json()

🗃️ 3. Explore a mgnipy.MGazine of datasets

# accessing the mgazine of datasets
mgazine = studies.datasets

# preview
print(mgazine)

Downloading datasets from MGnify

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

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

Reading in datasets from MGnify

# support for tsv, csv, txt, jsonl
taxa_table = mgazine.stream(
    alias="mgnify_file_alias.tsv", 
    df_engine="polars"
)

# support for fasta, gff, biom via skbio
skbio_fasta = mgazine.stream(alias="mgnify_file_alias.fasta.gz")

Additional Documentation

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

Development

see Contributing.md

License

TODO

Citation

TODO