> ## Documentation Index
> Fetch the complete documentation index at: https://docs.claviscage.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Analysis Recipes

> Save a pipeline as a JSON file and load it again

# Analysis Recipes

A recipe is a pipeline written down as a small JSON file: which blocks run, in which order, with which settings, over which frames. Save one to repeat an analysis on another trajectory, to share it with a colleague, or to let a script or an AI agent prepare the pipeline for you.

## In the app

Below the **Run** button in **ANALYZE**:

* **Export recipe** downloads the current pipeline as `pipeline-YYYY-MM-DD.claviscage.json`.
* **Import recipe** reads such a file. You can also drop the file on the pipeline.

Importing replaces the pipeline and applies the recipe's settings and frame range. It never starts a run. Blocks the app does not know, such as a method from a newer release, are skipped and listed.

### Algorithms of your own in a recipe

A recipe can carry functions you enrolled yourself (see the **LIBRARY** tab). When you import one that this browser does not have yet:

1. It is added to **LIBRARY** with the **USER · UNVERIFIED** badge, unpinned.
2. Its code does not run. The pipeline leaves it out for now.
3. A notice lists it. Read the code in **LIBRARY**, then choose **Add to pipeline** or **Keep in LIBRARY only**.

If the same function (same name and code) is already in your library, the recipe uses it directly. If a different function already has its id, the imported one gets a new id, so nothing you have is overwritten.

### Methods that changed since the recipe was saved

Each engine block in a recipe records the version of its method description (`descriptorVersion`). If this app's engine describes the method with a different version, for example because its parameters or outputs changed, the block is held out of the pipeline and a notice names it. Choose **Add to pipeline** to run it anyway, or leave it out.

## Format: `claviscage.recipe/v2`

```json theme={null}
{
  "schema": "claviscage.recipe/v2",
  "engine": "claviscage-engine 0.3.16",
  "blocks": [
    { "id": "trace", "descriptorVersion": 1, "params": { "hbondCutoffNm": 0.30 } },
    { "id": "f3f4", "descriptorVersion": 1, "params": { "orderCutoffNm": 0.35 } },
    { "id": "mcg", "descriptorVersion": 1, "params": {} },
    { "id": "user:k3x9a1", "params": {} }
  ],
  "range": { "from": 1, "to": 200, "step": 10 },
  "userAlgorithms": [
    {
      "id": "user:k3x9a1",
      "name": "Four-neighbour waters",
      "output": "4-neighbour fraction",
      "code": "function analyze(frame, helpers) { /* ... */ }"
    }
  ]
}
```

| Field | Meaning |
| - | - |
| `schema` | `claviscage.recipe/v2`. Files written as `claviscage.recipe/v1` still load (they pin no versions). Any other version is refused. |
| `engine` | The engine release that wrote the file. Informational; it is not checked. |
| `blocks` | The pipeline in order. Engine ids are the ones the engine lists (`trace`, `htr`, `grade`, `chill`, `f3f4`, `steinhardt`, `mcg`, and any method added later). Ids starting with `user:` must appear in `userAlgorithms`. Unknown ids are skipped. |
| `blocks[].descriptorVersion` | The method description version the block was saved with. A mismatch holds the block until you confirm. |
| `blocks[].params.method` | Parameters of an engine method that has no dedicated settings in the app, by the parameter names its description lists. Out-of-range values fall back to the defaults. |
| `blocks[].params.hbondCutoffNm` | TRACE and HTR hydrogen-bond cutoff, 0.25–0.45 nm. |
| `blocks[].params.orderCutoffNm` | F3/F4, q̄4/q̄6 and CHILL+ neighbour cutoff, 0.30–0.40 nm. |
| `range` | First and last frame (1-based) and the step. For a `.gro` trajectory held in memory the app runs every frame and uses only `step`. |
| `userAlgorithms` | Functions of your own: `analyze(frame, helpers)` returning a number or an object of numbers. Code longer than 100,000 characters is skipped. |

The app has one hydrogen-bond cutoff and one neighbour cutoff for all blocks. When a recipe gives several values, the first valid one is used. Values outside the ranges above are ignored.

## For scripts and agents

The format is plain JSON on purpose, so any tool can write it: a Python script, a notebook, or an AI assistant asked to "count cages with TRACE and HTR on every 5th frame". Write the file, then import it in the app. The block ids are the ones `clavis_engine.list_methods()` reports in the Python package; `clavis_engine.describe_method(id)` gives each method's `descriptor_version` and parameter names.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.