Custom Analysis - Gradiance Documentation

Custom Analysis (sometimes called “freestyle” in the API) is the assay you pick when your experiment doesn't map cleanly onto any of the named workflows. The agent reads your data, infers what you're trying to measure, and writes the Python in-line — using the same pandas / NumPy / SciPy / matplotlib stack that the dedicated workflows use under the hood.

When to reach for Custom Analysis

The assay isn't in the picker. Western densitometry, fraction-positive viral titer (Spearman-Kärber TCID₅₀), Lineweaver-Burk on a partially-inhibited enzyme, a polynomial standard curve for a colorimetric kit — all of these run through freestyle.
The model is non-standard. Power-law relationships, sigmoidal fits with a custom asymmetry, two competing models you want compared in one run.
The transformation is non-trivial. Plate-edge correction across a panel of conditions, custom normalizations (per-row blank subtraction, per-plate z-scoring), composite metrics that combine two readouts.
You want a one-off summary. A grouped mean ± SD with significance tests, a histogram of replicate-spread, a residual diagnostic the named workflows don't expose.

If your assay is in the picker, use the named workflow. They're shorter prompts (the agent already knows the model, the QC flags, and the export shape) and the prompts have been hardened against common edge cases.

What the agent will do

Freestyle runs follow the same three-step pattern as every other workflow:

Read & inspect. Load the file, identify columns, surface obvious shapes (long-format vs wide, plate vs tabular, replicate count per condition).
Fit / compute. Either call one of the dedicated fit tools (fit_dose_response_4pl, fit_standard_curve_tool, fit_enzyme_kinetics_tool, calc_qpcr_ddct, calc_tcid50, etc.) when the inferred analysis maps to one, or write inline Python with SciPy when it doesn't.
Report. Stream a report_fit payload per dataset to the viewer, then a one- to two-sentence narrative interpretation.

That structure is enforced even when the analysis is fully custom, which means freestyle results land in the same viewer, export to the same formats (PNG / SVG / PDF / CSV / Python / audit), and cite the same way as the named workflows.

Writing a prompt that lands

The agent starts from your prompt plus the file shape; the prompt is what disambiguates when the file alone is insufficient. Three rules of thumb:

Name the metric. “TCID₅₀ via Spearman-Kärber,” “normalized band intensity relative to the GAPDH lane,” “substrate-inhibited Vmax / Km / Ki via the Haldane equation.” The metric name is what the agent matches against its tool catalog.
Identify the columns when names are ambiguous. “Use the OD600_blank_subtracted column, not OD600_raw.” If column names already spell out the role (units in the header, role in the name), you can usually skip this.
State the constraint, not the implementation. “Bottom should be fixed to 0” works; “use curve_fit with bounds” is unnecessary plumbing — the agent knows the SciPy idiom.

Examples that work

Each of these is one prompt + one CSV, no further interaction:

“Fit a power-law (y = a · x^b) and report the exponent with 95% CI.”
“Compute TCID₅₀ per virus dilution with Spearman-Kärber. Cells per well are in the CellsPerWell column, dead/total counts in Dead and Total.”
“Two-way ANOVA on Yield by Strain × Temperature, with Tukey HSD on the interaction.”
“Per-plate z-score the response column, then fit a 4PL on the z-scored values.”
“Lineweaver-Burk on substrate vs initial rate, and a substrate-inhibited Michaelis-Menten on the same data; tell me which one the residuals prefer.”

Limits worth knowing

