io#
Load, save, import, and export your data and projects.
Import/export signals and spectra in common file formats, list and load
projects / samples / scans from the local library, and save the current data
back as a scan. save_group organises newly saved scans into folders,
and beep plays a sound to flag an event.
Base class for NMR Relaxometer devices with frequency and temperature control.
property
#
String IDs of all capabilities this object implements.
Execute a sequence.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sequence
|
Sequence[SequenceT_contra]
|
Sequence in device-specific format |
required |
Returns:
| Type | Description |
|---|---|
Sequence[Trace]
|
Execution results in device-specific format |
Check whether this object implements protocol (an isinstance check).
Connect to the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
DeviceConnConfigT
|
Device-specific connection configuration (dict or typed model) |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if connection successful |
Raises:
| Type | Description |
|---|---|
DeviceError
|
If connection fails |
InvalidTransitionError
|
If device is not in a connectable state |
Disconnect from the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
no_error
|
bool
|
Do nothing if the device is not currently connected. |
False
|
Returns:
| Type | Description |
|---|---|
bool
|
True if disconnection successful |
Raises:
| Type | Description |
|---|---|
DeviceError
|
If disconnection fails |
Configure the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
DeviceConfigT | None
|
Device-specific configuration |
None
|
Returns:
| Type | Description |
|---|---|
bool
|
True if configuration successful |
Raises:
| Type | Description |
|---|---|
DeviceError
|
If configuration fails or device not connected |
Halt any ongoing operations on the device.
Returns:
| Type | Description |
|---|---|
bool
|
True if halt successful |
Raises:
| Type | Description |
|---|---|
DeviceError
|
If halt fails or device not connected |
execute(
sequence: list[Any],
num_accum: int = 1,
record: bool = True,
report: bool = True,
) -> list[Any]
Execute a sequence with accumulation and recording options.
This is the main execution method used by DeviceAPI. Subclasses should implement _execute to handle device-specific execution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sequence
|
list[Any]
|
List of operations (BaseOp instances) |
required |
num_accum
|
int
|
Number of accumulations |
1
|
record
|
bool
|
Whether to record data |
True
|
report
|
bool
|
Whether to report progress |
True
|
Returns:
| Type | Description |
|---|---|
list[Any]
|
List of execution results (typically Trace objects) |
Validate if a sequence can be executed.
Default implementation accepts everything. Override for validation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sequence
|
Any
|
Sequence to validate |
required |
Returns:
| Type | Description |
|---|---|
tuple[bool, str]
|
Tuple of (is_valid, error_message) |
Get list of supported operation IDs.
Extracts op_id from operation classes that were registered via the @operation decorator.
Get list of supported operation classes.
Set settings from protobuf Struct.
Get connection params as Struct for RPC.
Returns connection params used to connect to this device, for persistence in project files.
Notify the system that device connection was lost unexpectedly.
Call this method from device implementations when the connection to the physical device is lost (e.g., network failure, device powered off, USB disconnected). This handles cleanup and notifies the frontend.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
reason
|
str | None
|
Optional human-readable reason for the disconnection |
None
|
Example
In your device implementation's connection monitoring:#
if connection_error_detected: self.notify_connection_lost("gRPC connection timed out")
classmethod
#
Get connection parameters schema as JSON schema.
Auto-extracts from DeviceConnConfigT type parameter. Override only if you need custom schema logic.
Returns:
| Type | Description |
|---|---|
dict
|
JSON schema dict for connection parameters UI generation |
Set frequency in MHz (Protocol requirement).
Get frequency range in MHz (Protocol requirement).
Set frequency using device-specific units.
Get frequency with device-specific units.
Set temperature (Protocol requirement).
Get target temperature (Protocol requirement).
Get temperature range (Protocol requirement).
Wait for temperature to stabilize (Protocol requirement).
Set temperature using device-specific units.
Get temperature with device-specific units.
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.
class-attribute
instance-attribute
#
Serialize this operation to a protobuf Struct.
Used for sending operations over gRPC.
class-attribute
instance-attribute
#
Serialize this operation to a protobuf Struct.
Used for sending operations over gRPC.
class-attribute
instance-attribute
#
Serialize this operation to a protobuf Struct.
Used for sending operations over gRPC.
beep(
mode: Literal[
"success", "warning", "error", "info"
] = "info",
theme: Literal[
"big-sur",
"chime",
"mario",
"material",
"pokemon",
"sonic",
"zelda",
] = "material",
) -> None
Plays an audio signal ("beep"). Can be used to indicate an important event or an error.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mode
|
Literal['success', 'warning', 'error', 'info']
|
The tone of the signal. Default: "info". |
'info'
|
theme
|
Literal['big-sur', 'chime', 'mario', 'material', 'pokemon', 'sonic', 'zelda']
|
Variation of the signal. Default: "material". |
'material'
|
export_signal(
path: str | Path,
format_id: str | None = None,
signal: Signal1D | Signal2D | None = None,
) -> bool
Export signal data to file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Output file path. |
required |
format_id
|
str | None
|
Export format ID (e.g., 'csv'). Auto-detected from extension if None. |
None
|
signal
|
Signal1D | Signal2D | None
|
Signal to export. Uses current state signal if None. |
None
|
Returns:
| Type | Description |
|---|---|
bool
|
True if export succeeded, False otherwise. |
export_spectrum(
path: str | Path,
format_id: str | None = None,
spectrum: Spectrum1D | Spectrum2D | None = None,
) -> bool
Export spectrum data to file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Output file path. |
required |
format_id
|
str | None
|
Export format ID (e.g., 'csv'). Auto-detected from extension if None. |
None
|
spectrum
|
Spectrum1D | Spectrum2D | None
|
Spectrum to export. Uses current state spectrum if None. |
None
|
Returns:
| Type | Description |
|---|---|
bool
|
True if export succeeded, False otherwise. |
Get the current save group path.
Returns:
| Type | Description |
|---|---|
str | None
|
Current group path, or None if saving to project root. |
Import a scan from file.
The imported data is loaded into State.signal and State.spectrum.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Input file path. |
required |
format_id
|
str | None
|
Import format ID. Auto-detected if None. |
None
|
Returns:
| Type | Description |
|---|---|
bool
|
True if import succeeded, False otherwise. |
List available export format IDs.
Returns:
| Type | Description |
|---|---|
list[str]
|
List of format IDs (e.g., ['csv', 'jcamp_dx', 'nmrpipe']). |
List available import format IDs.
Returns:
| Type | Description |
|---|---|
list[str]
|
List of format IDs (e.g., ['jcamp_dx', 'bruker', 'varian']). |
List all available project names.
Returns:
| Type | Description |
|---|---|
list[str]
|
List of project names. |
List all available sample names.
Returns:
| Type | Description |
|---|---|
list[str]
|
List of sample names. |
List all scan IDs in a project.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_name
|
str | None
|
Project to list scans from. Uses current project if None. |
None
|
Returns:
| Type | Description |
|---|---|
list[str]
|
List of scan IDs. |
Load a project from the repository.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Project name to load. |
required |
update_state
|
bool
|
If True, sets as current project in State. Default: True. |
True
|
Returns:
| Type | Description |
|---|---|
Project | None
|
The loaded Project, or None if not found. |
Load a sample from the repository.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Sample name to load. |
required |
update_state
|
bool
|
If True, sets as current sample in State.project. Default: True. |
True
|
Returns:
| Type | Description |
|---|---|
Sample | None
|
The loaded Sample, or None if not found. |
load_scan(
scan_id: str,
project_name: str | None = None,
update_state: bool = True,
) -> tuple[
Signal1D | Signal2D | None,
Spectrum1D | Spectrum2D | None,
]
Load a scan from the repository.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scan_id
|
str
|
Scan ID to load. |
required |
project_name
|
str | None
|
Project containing the scan. Uses current project if None. |
None
|
update_state
|
bool
|
If True, updates State.signal/spectrum/current_scan. Default: True. |
True
|
Returns:
| Type | Description |
|---|---|
tuple[Signal1D | Signal2D | None, Spectrum1D | Spectrum2D | None]
|
Tuple of (signal, spectrum), either may be None. |
save_as_scan(
signal: Signal1D | Signal2D | None = None,
spectrum: Spectrum1D | Spectrum2D | None = None,
name: str = "user_saved",
project_name: str | None = None,
group: str | None = None,
) -> str | None
Save provided signal/spectrum as a new scan in the repository.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
signal
|
Signal1D | Signal2D | None
|
Signal data to save (optional). |
None
|
spectrum
|
Spectrum1D | Spectrum2D | None
|
Spectrum data to save (optional). |
None
|
name
|
str
|
Name/label for the scan. Default: "user_saved". |
'user_saved'
|
project_name
|
str | None
|
Project to save to. Uses current project if None. |
None
|
group
|
str | None
|
Optional group/folder within the project. |
None
|
Returns:
| Type | Description |
|---|---|
str | None
|
The scan ID if successful, None otherwise. |
Context manager to set the save group for scans.
All scans saved within this context will go to the specified group. The group is created automatically if it doesn't exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
group_path
|
str
|
Group path relative to project (e.g., "January/SampleA"). Use empty string "" to save to project root. |
required |
Example
# Scans acquired in this block go to "Experiment1/Run1" folder
with io.save_group("Experiment1/Run1"):
acquire() # Saved to Project/Experiment1/Run1/scan.nscan
acquire() # Also saved there
# Back to project root
acquire() # Saved to Project/scan.nscan
# Nested groups work too
with io.save_group("January"):
with io.save_group("January/Week1"): # Absolute path
acquire() # Saved to Project/January/Week1/scan.nscan
Save a project to the repository.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project
|
Project | None
|
Project to save. Uses State.project if None. |
None
|
name
|
str | None
|
Override name for the project. Uses project.name if None. |
None
|
Returns:
| Type | Description |
|---|---|
bool
|
True if successful, False otherwise. |
Save a sample to the repository.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sample
|
Sample | None
|
Sample to save. Uses State.project.sample if None. |
None
|
name
|
str | None
|
Override name for the sample. Uses sample.name if None. |
None
|
Returns:
| Type | Description |
|---|---|
bool
|
True if successful, False otherwise. |
save_state_as_scan(
name: str = "user_saved",
project_name: str | None = None,
group: str | None = None,
) -> str | None
Save current State.signal and State.spectrum as a new scan.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Name/label for the scan. Default: "user_saved". |
'user_saved'
|
project_name
|
str | None
|
Project to save to. Uses current project if None. |
None
|
group
|
str | None
|
Optional group/folder within the project. |
None
|
Returns:
| Type | Description |
|---|---|
str | None
|
The scan ID if successful, None otherwise. |