Metadata-Version: 2.4
Name: seqout
Version: 0.2.7
Summary: Search genomics datasets across GEO, SRA, ENA, DDBJ, ArrayExpress, GEA and GSA. Read GEO supplementary files as counts matrices.
Keywords: genomics,bioinformatics,metadata,single-cell,GEO,SRA,ENA,DDBJ,ArrayExpress,GSA,accession,counts matrix,duckdb,parquet
Author: Aniruddha Mukherjee, Mukesh Reddy, Saket Choudhary
Author-email: Aniruddha Mukherjee <amkhrjee@iitb.ac.in>, Mukesh Reddy <mukeshreddy.work@gmail.com>, Saket Choudhary <saketc@iitb.ac.in>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Dist: duckdb>=1.5.4
Requires-Dist: httpx>=0.28.1
Requires-Dist: numpy>=2
Requires-Dist: pandas>=3.0.3
Requires-Dist: pydantic>=2.13.4
Requires-Dist: questionary>=2.1.1
Requires-Dist: requests>=2.32
Requires-Dist: rich>=15.0.0
Requires-Dist: tqdm>=4.67.3
Requires-Dist: anndata>=0.10 ; extra == 'counts'
Requires-Dist: h5py>=3.11 ; extra == 'counts'
Requires-Dist: isal>=1.6 ; extra == 'counts'
Requires-Dist: rdata>=0.11 ; extra == 'counts'
Requires-Dist: scipy>=1.14 ; extra == 'counts'
Requires-Dist: pysocks>=1.7 ; extra == 'socks'
Maintainer: Saket Choudhary
Maintainer-email: Saket Choudhary <saketc@iitb.ac.in>
Requires-Python: >=3.13
Project-URL: Homepage, https://seqout.org
Project-URL: Documentation, https://seqout.org/cli/python/
Project-URL: Repository, https://github.com/saketlab/seqout
Project-URL: Issues, https://github.com/saketlab/seqout/issues
Provides-Extra: counts
Provides-Extra: socks
Description-Content-Type: text/markdown

# seqout (Python Client & CLI)

A Python client library and command-line interface (CLI) for [seqout.org](https://seqout.org). Use this package to search and retrieve genomics study metadata across GEO, SRA, ENA, DDBJ, ArrayExpress, GEA, and GSA, and download metadata, raw reads, and processed counts matrices.

Requires Python 3.13 or newer.

## Installation

```bash
pip install seqout            # library + CLI
pip install "seqout[counts]"  # also read GEO supplementary files as counts matrices
```

As a standalone CLI, or as a project dependency, with `uv`:

```bash
uv tool install seqout
uvx seqout --help             # run once without installing
uv add "seqout[counts]"
```

The development version installs from GitHub:

```bash
pip install "seqout @ git+https://github.com/saketlab/seqout.git#subdirectory=python"
```

## Quick start

### Query from the command line

Run these commands to search for datasets, inspect study details, and download supplementary files:

```bash
# Search for GEO single-cell lung cancer studies, sorted by citations
seqout search "lung cancer single cell" --db geo --sort citations --max 5

# Show detailed metadata for a study
seqout show GSE149312

# Download processed supplementary files
seqout download GSE149312 --supplementary
```

### Query in Python

Open a connection using `connect()` to search and query metadata programmatically:

```python
from seqout import connect

with connect() as sq:
    dataset = sq.get("GSE149312")
    print(f"Title: {dataset.meta.title}")
    print(f"Samples: {len(dataset.samples)}")
    print(f"Runs: {len(dataset.runs)}")
```

The `Dataset` object evaluates fields lazily. It fetches data from the API only when you access a field for the first time, and caches it for future reads. It automatically resolves cross-archive links (for example, mapping a GEO series to its corresponding SRA study runs).

### Parse processed single-cell matrices

To parse supplementary files into cell-by-gene expression matrices along with harmonized donor covariates, use `SeqoutListCounts`. This feature requires the `counts` installation extra:

```python
from seqout import SeqoutListCounts

# Query the file manifest without downloading the files
counts = SeqoutListCounts(gse="GSE297547")
print(counts.manifest())

# Download and parse a specific sample unit into an AnnData object
matrix = counts.matrix(sample="GSM8994520")

# Access the harmonized experimental design table
print(counts.design)
```

## Command reference summary

For the complete options list, run `seqout --help` or `seqout <command> --help`.

### Explore metadata

| Command | Action |
| --- | --- |
| `seqout search [query]` | Search for studies using free-text and metadata filters. |
| `seqout show <accession>` | Display study-level tables or detailed sample attributes. |
| `seqout pmid <pmid\|doi>` | Retrieve all datasets linked to a publication PMID or DOI. |
| `seqout author <name>` | Retrieve all datasets linked to an author. |

### Download files

| Command | Action |
| --- | --- |
| `seqout download <accession>` | Download study metadata as a JSON file. |
| `seqout download <accession> --supplementary` | Download study-level supplementary files. |
| `seqout download <accession> --sample-supplementary` | Download per-sample supplementary files. |
| `seqout download <accession> --fastq` | Download raw sequencing reads (supports `--sra`, `--sra-lite`, `--s3`, `--gcs`). |

### Map accessions

| Command | Action |
| --- | --- |
| `seqout convert <accession>... --to <kind>` | Map accessions to other types (e.g., `study`, `sample`, `run`). |
| `seqout gse-to-srp <accession>...` | Shorthand helper to convert GEO Series accessions to SRA Study accessions. |

### Offline SQL queries (Parquet backend)

| Command | Action |
| --- | --- |
| `seqout parquet download <dir>` | Download the published database Parquet files to a directory. |
| `seqout parquet query "<sql>"` | Run custom SQL queries against the Parquet files using DuckDB. |
| `seqout parquet show <accession>` | Inspect studies, samples, or experiments offline. |
| `seqout parquet set-source <url\|dir>` | Save a default local or remote source directory. |

To run standard CLI commands offline, append the `--parquet` flag (e.g., `seqout show GSE12345 --parquet`).
