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:

It is added to LIBRARY with the USER · UNVERIFIED badge, unpinned.
Its code does not run. The pipeline leaves it out for now.
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`

{
  "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.

Getting Started

Analysis Methods

Contributing

Rendering

Support

Analysis Recipes

Analysis Recipes

In the app

Algorithms of your own in a recipe

Methods that changed since the recipe was saved

Format: `claviscage.recipe/v2`

For scripts and agents

Analysis Recipes

In the app

Algorithms of your own in a recipe

Methods that changed since the recipe was saved

Format: claviscage.recipe/v2

For scripts and agents

Format: `claviscage.recipe/v2`