geoparse

library2.0.4pypypi✓ verified 91d ago

GEOparse is a Python library designed to access, parse, and handle data from the Gene Expression Omnibus (GEO) database. It simplifies the programmatic retrieval of GEO Series (GSE), GEO DataSets (GDS), and GEO Sample (GSM) entries, providing easy access to metadata and expression tables. The current version is 2.0.4, and releases are made on an as-needed basis, typically for bug fixes or feature enhancements.

data ai-ml

pip install geoparse

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · GEOPARSE

geoparse

datapythonv2.0.4

Install

8.5s avg

Import

1543ms

Disk

168MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 1.573s · 168.7MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 8.5s · import 1.514s · 161MB

168MB installed

● package 168MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GEOparse

✓ import GEOparse

get_GEO

✓ from GEOparse import get_GEO

Can also be accessed via `GEOparse.get_GEO` after `import GEOparse`.

This quickstart demonstrates how to download and parse a GEO Series (GSE) entry, access its metadata, and iterate through its associated GEO Samples (GSMs) to view their data tables. It uses 'GSE1' for a minimal example.

import GEOparse import os # Download a small GEO Series (GSE1 is very small for quick testing) print("Downloading GSE1 data...") gse = GEOparse.get_GEO(geo="GSE1", destdir="./") print(f"\nSuccessfully parsed GEO Series: {gse.name}") print(f"Title: {gse.metadata.get('title', ['N/A'])[0]}") print(f"Number of samples (GSMs): {len(gse.gsms)}") # Access and print information for the first sample if gse.gsms: first_gsm_name = list(gse.gsms.keys())[0] first_gsm = gse.gsms[first_gsm_name] print(f"\nFirst Sample (GSM): {first_gsm.name}") print(f"Sample Title: {first_gsm.metadata.get('title', ['N/A'])[0]}") print(f"Sample Type: {first_gsm.metadata.get('type', ['N/A'])[0]}") print(f"Sample Table Head:\n{first_gsm.table.head(2)}")

Debug

Known issues

breakingThe return type of `GEOparse.get_GEO()` changed significantly from versions 1.x to 2.x. Previously, it might have returned a tuple (e.g., `(gse_object, gsm_list)`). In 2.x, it consistently returns a single GEOparse object (e.g., `GESeries`, `GDS`, or `GSM`).

fix

Adjust your code to expect a single object from `get_GEO`. Access associated GSMs via the returned object's `.gsms` attribute (e.g., `gse.gsms`).

affects: <2.0.0

gotchaProcessing very large GEO datasets can consume significant amounts of RAM and disk space, potentially leading to out-of-memory errors or long download/parsing times.

fix

Consider downloading files to disk using `destdir`, processing data in chunks if possible, or filtering data early. Ensure sufficient disk space and memory before attempting to parse extremely large datasets.

affects: All versions

gotchaDownloads from the GEO database can occasionally fail due to network connectivity issues, server-side problems at NCBI, or incorrect GEO accession IDs.

fix

Implement robust error handling (e.g., `try-except` blocks for `requests.exceptions.ConnectionError`), check your internet connection, verify the GEO accession ID on the NCBI GEO website, and consider implementing retry logic for downloads.

affects: All versions

Errors

Common errors & fixes

AttributeError: 'tuple' object has no attribute 'name'

This error occurs when code written for GEOparse 1.x (which returned a tuple from `get_GEO`) is run with GEOparse 2.x, which returns a single object. You're trying to access an attribute like 'name' directly on what is now the full `GESeries` object, but your code expects a tuple structure.

fix

Update your code to match the 2.x API. Instead of `gse, gsms = GEOparse.get_GEO(...)` and then `gse.name`, simply use `gse = GEOparse.get_GEO(...)` and then `gse.name`. Access individual samples via `gse.gsms`.

requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer'))

The connection to the NCBI GEO server was abruptly closed during download, often due to network instability, a firewall blocking the connection, or the server closing the connection.

fix

Check your internet connection and proxy settings. Temporarily disable any firewalls or VPNs that might interfere. Try running the download again. If the issue persists, the GEO server might be experiencing temporary problems; try again later.

KeyError: 'some_metadata_field_name'

You are trying to access a specific metadata field (e.g., `gsm.metadata['some_field']`) that does not exist for the current GEO Series or Sample.

fix

Not all metadata fields are present for every entry. Use the `.get()` method for dictionary access with a default value to prevent `KeyError`: `gsm.metadata.get('some_metadata_field_name', 'N/A')`.

Upgrade

Version history

2.0.4latest on PyPI · released Apr 23, 2024

Audit

Dependencies

pandasrequiredData manipulation, especially for expression tables.

lxmlrequiredXML/HTML parsing, used for handling GEO SOFT files.

requestsrequiredHTTP requests for downloading GEO files from NCBI servers.

numpyrequiredNumerical operations, often a dependency of pandas but explicitly listed.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/guma44/GEOparse ↗

packagehttps://pypi.org/project/geoparse/ ↗

docshttps://geoparse.readthedocs.io/ ↗

changeloghttps://geoparse.readthedocs.io/en/latest/history.html ↗