pyexpressionatlas package¶

Submodules¶

pyexpressionatlas.api module¶

BioStudies API client for Expression Atlas.

class pyexpressionatlas.api.BioStudiesAPI(timeout=30)[source]¶

Bases: object

Client for BioStudies API to search Expression Atlas experiments.

__enter__()[source]¶

Return type:: BioStudiesAPI

__exit__(*args)[source]¶

Return type:: None

__init__(timeout=30)[source]¶

Initialize BioStudies API client.

Parameters:: timeout (int) – Request timeout in seconds (default: 30).

close()[source]¶

Close the session.

Return type:: None

fetch_experiment_metadata(accessions)[source]¶

Fetch detailed metadata for each experiment.

Return type:: list[SearchResult]

search(properties, species=None, page_size=100)[source]¶

Search for Expression Atlas experiments.

Parameters:

properties (list[str]) – Search terms (e.g., [“cancer”, “breast”]).
species (str | None) – Species to filter by (e.g., “homo sapiens”).
page_size (int) – Number of results per page (default: 100).

Return type:

list[SearchResult]

Returns:

List of search results with experiment metadata.

Raises:

APIError – If the API request fails.

pyexpressionatlas.client module¶

Main client interface for Expression Atlas.

class pyexpressionatlas.client.ExpressionAtlasClient(timeout=30, cache_dir=None)[source]¶

Bases: object

Client for searching and downloading Expression Atlas data.

This is the main entry point for interacting with Expression Atlas. It provides methods equivalent to the R package’s exported functions: - search_experiments() -> searchAtlasExperiments() - get_experiment() -> getAtlasExperiment() - get_experiments() -> getAtlasData()

Data is returned in R-compatible formats: - RNA-seq: SummarizedExperiment (assays[“counts”] matrix) - Microarray: SummarizedExperiment (assays[“exprs”] matrix)

Examples

>>> client = ExpressionAtlasClient()
>>> # Search for experiments
>>> results = client.search_experiments(
...     ["cancer"],
...     species="homo sapiens",
... )
>>> # Download a single experiment
>>> exp = client.get_experiment(
...     "E-MTAB-1624"
... )
>>> # Download multiple experiments
>>> exps = client.get_experiments(
...     [
...         "E-MTAB-1624",
...         "E-MTAB-1625",
...     ]
... )

__enter__()[source]¶

Return type:: ExpressionAtlasClient

__exit__(*args)[source]¶

Return type:: None

__init__(timeout=30, cache_dir=None)[source]¶

Initialize Expression Atlas client.

Parameters:

timeout (int) – Request timeout in seconds (default: 30).
cache_dir (str | Path | None) – Custom path to store downloaded dataset files (default: ~/.cache/expressionatlas_bfc).

__repr__()[source]¶

Return repr(self).

Return type:: str

property api: BioStudiesAPI¶: Lazy-loaded BioStudies API client.

close()[source]¶

Close the client and release resources.

Return type:: None

fetch_experiment_metadata(accession)[source]¶

Fetch full metadata for one or more experiment accessions.

Parameters:: accession (str | Sequence[str]) – A single accession string or a sequence of accession strings.
Return type:: BiocFrame
Returns:: A BiocFrame containing the full metadata.

get_experiment(accession)[source]¶

Download a single Expression Atlas experiment.

Equivalent to R function: getAtlasExperiment()

Parameters:: accession (str) – ArrayExpress/BioStudies experiment accession (e.g., “E-MTAB-1624”).
Return type:: NamedList | None
Returns:: The downloaded experiment data, or None if download fails. For RNA-seq (bulk): access via [“rnaseq”] to get SummarizedExperiment For microarray (bulk): access via array design (e.g., [“A-AFFY-126”]) to get SummarizedExperiment For Single-cell: returns a SingleCellExperiment object
Raises:: InvalidAccessionError – If the accession format is invalid.

Examples: >>> client = ExpressionAtlasClient() >>> # RNA-seq experiment >>> exp = client.get_experiment( … “E-MTAB-1625” … ) >>> sumexp = exp[ … “rnaseq” … ] # SummarizedExperiment >>> sumexp.assays[ … “counts” … ] # counts matrix (genes × samples) >>> sumexp.colData # sample annotations >>> >>> # Microarray experiment >>> exp = client.get_experiment( … “E-MTAB-1624” … ) >>> eset = exp[ … “A-AFFY-126” … ] # SummarizedExperiment >>> eset.assays[ … “exprs” … ] # expression matrix (probes × samples) >>> eset.colData # sample annotations

get_experiments(accessions, skip_invalid=True)[source]¶

Download multiple Expression Atlas experiments.

Equivalent to R function: getAtlasData()

Parameters:

accessions (Sequence[str]) – List of experiment accessions to download.
skip_invalid (bool) – If True (default), skip invalid accessions with a warning. If False, raise an error on invalid accessions.

Return type:

NamedList

Returns:

Dictionary-like object mapping accession to experiment data (NamedList). Failed downloads are excluded from the result.

Raises:

