Data types#
Objects the APIs return or accept — fitting results, scan and graph objects, chart builders, and pulse operations.
dataclass
#
Annotation(
x: float | str | None = None,
y: float | str | None = None,
text: str | None = None,
showarrow: bool | None = None,
textangle: float | None = None,
xanchor: Literal["auto", "left", "center", "right"]
| None = None,
yanchor: Literal["auto", "top", "middle", "bottom"]
| None = None,
font: Font | dict[str, Any] | None = None,
xref: str | None = None,
yref: str | None = None,
ax: float | None = None,
ay: float | None = None,
arrowcolor: str | None = None,
arrowwidth: float | None = None,
bgcolor: str | None = None,
extras: dict[str, Any] = dict(),
)
dataclass
#
Axis(
title: str | dict[str, Any] | None = None,
range: list[float] | tuple[float, float] | None = None,
autorange: bool | Literal["reversed"] | None = None,
type: Literal["linear", "log", "date", "category"]
| None = None,
showgrid: bool | None = None,
gridcolor: str | None = None,
gridwidth: float | None = None,
zeroline: bool | None = None,
zerolinecolor: str | None = None,
zerolinewidth: float | None = None,
tickformat: str | None = None,
showticklabels: bool | None = None,
domain: list[float] | tuple[float, float] | None = None,
anchor: str | None = None,
matches: str | None = None,
nticks: int | None = None,
extras: dict[str, Any] = dict(),
)
Settings for one axis: title, range, scale, gridlines, and ticks.
Common fields: title, range=[lo, hi] (or autorange=True),
type="log" for a logarithmic scale, and showgrid.
class-attribute
instance-attribute
#
dataclass
#
Bar(
x: ArrayLike | None = None,
y: ArrayLike | None = None,
name: str | None = None,
marker: Marker | dict[str, Any] | None = None,
orientation: Literal["v", "h"] | None = None,
xaxis: str | None = None,
yaxis: str | None = None,
showlegend: bool | None = None,
visible: bool | None = None,
type: Literal["bar"] = "bar",
extras: dict[str, Any] = dict(),
)
A bar series — vertical bars by default, horizontal with orientation="h".
dataclass
#
Contour(
z: Array2D | None = None,
x: ArrayLike | None = None,
y: ArrayLike | None = None,
colorscale: Colorscale | None = None,
contours: dict[str, Any] | None = None,
line: Line | dict[str, Any] | None = None,
ncontours: int | None = None,
showcolorbar: bool | None = None,
name: str | None = None,
xaxis: str | None = None,
yaxis: str | None = None,
visible: bool | None = None,
type: Literal["contour"] = "contour",
extras: dict[str, Any] = dict(),
)
Contour lines over a 2D grid of values (a topographic-style map).
Like Heatmap, but draws lines joining equal values. ncontours
sets roughly how many levels to draw.
dataclass
#
A complete plot: one or more data series plus a Layout.
Add series with add, draw extra marks with add_shape /
add_annotation, and set titles and axes with update_layout.
All of these return the figure, so calls can be chained. Pass the finished
figure to viz.show_figure(...) or reporting.add_figure(...).
class-attribute
instance-attribute
#
add(*traces: _Trace | dict[str, Any]) -> Figure
Add one or more data series (Scatter, Bar, …) to the figure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*traces
|
_Trace | dict[str, Any]
|
The series to add. |
()
|
Returns:
| Type | Description |
|---|---|
Figure
|
The figure, so calls can be chained. |
add_annotation(
annotation: Annotation | dict[str, Any],
) -> Figure
Add a text label (optionally with an arrow) at a point on the figure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
annotation
|
Annotation | dict[str, Any]
|
The |
required |
Returns:
| Type | Description |
|---|---|
Figure
|
The figure, so calls can be chained. |
update_layout(**kwargs: Any) -> Figure
Set figure-wide options like title and axes by keyword.
For example fig.update_layout(title="...", xaxis=charts.Axis(title="...")).
Use the flat form — the xaxis_title= shorthand is not supported; pass
xaxis=charts.Axis(title=...) instead.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
**kwargs
|
Any
|
Layout fields to set (e.g. |
{}
|
Returns:
| Type | Description |
|---|---|
Figure
|
The figure, so calls can be chained. |
Export the figure as a plain dictionary.
You rarely need this directly — viz.show_figure and
reporting.add_figure call it for you. Useful if you want to inspect or
store the figure's definition. Unset options are dropped and numpy arrays
become lists.
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A |
dict[str, Any]
|
figure. |
dataclass
#
Font(
size: float | None = None,
color: str | float | None = None,
family: str | None = None,
extras: dict[str, Any] = dict(),
)
Font styling for titles, axis labels, and annotation text.
dataclass
#
Heatmap(
z: Array2D | None = None,
x: ArrayLike | None = None,
y: ArrayLike | None = None,
colorscale: Colorscale | None = None,
showcolorbar: bool | None = None,
name: str | None = None,
xaxis: str | None = None,
yaxis: str | None = None,
visible: bool | None = None,
type: Literal["heatmap"] = "heatmap",
extras: dict[str, Any] = dict(),
)
A 2D grid of values shown as colours.
z is the grid (rows × columns); optional x and y label the column
and row positions. colorscale sets the colour mapping.
dataclass
#
Layout(
title: str | dict[str, Any] | None = None,
xaxis: Axis | dict[str, Any] | None = None,
yaxis: Axis | dict[str, Any] | None = None,
xaxis2: Axis | dict[str, Any] | None = None,
xaxis3: Axis | dict[str, Any] | None = None,
xaxis4: Axis | dict[str, Any] | None = None,
yaxis2: Axis | dict[str, Any] | None = None,
yaxis3: Axis | dict[str, Any] | None = None,
yaxis4: Axis | dict[str, Any] | None = None,
showlegend: bool | None = None,
legend: dict[str, Any] | None = None,
margin: Margin | dict[str, Any] | None = None,
shapes: list[Shape | dict[str, Any]] = list(),
annotations: list[Annotation | dict[str, Any]] = list(),
paper_bgcolor: str | None = None,
plot_bgcolor: str | None = None,
height: float | None = None,
width: float | None = None,
font: Font | dict[str, Any] | None = None,
hovermode: Literal[
"x", "y", "closest", "x unified", "y unified", False
]
| None = None,
extras: dict[str, Any] = dict(),
)
The figure's overall look: title, axes, legend, margins, shapes, annotations.
Usually set through Figure.update_layout rather than constructed
directly. xaxis2/yaxis2 (and …3/…4) support extra axes for
multi-panel figures.
class-attribute
instance-attribute
#
shapes: list[Shape | dict[str, Any]] = field(
default_factory=list
)
class-attribute
instance-attribute
#
annotations: list[Annotation | dict[str, Any]] = field(
default_factory=list
)
class-attribute
instance-attribute
#
dataclass
#
Line(
color: str | None = None,
width: float | None = None,
dash: Literal[
"solid",
"dot",
"dash",
"longdash",
"dashdot",
"longdashdot",
]
| None = None,
extras: dict[str, Any] = dict(),
)
Line styling: color, width, and dash pattern.
class-attribute
instance-attribute
#
dataclass
#
Margin(
l: float | None = None,
r: float | None = None,
t: float | None = None,
b: float | None = None,
extras: dict[str, Any] = dict(),
)
Plot margins in pixels: left, right, top, bottom.
dataclass
#
Marker(
color: str | list[str] | list[float] | None = None,
size: float | list[float] | None = None,
symbol: Literal[
"circle",
"square",
"diamond",
"cross",
"x",
"triangle-up",
"triangle-down",
]
| None = None,
line: Line | dict[str, Any] | None = None,
extras: dict[str, Any] = dict(),
)
Marker styling for data points (color, size, symbol).
class-attribute
instance-attribute
#
symbol: (
Literal[
"circle",
"square",
"diamond",
"cross",
"x",
"triangle-up",
"triangle-down",
]
| None
) = None
dataclass
#
Scatter(
x: ArrayLike | None = None,
y: ArrayLike | None = None,
mode: Literal[
"lines",
"markers",
"lines+markers",
"text",
"lines+markers+text",
]
| None = None,
name: str | None = None,
line: Line | dict[str, Any] | None = None,
marker: Marker | dict[str, Any] | None = None,
fill: Literal[
"none",
"tozeroy",
"tozerox",
"tonexty",
"tonextx",
"toself",
]
| None = None,
fillcolor: str | None = None,
xaxis: str | None = None,
yaxis: str | None = None,
text: list[str] | str | None = None,
textfont: Font | dict[str, Any] | None = None,
textposition: Literal[
"top left",
"top center",
"top right",
"middle left",
"middle center",
"middle right",
"bottom left",
"bottom center",
"bottom right",
]
| None = None,
showlegend: bool | None = None,
visible: bool | None = None,
type: Literal["scatter"] = "scatter",
extras: dict[str, Any] = dict(),
)
A line and/or point series — the most common plot type.
Set mode to "lines", "markers", or "lines+markers" to choose
between a connected line, scattered points, or both. Style with line= and
marker=.
class-attribute
instance-attribute
#
mode: (
Literal[
"lines",
"markers",
"lines+markers",
"text",
"lines+markers+text",
]
| None
) = None
class-attribute
instance-attribute
#
class-attribute
instance-attribute
#
textposition: (
Literal[
"top left",
"top center",
"top right",
"middle left",
"middle center",
"middle right",
"bottom left",
"bottom center",
"bottom right",
]
| None
) = None
dataclass
#
Shape(
type: Literal[
"line", "rect", "circle", "path", "triangle"
]
| None = None,
x0: float | str | None = None,
x1: float | str | None = None,
y0: float | str | None = None,
y1: float | str | None = None,
path: str | None = None,
xref: str | None = None,
yref: str | None = None,
line: Line | dict[str, Any] | None = None,
fillcolor: str | None = None,
opacity: float | None = None,
layer: Literal["above", "below"] | None = None,
tipX: float | None = None,
tipY: float | None = None,
dx: float | None = None,
dy: float | None = None,
lengthPx: float | None = None,
widthPx: float | None = None,
label: str | None = None,
labelColor: str | None = None,
labelFontSize: float | None = None,
extras: dict[str, Any] = dict(),
)
A shape drawn over the plot to highlight a region or point.
Set type to "line", "rect", "circle", or "path" and give
its corners with x0/y0/x1/y1. A "triangle" type is also available as a
peak marker (positioned with tipX/tipY and sized with the dx/
dy/lengthPx/widthPx/label fields).
class-attribute
instance-attribute
#
What a processing graph produced when run over one scan.
Read-only. signal and spectrum give the graph's final results; the
outputs mapping holds every final output keyed by the step that produced
it. ("Final" steps are the ones whose output nothing else in the graph feeds
into.)
One stored scan, with friendly access to its data.
Read its signal, spectrum, peaks, and metadata; the heavy data
is loaded from disk only when first accessed, then kept in memory. Assigning to
signal/spectrum/peaks changes the scan in memory only — call
save to write it back to its own file on disk.
This is what every scans method hands back; you work with it instead of the
raw stored record (still reachable via .raw if you ever need it).
property
writable
#
Accumulated signal (FID) as a Signal1D/Signal2D.
property
writable
#
spectrum: Spectrum1D | Spectrum2D | None
Accumulated spectrum as a Spectrum1D/Spectrum2D.
property
writable
#
peaks: list[PeakInfo] | list[PeakInfo2D]
Picked peaks for the scan.
Returns the manually picked peaks stored on the scan if present; otherwise
the peaks from the most recent explicit perform_analysis call (empty
if none). Peaks are not auto-detected on access — call
perform_analysis to run detection.
property
#
Integration regions defined on the scan.
property
#
The underlying stored scan record, for advanced use.
Loads from disk on first access. Prefer the friendly accessors above
(signal, spectrum, peaks, metadata); reach for this only
when you need a field they don't expose.
perform_analysis(
*,
settings: PeakDetectionSettings | None = None,
adaptive: bool | None = None,
min_distance_hz: float | None = None,
min_height_ratio: float | None = None,
prominence: float | None = None,
integration_width_hz: float | None = None,
normalize_to_peak: int | None = None,
multiplet_search_width_hz: float | None = None,
) -> list[PeakInfo]
Detect peaks and compute their integrals on this scan's 1D spectrum.
Runs the same analysis the app performs (adaptive detection + integration).
Any setting not provided falls back to the user's global peak-detection
settings (project display settings), then the app defaults. The result is
stored and returned (also reflected by .peaks when there are no manual
peaks). Returns an empty list for non-1D spectra.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
settings
|
PeakDetectionSettings | None
|
A full settings object to start from (overrides the global settings as the base); individual keyword args below still win. |
None
|
adaptive
|
bool | None
|
Noise-adaptive detection. |
None
|
min_distance_hz
|
float | None
|
Minimum spacing between peaks. |
None
|
min_height_ratio
|
float | None
|
Minimum height as a fraction of the max (manual mode). |
None
|
prominence
|
float | None
|
Minimum prominence (manual mode). |
None
|
integration_width_hz
|
float | None
|
Fixed integration width (0/None = auto). |
None
|
normalize_to_peak
|
int | None
|
Peak index to normalize areas to (<0 = none). |
None
|
multiplet_search_width_hz
|
float | None
|
Multiplet clustering window. |
None
|
Write modifications back to this scan's own file on disk.
Targets the scan by id/project, so persisting an analysis scan never touches the current/active scan.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
signed
|
bool
|
Use a CFR-21-Part-11 signed save (authorship signature). |
False
|
password
|
str | None
|
Profile password (required for admin signed saves only). |
None
|
comment
|
str
|
Optional signing comment. |
''
|
preprocess(
*,
settings: PreprocessingSettings | None = None,
phase_correction: PhaseCorrectionSettings | None = None,
baseline_correction: BaselineCorrectionSettings
| None = None,
apodization: ApodizationSettings | None = None,
zero_fill: ZeroFillSettings | None = None,
fft: FftSettings | None = None,
reference_correction: ReferenceCorrectionSettings
| None = None,
) -> Scan
Apply preprocessing to this scan's 1D signal, in memory.
Runs the same pipeline as a normal scan load — apodization, zero-fill, FFT,
phase correction, baseline correction, reference correction — producing a
processed signal and spectrum. Each stage not provided falls back to the
user's global preprocessing settings (project.preprocessing_settings).
Updates .signal/.spectrum (and invalidates cached peaks) without
touching current_scan. No-op for non-1D signals. Returns self.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
settings
|
PreprocessingSettings | None
|
A full settings object to start from (the global settings are the base otherwise); the per-stage args below still win. |
None
|
phase_correction
|
PhaseCorrectionSettings | None
|
Override the phase-correction stage. |
None
|
baseline_correction
|
BaselineCorrectionSettings | None
|
Override the baseline-correction stage. |
None
|
apodization
|
ApodizationSettings | None
|
Override the apodization (window) stage. |
None
|
zero_fill
|
ZeroFillSettings | None
|
Override the zero-fill stage. |
None
|
fft
|
FftSettings | None
|
Override the FFT stage. |
None
|
reference_correction
|
ReferenceCorrectionSettings | None
|
Override the reference-correction stage. |
None
|
analyze(*, with_preprocessing: bool | None = None) -> Scan
Run the app's automatic processing on this scan (in memory).
Convenience bundle: optionally preprocess (phase correction, baseline,
etc.) then refresh peak analysis — matching what the app does on a normal
scan load, without touching current_scan. Returns self.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
with_preprocessing
|
bool | None
|
Whether to preprocess first. Defaults to the project's
|
None
|
process(graph: GraphSpec | None = None) -> GraphResult
Run a processing graph over this scan and return its outputs.
Processes this scan's signal/spectrum in the background, without changing
the active scan (scans.current) or the processor shown in the UI.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
graph
|
GraphSpec | None
|
Which graph to run — |
None
|
Returns:
| Type | Description |
|---|---|
GraphResult
|
A |
dataclass
#
FunctionAnalysisResult(
function_name: str = "unknown",
parameter_count: int = 0,
function_type: str = "unknown",
confidence: float = 0.0,
recommended_algorithm: str = "scipy",
algorithm_confidence: float = 0.0,
characteristics: dict[str, Any] = dict(),
analysis_methods: list[str] = list(),
recommendation_reason: str = "",
signature: SignatureInfo = SignatureInfo(),
source_analysis: SourceAnalysis | None = None,
name_analysis: NameAnalysis = NameAnalysis(),
numerical_analysis: NumericalAnalysis | None = None,
)
dataclass
#
SmartFittingResult(
success: bool,
parameters: tuple[float, ...],
loss: float,
message: str,
execution_time: float,
model_name: str,
n_iterations: int,
initial_guess: tuple[float, ...],
algorithm_used: str,
model_info: FunctionAnalysisResult,
data_info: DataAnalysisInfo,
auto_selected: bool,
)
Result from SmartFittingAPI.fit with comprehensive metadata.
Base class for all operations.
Operations are pure data models (Pydantic) that define their parameters. Devices are responsible for interpreting and executing operations.
Example
@operation # Decorator will register and assign ID class PulseOp(BaseOp): phase: rpc.NmrPulseDirection duration: rpc.Duration
class-attribute
instance-attribute
#
Get visualization data for this operation.
Returns a dict with visualization info or None if no visualization. Default implementation returns None - override in subclasses.
Get operation duration in nanoseconds.
Default returns 0 - override in operations with duration.
Serialize this operation to a protobuf Struct.
Used for sending operations over gRPC.