GEOmend

Turn a list of GEO studies into a useful modeling metadata table, then improve the guesses where it matters. GEOmend handles study metadata acquisition, profiling, cross-study alignment, and export in one headless workflow. You can start with best-guess results—without first writing a registry, helper scripts, or review decisions—and refine them over time through the CLI, SDK, or API.

GEOmend accepts GEO accessions, family-SOFT files, and CSV/TSV metadata. Source data stays intact, while revisions, evidence, and prior exports remain recoverable. The cohort workflow is designed to make a useful first pass convenient and corrections inexpensive; its suggestions are not claims of scientific perfection. A separate canonical workflow requires review before mappings can enter canonical output.

Install

GEOmend requires Python 3.13 or newer. Install the cohort workflow with uv:

uv tool install 'geomend[cohort]'
geomend capabilities --json
geomend doctor --json

For the canonical reconciliation workflow, install its profiling and ontology dependencies:

uv tool install 'geomend[reconcile,ontology]'

You can also install GEOmend with pip:

python -m pip install 'geomend[cohort]'

From study list to modeling table

Create a resumable cohort project from a list of accessions and export an analysis-oriented table:

geomend cohort create --accessions-file accessions.txt --project my-cohort
geomend cohort export my-cohort --output metadata.tsv --profile analysis

The analysis export includes the sample metadata table, column annotations, and extra metadata that does not belong in the modeling table. The primary table keeps one row per study/sample, including samples with incomplete metadata. Useful measurements and covariates stay in the table while study-specific identifiers and unaligned study-level details move into context. Acquisition can resume, completed inputs are reused, and exports remain available as the project is refined.

The first pass is best effort: candidates and transformations are suggestions, not accepted scientific decisions. When a guess needs correction, inspect its evidence and update it through the same public services used by people and agents. A GUI is optional. See the cohort workflow guide for recovery, refinements, local inputs, API, and SDK usage.

Reconcile with review

Plan and run a review workspace for a local table:

geomend reconcile plan samples.tsv --output-dir plan
geomend reconcile run plan/reconcile.yaml --output-dir workspace --offline
geomend review show workspace/review.geomend.sqlite

Planning identifies fields and proposes candidate mappings. It does not accept them. Reviewers can inspect evidence and record attributable decisions through the CLI, SDK, or authenticated API. For example, assign two reviewers:

geomend review assign workspace/review.geomend.sqlite review-round \
  --reviewer reviewer-a --reviewer reviewer-b --query FIELD

Each reviewer receives a portable .geomend-review.zip packet. After review, import the returned response and export reviewed data:

geomend review import workspace/review.geomend.sqlite \
  review-round/packets/reviewer-a.geomend-response.zip
geomend export data workspace/review.geomend.sqlite reviewed-output

Canonical export is reviewed-only by default and stops rather than silently creating an empty data product. Use --allow-empty only when an empty export is intentional. Review outcomes include acceptance, nomatch, and deferral; a suggestion or ranking is never an accepted mapping by itself.

For GEO accessions and family-SOFT inputs, use geomend reconcile plan with the appropriate sources. For local CSV/TSV inputs, GEOmend creates a review-only draft registry automatically. Supply --registry TARGETS.json to use curated targets. Planning is offline; acquisition of uncached GEO accessions requires network access.

Optional features

Install extras for additional capabilities:

For example, install both cohort and ontology features with uv tool install 'geomend[cohort,ontology]'. Local LLM inference is optional; it provides evidence and proposals, not automatic acceptance. Research campaign and benchmark drivers are source-only and are not included in wheels.

Scientific and data boundaries

• Source artifacts are immutable and hash-pinned.
• A source column, target variable, ontology concept, and observed answer are different entities; similar names do not prove equivalence.
• Candidate rankings are evidence for review, not calibrated confidence or accepted mappings.
• Proposed transformations are reviewed separately from execution.
• Review changes are append-only and tied to frozen evidence.
• Exports preserve source, transformation, candidate, and reviewer lineage.

GEOmend uses the upstream LinkML-Map TransformationSpecification as the authoritative representation for reviewed transformations. Validate a specification with geomend workspace transformation validate.

Documentation

• Full documentation
• Reviewer protocol
• Multiple reviewer workflow
• CLI and JSON contracts
• Ontology and provenance
• Reconciliation outcomes
• Metadata representation vocabulary
• Artifact and curation contracts
• Repository and issue tracker