ValueError – If no valid accessions provided.
InvalidAccessionError – If skip_invalid is False and an invalid accession is found.

Examples: >>> client = ExpressionAtlasClient() >>> results = client.search_experiments( … “cancer”, … species=”homo sapiens”, … ) >>> # Download all RNA-seq experiments from search results >>> types = results.get_column( … “Type” … ) >>> accessions = results.get_column( … “Accession” … ) >>> rnaseq_accessions = [ … acc … for acc, typ in zip( … accessions, … types, … ) … if typ … and “RNA-seq” … in typ … ] >>> experiments = client.get_experiments( … rnaseq_accessions … ) >>> # Access: experiments[“E-MTAB-XXXX”][“rnaseq”].assays[“counts”]

search_experiments(properties, species=None)[source]¶

Search for Expression Atlas experiments matching given criteria.

Equivalent to R function: searchAtlasExperiments()

Parameters:

properties (str | Sequence[str]) – Search terms (e.g., “cancer” or [“cancer”, “breast”]).
species (str | None) – Species to filter by (e.g., “homo sapiens”, “mus musculus”). If not provided, searches across all species.

Returns:

Accession, Species, Type, Title. Sorted by Species, Type, then Accession. Note: Species and Type will initially be None. Use fetch_experiment_metadata to retrieve full metadata for specific accessions.

Return type:

BiocFrame

Raises:

ValueError – If no search properties provided.
APIError – If the BioStudies API request fails.

Examples: >>> client = ExpressionAtlasClient() >>> # Search for salt stress experiments in rice >>> results = client.search_experiments( … “salt”, … species=”oryza sativa”, … ) >>> # Search with multiple terms >>> results = client.search_experiments( … [ … “cancer”, … “breast”, … ], … species=”homo sapiens”, … )

pyexpressionatlas.download module¶

FTP download functionality for Expression Atlas experiments.

Provides compatibility with the BiocPy ecosystem: - Uses rds2py to load .rds files if available (replaces rpy2 and .Rdata) - Fallback: Downloads TSV files from FTP server

The data structures use biocutils, biocframe, and summarizedexperiment.

pyexpressionatlas.download.download_experiment(experiment_accession)¶

Download and return the data representing a single Expression Atlas experiment.

Parameters:: experiment_accession (str) – Valid ArrayExpress/BioStudies accession (e.g., “E-MTAB-1624” or “E-MTAB-6945”).
Returns:: NamedList with key “rnaseq” containing SummarizedExperiment For microarray (bulk): NamedList with array design accessions as keys, each containing SummarizedExperiment For Single-cell: SingleCellExperiment object Returns None if download fails.
Return type:: NamedList | None

pyexpressionatlas.download.download_experiments(experiment_accessions)¶

Download NamedList objects for one or more Expression Atlas experiments.

Parameters:: experiment_accessions (list[str]) – List of experiment accessions to download.
Return type:: NamedList
Returns:: Dictionary-like object mapping accession to experiment data.

pyexpressionatlas.download.get_atlas_data(experiment_accessions)[source]¶

Download NamedList objects for one or more Expression Atlas experiments.

Parameters:: experiment_accessions (list[str]) – List of experiment accessions to download.
Return type:: NamedList
Returns:: Dictionary-like object mapping accession to experiment data.

pyexpressionatlas.download.get_atlas_experiment(experiment_accession)[source]¶

Download and return the data representing a single Expression Atlas experiment.

Parameters:: experiment_accession (str) – Valid ArrayExpress/BioStudies accession (e.g., “E-MTAB-1624” or “E-MTAB-6945”).
Returns:: NamedList with key “rnaseq” containing SummarizedExperiment For microarray (bulk): NamedList with array design accessions as keys, each containing SummarizedExperiment For Single-cell: SingleCellExperiment object Returns None if download fails.
Return type:: NamedList | None

pyexpressionatlas.download.has_tsv_files(accession)[source]¶

Check if an experiment has TSV files available for download.

Parameters:: accession (str) – Valid ArrayExpress/BioStudies accession (e.g., “E-MTAB-1624”).
Return type:: bool
Returns:: True if TSV files are available, False otherwise.

pyexpressionatlas.download.set_cache_dir(cache_dir)[source]¶

Set the BiocFileCache directory globally.

Parameters:: cache_dir (str | Path) – Path to the new cache directory.
Return type:: None

pyexpressionatlas.exceptions module¶

Custom exceptions for Expression Atlas client.

exception pyexpressionatlas.exceptions.APIError(status_code, message=None)[source]¶

Bases: ExpressionAtlasError

Raised when BioStudies API request fails.

__init__(status_code, message=None)[source]¶

exception pyexpressionatlas.exceptions.DownloadError(accession, reason)[source]¶

Bases: ExpressionAtlasError

Raised when experiment download fails.

__annotations__ = {}¶

__init__(accession, reason)[source]¶

exception pyexpressionatlas.exceptions.ExpressionAtlasError[source]¶

Bases: Exception

Base exception for Expression Atlas errors.

