MGni.py

MGni.py#

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

PyPI cicd.yml GitHub Pages docs
Python 3.11 to 3.13 GitHub issues GitHub license GitHub last commit GitHub stars

mgnipy schematic

Contents#

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#

Development#

see Contributing.md

License#

TODO

Citation#

TODO

Thank you#

A list of people who have contributed to this repository. Please add your name and github or email if you’d like.

From the Multiomics Network Analytics team @ Danmarks Tekniske Universitet (DTU):

  • Angel L. P. (angelphanth) - PhD student and visitor to Microbiome Informatics team

  • Maria Barranco - Postdoc

  • Sebastián Ayala Ruano (sayalaruano) - Previous MSc student and Research Assistant

  • Alberto Santos Delgado (albsantosdel) - Senior Researcher and BRIGHT Informatics Platform Director

From the Microbiome Informatics team @ The European Bioinformatics Institute (EMBL-EBI):

  • Mahfouz Shehu (MGS-sails) - Mgnify Website Developer

  • Christian Atallah (chrisAta) - Bioinformatician Mgnify

  • Sandy Rogers (SandyRogers) - MGnify Web and Platform Project Leader

  • Martin Beracochea (mberacochea) - MGnify Production Project Leader

  • Robert Finn (rdf [at] ebi.ac.uk ) - Section Head, Team Leader and Senior Scientist

Extra special thanks to:

  • Prof. Rob Finn and everyone in the Microbiome Informatics team and Finn Group at EMBL-EBI for their mentorship

  • My Prof. Alberto Santos for making this colab happen and also constant guidance and patience

  • The Danemo Stipend, Reinholdt W. Jorck og Hustrus Fond, and William Demant Fonden for their generous travel grants so that I could go to EBI

  • The Informatics Platform at BRIGHT at DTU for their mentorship

  • The creators of this python_package template and especially Henry Webel (enryH)

  • The creators and maintainers of openapi-python-client

Contents