Future House Edison Client Finch Data Analysis

---
name: finch-data-analysis
description: Hosted biological-data-analysis agent (Finch) on the FutureHouse Platform. Hands a dataset + question to Finch, which builds a Jupyter notebook that explores, analyzes, and interprets the data. Use when the user has a biological dataset (omics, imaging, clinical) and a research question, and wants a multi-step analysis with code + results, not just a literature answer.
metadata:
  skill-author: Compiled from FutureHouse edison-client (Apache-2.0)
  upstream: https://github.com/Future-House/edison-client-docs
---

# Finch — Hosted Biological Data Analysis Agent (FutureHouse Platform)

Finch is the FutureHouse hosted Jupyter-notebook agent for biological data analysis (job name `ANALYSIS`). It accepts a dataset reference and a natural-language research question, then iteratively builds a notebook — exploring the data, picking methods, generating plots, and interpreting results — finally returning the notebook plus a written conclusion.

Finch was the agent used to produce trajectories for the [BixBench benchmark](https://github.com/Future-House/bixbench) and is most at home with bioinformatics tasks (single-cell, bulk RNA-seq, variant analysis, etc.) but it works on tabular biological data generally.

For self-hosted Finch (open-source, no platform credits), see the sibling `aviary-agent-gym` and the `Future-House/finch` repo.

## Prerequisites

- `pip install edison-client`
- `EDISON_API_KEY` from <https://platform.edisonscientific.com/profile>
- Your dataset must be reachable by the platform: typically uploaded via the platform UI first, then referenced by its dataset ID. See the platform docs for upload paths.

## Minimal usage

```python
import os
from edison_client import EdisonClient, JobNames

client = EdisonClient(api_key=os.environ["EDISON_API_KEY"])

resp = client.run_tasks_until_done({
    "name": JobNames.ANALYSIS,
    "query": (
        "Using dataset GSE149859 (single-cell RNA-seq of NASH liver), "
        "identify cell-type-specific markers that differ between fibrotic and "
        "non-fibrotic samples. Report top markers per cluster and produce "
        "UMAP plots colored by condition."
    ),
})
print(resp.answer)
# resp.environment_frame contains links to the produced notebook + figure files
```

## Recipes

### Hand off a question with explicit dataset
```python
resp = client.run_tasks_until_done({
    "name": JobNames.ANALYSIS,
    "query": (
        "Dataset: <dataset_id_uploaded_to_platform>\n"
        "Question: Are there sex-specific differences in expression of clock "
        "genes (BMAL1, PER1, PER2, CRY1, CRY2) in this RNA-seq cohort?"
    ),
})
```

### Long-running analyses
Some analyses (full single-cell pipeline, large variant calling) can take 15–60 min. Use the async API to fire and poll:

```python
task_id = client.create_task({"name": JobNames.ANALYSIS, "query": "..."})
# … do other work …
status = client.get_task(task_id)
if status.status == "success":
    notebook_url = status.environment_frame["notebook_url"]
```

### Verbose output (notebook trajectory + figures)
```python
resp = client.run_tasks_until_done(
    {"name": JobNames.ANALYSIS, "query": "..."},
    verbose=True,
)
nb = resp.environment_frame["notebook"]   # nbformat-compatible dict
```

## When to use Finch vs alternatives

| Situation | Pick |
|---|---|
| Dataset already on platform; want notebook + answer | **Finch** (this skill) |
| Want to run analysis locally on your machine | self-hosted Finch (`Future-House/finch` repo) |
| No dataset — just a literature question | Crow / Falcon |
| Pure chemistry analysis (no biology) | Phoenix |

## Cost / latency / caveats

- Compute is real — analyses may take minutes to hours and consume more credits than literature jobs.
- Finch is currently bioinformatics-leaning. For non-bio data the OSS Finch (Jupyter agent) may be more flexible.
- Always inspect the produced notebook before publishing results — Finch is good but not infallible at choosing methods.