The mgnipy.MGnipy() client

The mgnipy.MGnipy() client#

Here we provide additional information about the mgnipy.MGnipy() client

# uncomment below if colab
#!pip install mgnipy

Why start with the mgnipy.MGnipy client?#

  • Unified configuration: Central MGnipyConfig for base URL, credentials, token handling, and cache settings — one place to change behavior

  • Tidier cache invalidation: All the cache files across all resource endpoints (e.g., MG.studies, MG.analysis, MG.biome) go to a consistent place. The MG.clear_subcaches() can then clear all the mgnipy cache files for all different requests made.

Quick to start#

You can create a single MGnipy() instance and then access resource proxies from it. Those resource proxies aka resource endpoint-specific MGnifier()s would then share the same configuration of MGnipy()

from mgnipy import MGnipy

# Create a default client (will pick up .env if present)
MG = MGnipy()

# for example we can access the samples MGnify resource easily
samples = MG.samples
# some info
print(samples)
# more info
samples.describe_endpoint()

MGnifier instance for resource: samples
I.e., mgnipy.V2.proxies.samples.Samples
----------------------------------------
Base URL: https://www.ebi.ac.uk/
Parameters: {}
Example request URL: https://www.ebi.ac.uk/metagenomics/api/v2/samples?page=1
Endpoint module: mgnipy.emgapi_v2_client.api.samples.list_mgnify_samples
Is list endpoint (returns paginated results): True
Cache directory: /home/runner/.cache/mgnipy/3fddd8853bdd0204eeaeda6c5b9b42b48c8a25ca4f034132d94eb1f93e01ac48

List all samples analysed by MGnify

MGnify samples inherit directly from samples (or BioSamples) in ENA.

Supported parameters:
- biome_lineage: None | str | Unset The lineage to match, including all descendant biomes
- search: None | str | Unset Search within sample titles and accessions
- order: ListMgnifySamplesOrderType0 | None | Unset
- page: int | Unset Default: 1.
- page_size: int | None | Unset

API helpers#

We can also learn more about the MGnify API using the mgnipy.MGnipy client.

  • MG.list_resources() returns the available endpoint names.

  • MG.describe_resource() to read parameter docs extracted from the OpenAPI spec.

# List known resources (strings like 'samples', 'studies', 'analyses')
print(MG.list_resources())

# Describe a resource
MG.describe_resources(MG.list_resources()[0])

['analyses', 'analysis', 'assemblies', 'assembly', 'genomes', 'genome', 'publications', 'publication', 'samples', 'sample', 'studies', 'study', 'runs', 'run', 'biomes', 'biome', 'catalogues', 'catalogue', 'private_studies']
List all analyses (MGYAs) available from MGnify

Each analysis is the result of a Pipeline execution on a reads dataset (either a raw read-run, or an
assembly).

Supported parameters:
- page: int | Unset Default: 1.
- page_size: int | None | Unset

Quick cleanup#

The MG.clear_subcaches() will clear all the mgnipy cache files, no matter if they were from MG.studies vs. MG.analysis vs. MG.biome etc, in the universal MG.cache_dir.

MG.clear_subcaches()
Contents