__annotations__ = {}¶

exception pyexpressionatlas.exceptions.InvalidAccessionError(accession)[source]¶

Bases: ExpressionAtlasError

Raised when an experiment accession is invalid.

__annotations__ = {}¶

__init__(accession)[source]¶

pyexpressionatlas.models module¶

Data models for Expression Atlas.

class pyexpressionatlas.models.ExperimentType(*values)[source]¶

Bases: str, Enum

Valid Expression Atlas experiment types.

ANTIGEN_PROFILING = 'antigen profiling'¶

MICRORNA_PROFILING_ARRAY = 'microRNA profiling by array'¶

PROTEOMIC_PROFILING = 'proteomic profiling by mass spectrometer'¶

RNASEQ_CODING = 'RNA-seq of coding RNA'¶

RNASEQ_NONCODING = 'RNA-seq of non coding RNA'¶

RNASEQ_SINGLE_CELL_CODING = 'RNA-seq of coding RNA from single cells'¶

RNASEQ_SINGLE_CELL_NONCODING = 'RNA-seq of non coding RNA from single cells'¶

RNASEQ_TOTAL = 'RNA-seq of total RNA'¶

TRANSCRIPTION_PROFILING_ARRAY = 'transcription profiling by array'¶

__format__(format_spec)¶: Return a formatted version of the string as described by format_spec.

__new__(value)¶

__repr__()¶: Return repr(self).

classmethod get_eligible_types()[source]¶

Return list of all eligible experiment type values.

Return type:: list[str]

classmethod is_microarray(exp_type)[source]¶

Check if experiment type is microarray.

Return type:: bool

classmethod is_rnaseq(exp_type)[source]¶

Check if experiment type is RNA-seq.

Return type:: bool

class pyexpressionatlas.models.SearchResult(accession, species, experiment_type, title, connection_error=False)[source]¶

Bases: object

Container for search results from BioStudies API.

__annotations__ = {'accession': 'str', 'connection_error': 'bool', 'experiment_type': 'str | None', 'species': 'str | None', 'title': 'str | None'}¶

__dataclass_fields__ = {'accession': Field(name='accession',type='str',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'connection_error': Field(name='connection_error',type='bool',default=False,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'experiment_type': Field(name='experiment_type',type='str | None',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'species': Field(name='species',type='str | None',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD), 'title': Field(name='title',type='str | None',default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD)}¶

__dataclass_params__ = _DataclassParams(init=True,repr=True,eq=True,order=False,unsafe_hash=False,frozen=False,match_args=True,kw_only=False,slots=False,weakref_slot=False)¶

__eq__(other)¶: Return self==value.

__hash__ = None¶

__init__(accession, species, experiment_type, title, connection_error=False)¶

__match_args__ = ('accession', 'species', 'experiment_type', 'title', 'connection_error')¶

__repr__()¶: Return repr(self).

accession: str¶

connection_error: bool = False¶

experiment_type: str | None¶

species: str | None¶

title: str | None¶

to_dict()[source]¶

Convert to dictionary.

Return type:: dict[str, Any]

pyexpressionatlas.models.search_results_to_biocframe(results)[source]¶

Convert list of SearchResult objects to a BiocFrame.

Return type:: BiocFrame

pyexpressionatlas.validation module¶

Validation utilities for Expression Atlas.

pyexpressionatlas.validation.filter_valid_accessions(accessions, raise_on_invalid=False)[source]¶

Filter a list of accessions to only include valid ones.

Parameters:

accessions (Sequence[str]) – List of experiment accessions to filter.
raise_on_invalid (bool) – If True, raise error on first invalid accession. If False (default), silently skip invalid accessions.

Return type:

list[str]

Returns:

List containing only valid accessions.

Raises:

InvalidAccessionError – If raise_on_invalid is True and an invalid accession is found.

pyexpressionatlas.validation.is_valid_accession(accession)[source]¶

Check if experiment accession matches expected ArrayExpress/BioStudies format.

Valid format: E-XXXX-#### (e.g., E-MTAB-1624, E-GEOD-11175)

Parameters:: accession (str) – The experiment accession to validate.
Return type:: bool
Returns:: True if valid, False otherwise.

Examples: >>> is_valid_accession( … “E-MTAB-1624” … ) True >>> is_valid_accession( … “E-GEOD-11175” … ) True >>> is_valid_accession( … “DRP000391” … ) False >>> is_valid_accession( … “invalid” … ) False

pyexpressionatlas.validation.validate_accession(accession)[source]¶

Validate accession and raise error if invalid.

Parameters:: accession (str) – The experiment accession to validate.
Return type:: str
Returns:: The validated accession (unchanged if valid).
Raises:: InvalidAccessionError – If the accession format is invalid.

pyexpressionatlas package¶

Submodules¶

pyexpressionatlas.api module¶

pyexpressionatlas.client module¶

pyexpressionatlas.download module¶

pyexpressionatlas.exceptions module¶

pyexpressionatlas.models module¶

pyexpressionatlas.validation module¶

Module contents¶