Runtime cap. Each run is bounded at 30 minutes of active agent time (waits for user input don't count). Most freestyle runs finish in under a minute; the cap exists to catch loops, not to constrain legitimate analyses.
Step cap. The agent is capped at 20 code steps per run. The standard-workflow prompts target 3 steps end-to-end; freestyle analyses use more, but anything bumping against 20 steps is usually stuck and better off being restarted with a more specific prompt.
Restricted imports. The Python executor allows numpy, pandas, scipy, matplotlib, openpyxl, plus the stdlib json / csv / typing/ functools / operator / traceback. Network modules (requests, urllib, socket) are not on the allow list, so a freestyle run can't fetch a reference dataset from the internet — upload it as a second file instead.
Reproducibility export still works. The inline Python the agent writes is captured in the same <runname>_reproducibility.py as the named workflows. A reviewer can re-run a freestyle analysis locally with NumPy + SciPy + pandas + matplotlib.

When freestyle is the wrong answer

Two cases where you should pick a named workflow even if freestyle would technically work:

You want the QC flags. Named workflows carry assay-specific QC (no upper plateau, IC₅₀ extrapolated, hook effect, efficiency drift, lag bleed-through). Freestyle does the fit but doesn't run those domain checks unless you ask.
You want a comparable headline number. An IC₅₀ from the dose-response workflow is computed as the absolute IC₅₀ when it diverges from the relative IC₅₀ by >10% (see Statistical methods); the same number from freestyle reflects whatever the agent inferred, which may be the relative form. For published comparisons, prefer the named workflow.

Reference

The run workspace

Refine, stop, share, and the live code panel.

Reference

Statistical methods

The exact algorithms behind every fit, named or freestyle.

When to reach for Custom Analysis

The assay isn't in the picker. Western densitometry, fraction-positive viral titer (Spearman-Kärber TCID₅₀), Lineweaver-Burk on a partially-inhibited enzyme, a polynomial standard curve for a colorimetric kit — all of these run through freestyle.

The model is non-standard. Power-law relationships, sigmoidal fits with a custom asymmetry, two competing models you want compared in one run.

The transformation is non-trivial. Plate-edge correction across a panel of conditions, custom normalizations (per-row blank subtraction, per-plate z-scoring), composite metrics that combine two readouts.

You want a one-off summary. A grouped mean ± SD with significance tests, a histogram of replicate-spread, a residual diagnostic the named workflows don't expose.

What the agent will do

Freestyle runs follow the same three-step pattern as every other workflow:

Read & inspect. Load the file, identify columns, surface obvious shapes (long-format vs wide, plate vs tabular, replicate count per condition).

Fit / compute. Either call one of the dedicated fit tools (fit_dose_response_4pl, fit_standard_curve_tool, fit_enzyme_kinetics_tool, calc_qpcr_ddct, calc_tcid50, etc.) when the inferred analysis maps to one, or write inline Python with SciPy when it doesn't.

Report. Stream a report_fit payload per dataset to the viewer, then a one- to two-sentence narrative interpretation.

Writing a prompt that lands

The agent starts from your prompt plus the file shape; the prompt is what disambiguates when the file alone is insufficient. Three rules of thumb:

Name the metric. “TCID₅₀ via Spearman-Kärber,” “normalized band intensity relative to the GAPDH lane,” “substrate-inhibited Vmax / Km / Ki via the Haldane equation.” The metric name is what the agent matches against its tool catalog.

Identify the columns when names are ambiguous. “Use the OD600_blank_subtracted column, not OD600_raw.” If column names already spell out the role (units in the header, role in the name), you can usually skip this.

State the constraint, not the implementation. “Bottom should be fixed to 0” works; “use curve_fit with bounds” is unnecessary plumbing — the agent knows the SciPy idiom.

Examples that work

Each of these is one prompt + one CSV, no further interaction:

“Fit a power-law (y = a · x^b) and report the exponent with 95% CI.”

“Compute TCID₅₀ per virus dilution with Spearman-Kärber. Cells per well are in the CellsPerWell column, dead/total counts in Dead and Total.”

“Two-way ANOVA on Yield by Strain × Temperature, with Tukey HSD on the interaction.”

“Per-plate z-score the response column, then fit a 4PL on the z-scored values.”

“Lineweaver-Burk on substrate vs initial rate, and a substrate-inhibited Michaelis-Menten on the same data; tell me which one the residuals prefer.”

Limits worth knowing

Runtime cap. Each run is bounded at 30 minutes of active agent time (waits for user input don't count). Most freestyle runs finish in under a minute; the cap exists to catch loops, not to constrain legitimate analyses.

Step cap. The agent is capped at 20 code steps per run. The standard-workflow prompts target 3 steps end-to-end; freestyle analyses use more, but anything bumping against 20 steps is usually stuck and better off being restarted with a more specific prompt.

Restricted imports. The Python executor allows numpy, pandas, scipy, matplotlib, openpyxl, plus the stdlib json / csv / typing/ functools / operator / traceback. Network modules (requests, urllib, socket) are not on the allow list, so a freestyle run can't fetch a reference dataset from the internet — upload it as a second file instead.

Reproducibility export still works. The inline Python the agent writes is captured in the same <runname>_reproducibility.py as the named workflows. A reviewer can re-run a freestyle analysis locally with NumPy + SciPy + pandas + matplotlib.

When freestyle is the wrong answer

Two cases where you should pick a named workflow even if freestyle would technically work:

You want the QC flags. Named workflows carry assay-specific QC (no upper plateau, IC₅₀ extrapolated, hook effect, efficiency drift, lag bleed-through). Freestyle does the fit but doesn't run those domain checks unless you ask.

You want a comparable headline number. An IC₅₀ from the dose-response workflow is computed as the absolute IC₅₀ when it diverges from the relative IC₅₀ by >10% (see Statistical methods); the same number from freestyle reflects whatever the agent inferred, which may be the relative form. For published comparisons, prefer the named workflow.