gprofiler-official

1.0.0 · active · verified Sat Apr 11

The official Python 3 interface to the g:Profiler toolkit, providing functional enrichment analysis of GO and other terms, conversion between identifier namespaces, and mapping orthologous genes. It is currently at version 1.0.0, released in April 2019, and appears to have a stable, though not rapid, release cadence based on its history.

Warnings

breaking The 1.0.x series introduced breaking changes compared to the 0.3.x series. Code written for older versions (e.g., 0.3.5) will not be compatible with 1.0.0 without modifications.
Fix: Review the API documentation for version 1.0.0 and update your code accordingly. For legacy projects requiring Python 2, use `pip install gprofiler-official==0.2.3`.
gotcha The library is exclusively for Python 3 since version 0.3. Earlier versions (e.g., 0.2.x) were Python 2 compatible. Attempting to use recent versions with Python 2 will result in errors.
Fix: Ensure your project is running on Python 3. If Python 2 support is strictly necessary, use version 0.2.3 specifically.
gotcha If identifiers in your query have multiple possible mappings in g:Profiler, they might be excluded by default. This can lead to incomplete results.
Fix: Check for identifier discrepancy warnings in the g:Profiler output. You may need to manually map ambiguous genes or re-submit the query with explicit mappings to ensure all identifiers are correctly interpreted.
gotcha Using `return_dataframe=True` (as shown in quickstart) requires the `pandas` library to be installed. If `pandas` is not present, this will lead to an `ImportError` or `ModuleNotFoundError` when results are being processed.
Fix: Install `pandas` explicitly if you intend to use the DataFrame output: `pip install pandas`.

Install

pip install gprofiler-official Install with pip

Imports

GProfiler
```
from gprofiler import GProfiler
```

Quickstart

This quickstart demonstrates how to initialize the `GProfiler` client and perform basic functional enrichment analysis (g:GOSt) and gene ID conversion (g:Convert). It's recommended to provide a `user_agent` for API calls and to set `return_dataframe=True` for convenient result handling with pandas.

import os
from gprofiler import GProfiler

# Initialize GProfiler object
# user_agent is optional but good practice to identify your application.
# Setting return_dataframe=True makes results easier to work with using pandas.
gp = GProfiler(
    user_agent=os.environ.get('GPROFILER_USER_AGENT', 'MyAwesomeBioTool/1.0'),
    return_dataframe=True
)

# Example: Functional enrichment analysis (g:GOSt)
# Query a list of genes for Homo sapiens
genes_query = ['NR1H4', 'TRIP12', 'UBC', 'FCRL3', 'PLXNA3', 'GDNF', 'VPS11']
print(f"Querying genes: {genes_query}")
results = gp.profile(organism='hsapiens', query=genes_query)

print("\nFunctional Enrichment Results (head):")
if results is not None and not results.empty:
    print(results.head())
else:
    print("No enrichment results found or query failed.")

# Example: Gene ID conversion (g:Convert)
# Convert gene IDs from one namespace to another
convert_query = ['NR1H4', 'TRIP12']
print(f"\nConverting gene IDs: {convert_query}")
converted_genes = gp.convert(
    organism='hsapiens',
    query=convert_query,
    target_namespace='ENTREZGENE_ACC'
)
print("\nGene ID Conversion Results (head):")
if converted_genes is not None and not converted_genes.empty:
    print(converted_genes.head())
else:
    print("No conversion results found or query failed.")

view raw JSON →