Tutorial

The pyexpressionatlas package bridges the gap between Python and the EMBL-EBI Expression Atlas, making it simple to search, download, and analyze curated gene expression datasets in Python. This client mirrors the Bioconductor package, and plugs right into the BiocPy ecosystem (BiocFrame, SummarizedExperiment, and SingleCellExperiment).

---

Getting Started

First, make sure you have the package installed:

pip install pyexpressionatlas

Then, import the client:

from pyexpressionatlas import ExpressionAtlasClient

# Initialize the client.
# By default, files are cached in ~/.cache/pyexpressionatlas_bfc.
# You can customize this directory by passing the cache_dir parameter:
client = ExpressionAtlasClient(timeout=30, cache_dir="/my/custom/cache/path")

Searching for Datasets

Expression Atlas hosts thousands of curated experiments. You can search for terms related to diseases, cell lines, developmental stages, and more.

Let’s say we’re looking for breast cancer datasets in humans:

results = client.search_experiments(
    properties=["breast", "cancer"],
    species="homo sapiens"
)

print(results)

This returns a BiocFrame containing all matches.

If you want the complete metadata for your hits, you can fetch it on-demand:

# Grab the first 5 accessions from our search
accessions = results.get_column("Accession")[:5]

# Fetch complete metadata for just these experiments
metadata = client.fetch_experiment_metadata(accessions)
print(metadata)

Downloading Bulk Experiments

Let’s download E-MTAB-1625 as an example. When you download a bulk experiment, it usually comes back as a NamedList containing SummarizedExperiment objects (since an accession might contain multiple array designs or assays).

exp = client.get_experiment("E-MTAB-1625")

# For RNA-seq datasets, the data lives under the "rnaseq" key
rnaseq = exp["rnaseq"]
print(rnaseq)

This is a SummarizedExperiment object. You can access the count matrix, sample annotations, and gene annotations using standard accessors:

# The expression matrix (numpy array: genes x samples)
counts = rnaseq.assay("counts")

# The sample annotations (BiocFrame)
sample_metadata = rnaseq.get_column_data()

# The gene annotations (BiocFrame)
gene_metadata = rnaseq.get_row_data()

It works exactly the same for Microarray data, except the keys in the NamedList will correspond to the array design (e.g., A-AFFY-126), and the assay is usually called "exprs".

Downloading Single-Cell Experiments

If you pass an accession from the Single Cell Expression Atlas, the client automatically detects it, falls back to the single-cell FTP, and grabs the Matrix Market components. It returns a SingleCellExperiment object.

# Let's download a single-cell dataset
sc_exp = client.get_experiment("E-MTAB-6945")

print(type(sc_exp))
# <class 'singlecellexperiment.SingleCellExperiment.SingleCellExperiment'>

print(sc_exp)

You can interact with sc_exp exactly like a bulk SummarizedExperiment.

Batch Downloads

If you’re doing meta-analysis across dozens of experiments, grabbing them one by one is tedious. Use get_experiments to download a whole batch at once:

# Download a batch of accessions
batch_results = client.get_experiments(["E-MTAB-1624", "E-MTAB-1625", "E-MTAB-6945"])

# Iterate through the downloaded objects
for accession, data in batch_results.items():
    print(f"Loaded {accession} successfully!")

And that’s it! You’re ready to start pulling down Expression Atlas data and throwing it straight into your Python pipelines. Happy analyzing!