GEOmend

GEOmend downloads and combines metadata from GEO studies into a table for analysis. It profiles source fields, suggests how to align them across studies, and exports the results. You can inspect and correct those suggestions through the command line, Python SDK, or API.

GEOmend accepts GEO accessions, family-SOFT files, and CSV/TSV metadata. The cohort workflow produces an initial table without requiring a registry or review decisions. Its field groupings and transformations are provisional and may need correction. GEOmend preserves source data, revision history, evidence, and previous exports. For output that requires reviewed mappings, use the separate reviewed reconciliation workflow.

Install

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

uv tool install geomend
geomend capabilities --json
geomend doctor --json

The default install includes dependencies for cohort processing, reconciliation, ontology ingestion, and GEO verification. Learned retrieval is optional: python -m pip install 'geomend[learned]' adds PyTorch, Transformers, and Hugging Face Hub. The other named extras remain compatible with earlier installation commands.

You can also install GEOmend with pip:

python -m pip install geomend

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.

To correct an initial suggestion, inspect its evidence and update it through the CLI, SDK, or API. These interfaces apply the same review rules to people and agents. 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

Export includes only reviewed mappings by default. If none can produce output values, the command stops and explains why. Use --allow-empty when an empty export is intentional. Reviewers can accept a mapping, choose nomatch when no target applies, or defer when more evidence is needed.

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. Local LLM inference is optional; it provides evidence and proposals, not automatic acceptance. Research campaigns, training, and benchmarks live in the separate geomend-research repository. See the development boundary.

How GEOmend handles evidence and review

• GEOmend preserves source artifacts and records their hashes to detect changes.
• A source column, target variable, ontology concept, and observed answer are different entities; similar names do not prove equivalence.
• Candidate scores rank suggestions for review. They do not report calibrated confidence or approve mappings.
• Proposed transformations are reviewed separately from execution.
• New reviews are added to the history and refer to a fixed copy of the evidence.
• Exports record the sources, transformations, candidates, and reviews used to produce them.

GEOmend uses the upstream LinkML-Map TransformationSpecification as the standard format 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