Session¶

Bases: object

Main session class for neural network parameter analysis.

Provides a high-level interface for adding models, applying computational kernels, and retrieving results. Manages the complete lifecycle of parameter analysis workflows through dependency injection and modular components.

Example

>>> session = Session()
>>> session.models.add(my_model, model_id="bert-base")
>>> session.compute.apply("frob_norm", "stable_rank")
>>> results = session.results.export_metrics(
...     "frob_norm", "stable_rank", export_format="pandas"
... )

Initialize a new session.

Parameters:

profile – Built-in profile name for quick setup: - “ram”: RAM storage, no persistence (fast experiments) - “local”: SQLite storage in .diffract/ (persistent, simple) - “hybrid”: SQLite + HDF5 (persistent, optimized for large arrays)
config_path – Path to configuration file (YAML/JSON/INI). Takes priority over profile if both are provided.
container – Pre-configured MainContainer instance. If None, creates new container using config_path or profile.
other_session – Another Session instance to copy configuration from.

filter(param_ids: list[str] | None = None, param_names: list[str] | None = None, param_types: list[ParameterType] | None = None, model_ids: list[str] | None = None) → SessionContext[source]¶

Create a filtered view of the session’s parameters and aggregates.

Parameters:

param_ids – Parameter IDs to keep, or None for no ID filtering.
param_names – Parameter names to keep, or None for no name filtering.
param_types – Parameter types to keep, or None for no type filtering.
model_ids – Model IDs to keep, or None for no model filtering.

Returns:

A SessionContext scoped to the filtered parameter and aggregate views.

exception diffract.session.SessionError[source]¶

Bases: Exception

Base exception class for session-related errors.

exception diffract.session.ModelNotFoundError[source]¶

Bases: SessionError

Raised when a model is not found in the session.

exception diffract.session.ModelAlreadyExistsError[source]¶

Bases: SessionError

Raised when a model with the same id already exists.

exception diffract.session.KernelNotFoundError[source]¶

Bases: SessionError

Raised when a kernel is not found in the registry.

Session namespaces¶

The Session API surface is organized into namespaces, available as session.models, session.compute, session.results, session.viz, and session.utils.

class diffract.session.namespaces.ModelsNamespace(session_or_context: Session | SessionContext, parameter_repository: IParameterRepository = Provide['nn.parameter_repository'], aggregate_repository: AggregateRepository = Provide['nn.aggregate_repository'], extractor_factory: Callable[..., IParameterExtractor] = Provide['nn.extractor_factory.provider'])[source]¶

Bases: object

Model management API.

add(model: Any, model_id: str | None = None, parameter_overrides: dict[str, ParameterOverrides] | None = None, custom_handlers: Iterable[ParameterHandler] | None = None) → None[source]¶

Add a neural network model to the session.

Extracts parameters from the provided model and stores them for analysis. Parameters are automatically persisted and can be retrieved in future sessions.

Parameters:

model – Neural network model object (PyTorch, TensorFlow, etc.) or a dict mapping parameter names to NumPy arrays.
model_id – Unique identifier for the model. Auto-generated if None.
parameter_overrides – Custom parameter extraction overrides by name.
custom_handlers – Additional parameter handlers for custom parameter types.

Raises:

ModelAlreadyExistsError – If model_id already exists in the session.
SessionError – If parameter extraction fails or yields no parameters.

rename(model_id: str, new_model_id: str) → None[source]¶

Rename a model in the session.

Parameters:

model_id – ID of the model to rename.
new_model_id – New ID for the model.

Raises:

ModelNotFoundError – If model_id does not exist.
ModelAlreadyExistsError – If new_model_id already exists.

erase(*model_ids: str, erase_all: bool = False) → None[source]¶

Erase all parameters and results for specified models.

Removes model parameters from both memory and persistent storage. Use with caution as this operation cannot be undone.

Parameters:

*model_ids – Model IDs to erase. Required if erase_all is False.
erase_all – If True, erases all models. model_ids must be empty.

Raises:

ValueError – If neither model_ids nor erase_all is specified, or if both are specified.
ModelNotFoundError – If any specified model ID is not found.

list() → list[str][source]¶

List all model IDs currently in the session.

Returns:: Sorted list of unique model IDs present in the session.

class diffract.session.namespaces.ComputeNamespace(session_or_context: Session | SessionContext, parameter_repository: IParameterRepository = Provide['nn.parameter_repository'], kernel_registry: KernelRegistry = Provide['compute.kernel_registry'], kernel_executor_factory: Callable[[], KernelExecutor] = Provide['compute.kernel_executor.provider'])[source]¶

Bases: object

Kernel compute API for Session.

apply(*fields_to_produce: str) → None[source]¶

Apply computational kernels to stored parameters.

Executes the specified kernels on filtered parameters in dependency order. Results are automatically stored and can be retrieved using export_metrics().

Parameters:

*fields_to_produce – Names of fields to compute using registered kernels.

Raises:

KernelNotFoundError – If any specified field cannot be produced.
SessionError – If kernel execution fails.

list_available_kernels(verbose: bool = False) → list[str][source]¶

List all available computational kernels.

Parameters:: verbose – If True, include detailed kernel information including dependencies and field requirements.
Returns:: List of kernel names or detailed kernel descriptions.

list_available_metrics(verbose: bool = False) → list[str][source]¶

List all fields that can be computed by registered kernels.

Parameters:: verbose – If True, include detailed field information including producing kernels and dependencies.
Returns:: List of computable field names or detailed field descriptions.

configure_kernel(kernel_name: str, **config: Any) → None[source]¶

Configure parameters for a specific kernel.

Updates the configuration for a registered kernel, affecting subsequent computations using that kernel.

Parameters:

kernel_name – Name of kernel to configure.
**config – Kernel configuration parameters as keyword arguments.

Raises:

KernelNotFoundError – If kernel is not registered in the registry.

kernel(_func: Callable[..., Any] | None = None, *, name: str | None = None, require_fields: tuple[str, ...] | None = None, produce_fields: tuple[str, ...] | None = None, apply_level: KernelApplyLevel = KernelApplyLevel.PARAMETER, execution_protocol: KernelExecutionProtocol = KernelExecutionProtocol.SEQUENTIAL, restrictions: KernelRestrictions | None = None) → Callable[[Callable[..., Any]], Callable[..., Any]][source]¶

Decorator for registering custom kernels in the session registry.

Creates a kernel that can compute metrics on neural network parameters. Dependencies are automatically inferred from function arguments.

Parameters:

name – Custom kernel name (defaults to function name).
require_fields – Input field names (inferred from signature if None).
produce_fields – Output field names (defaults to kernel name).
apply_level – Granularity at which the kernel is applied.
execution_protocol – Execution protocol for the kernel.
restrictions – Optional restrictions applied to kernel execution.

Returns:

Decorator function for registering the kernel.

Example

>>> session = Session()
>>> with session:
...
...     @session.compute.kernel()
...     def my_metric(frob_norm: float, *, scale: float = 1.0) -> float:
...         return frob_norm * scale

class diffract.session.namespaces.ResultsNamespace(session_or_context: Session | SessionContext, parameter_repository: IParameterRepository = Provide['nn.parameter_repository'], aggregate_repository: AggregateRepository = Provide['nn.aggregate_repository'], kernel_registry: KernelRegistry = Provide['compute.kernel_registry'], parallel_context_factory: Callable[[], ParallelContext] = Provide['parallel_singleton.thread_pool_context.provider'], results_exporter_factory: Callable[[tuple[str, ...], IParameterView, str], Any] = Provide['export.result_exporter.provider'], default_export_format: str | None = Provide['export.config.default_export_format'])[source]¶

Bases: object

Results export and ingestion API for Session.

export_metrics(*fields: str, export_format: str | None = None) → Any[source]¶

Retrieve computation results for specified fields (metrics only).

Parameters:

*fields – Field names to retrieve.
export_format – Output format - “dict”, “json”, “pandas”, “polars”, “list”. Defaults to the configured [export] default_export_format.

Returns:

Metric results in the specified format.

export_aggregates(*fields: str, export_format: str | None = None) → Any[source]¶

Retrieve aggregation results for specified fields (aggregates only).

Parameters:

*fields – Field names to retrieve.
export_format – Output format - “dict”, “json”, “pandas”, “polars”, “list”. Defaults to the configured [export] default_export_format.

Returns:

Aggregation results in the specified format.

ingest_metrics(fields_by_uid: dict[str, dict[str, Any]], *, force: bool = False) → None[source]¶

Ingest precomputed fields into the session via a uid->field mapping.

Field names are stored exactly as provided (including contextual suffixes like “metric@ctx”). By default, this method is strict and raises if any target field already exists; set force=True to overwrite.

Parameters:

fields_by_uid – Mapping of parameter uid -> {field_name: value}.
force – If False (default), raise on any existing field conflict. If True, overwrite existing field values.

Raises:

SessionError – If unknown uids are provided or conflicts are detected (force=False).

ingest_aggregates(aggregates: list[dict[str, Any]], *, force: bool = False) → None[source]¶

Ingest precomputed aggregate values into the session.

Each aggregate is identified by (field_name, context_models, context_params). Useful for importing precomputed aggregation results.

Parameters:

aggregates – List of aggregate dictionaries, each containing: - field_name: Base field name (e.g., “l_overlap”). - context_models: Tuple/list of model IDs. - context_params: Tuple/list of parameter names (optional). - value: The computed value to store.
force – If False (default), raise on existing aggregate conflict. If True, overwrite existing values.

Raises:

SessionError – If aggregate structure is invalid or conflicts are detected (force=False).

erase(*fields_to_erase: str, erase_dependent_also: bool = False, erase_all: bool = False) → None[source]¶

Erase computation results for specified fields.

Removes computed field data from parameters while preserving the parameters themselves. Optionally erases dependent fields that rely on the specified fields as inputs.

Parameters:

*fields_to_erase – Field names to erase. Required if erase_all is False.
erase_dependent_also – If True, also erases fields that depend on the specified fields.
erase_all – If True, erases all computed fields. fields_to_erase must be empty.

Raises:

ValueError – If neither fields_to_erase nor erase_all is specified, or if both are specified.
KernelNotFoundError – If any specified field cannot be produced by registered kernels.

export(*fields: str, sources: str = 'all', export_format: str | None = None, expand_contextual: bool = True) → Any[source]¶

Unified export of metrics and aggregates.

This method provides a single interface for exporting both parameter metrics and aggregate values. When both sources are requested, aggregate values are merged into parameter entries as contextual fields.

Parameters:

*fields – Field names to retrieve.
sources – Data sources to include - “metrics”, “aggregates”, or “all”.
export_format – Output format - “dict”, “json”, “pandas”, “polars”, “list”. Defaults to the configured [export] default_export_format.
expand_contextual – When True and sources=”all”, merge aggregate values into parameter entries as contextual field names.

Returns:

Results in the specified format.

class diffract.session.namespaces.VizNamespace(session_or_context: Session | SessionContext)[source]¶

Bases: object

Visualization API for Session.

Provides multiple ways to create visualizations:

Simple methods (recommended for quick exploration):

>>> session.viz.box(y="stable_rank", x="model_id")
>>> session.viz.scatter(x="frob_norm", y="stable_rank")

Plot objects (for Hydra configs and advanced customization):

>>> from diffract.viz.plots.boxplot import BoxPlot
>>> session.viz.draw(plot=BoxPlot(y="stable_rank", x="model_id"))

Config files (for reproducible workflows):

>>> session.viz.draw(config_path="plots/boxplot.yaml")

Grid helpers (for subplot dashboards and bound grids):

>>> session.viz.grid(subplots=[...])
>>> session.viz.bound_grid(plot_template=..., row=..., col=...)

Render a Plotly figure using the viz module.

Provide either plot (a Plot object) or config_path (a Hydra YAML file).

Parameters:

plot – A Plot instance to render.
config_path – Path to a Hydra YAML config file.
overrides – Hydra overrides to apply (only with config_path).
theme – A Theme instance to apply.
theme_path – Path to a YAML file with theme config.

box(*, y: str | FieldRef, x: str | FieldRef, title: str | None = None, value_filter: dict[str, tuple[str, Any]] | None = None, box_width: float = 0.5, boxpoints: Literal['all', 'outliers', False] = 'outliers', jitter_enabled: bool = False, jitter_width: float = 0.12, jitter_offset: float = -0.35, jitter_seed: int = 42, jitter_density_scale: bool = True, jitter_color: str | FieldRef | None = None, jitter_colorscale: str = 'Viridis', x_title: str | None = None, x_showticklabels: bool = True, x_tickangle: int | None = None, x_tickfont_size: int | None = None, x_tickfont_family: str | None = None, x_tickfont_color: str | None = None, x_showgrid: bool = True, x_gridcolor: str | None = None, x_showline: bool = True, x_linecolor: str | None = None, y_title: str | None = None, y_showticklabels: bool = True, y_tickangle: int | None = None, y_tickfont_size: int | None = None, y_tickfont_family: str | None = None, y_tickfont_color: str | None = None, y_showgrid: bool = True, y_gridcolor: str | None = None, y_showline: bool = True, y_linecolor: str | None = None, y_range: tuple[float, float] | None = None, y_dtick: float | str | None = None, y_tick0: float | None = None, y_tickformat: str | None = None, y_zeroline: bool = False, y_zerolinecolor: str | None = None, marker_coloraxis_id: int | None = None, marker_colorscale: str = 'Viridis', marker_showscale: bool = True, marker_cmin: float | None = None, marker_cmax: float | None = None, marker_colorbar_title: str | None = None, marker_coloraxis_override: bool = False, marker_size: str | FieldRef | float | None = 6, marker_size_range: tuple[float, float] | None = None, marker_opacity: str | FieldRef | float | None = 0.7, marker_opacity_range: tuple[float, float] | None = None, marker_color: str | FieldRef | None = None, marker_symbol: str | FieldRef | None = None, theme: Theme | None = None, theme_path: str | Path | None = None) → go.Figure¶

Create a box plot.

Parameters:

self – The bound viz namespace providing the draw() method.
y – Field for vertical values (field name or FieldRef).
x – Field for categories (field name or FieldRef).
title – Figure title.
value_filter – Filter entries by field values.
box_width – Width of boxes.
boxpoints – Show points: “all”, “outliers”, or False.
jitter_enabled – Enable the jitter overlay of individual points.
jitter_width – Horizontal spread of the jitter overlay.
jitter_offset – Horizontal offset of the jitter overlay from the box.
jitter_seed – Random seed for the jitter overlay.
jitter_density_scale – Scale jitter spread by local point density.
jitter_color – Field or color for jitter points.
jitter_colorscale – Colorscale for jitter points.
x_title – X-axis title.
x_showticklabels – Show x-axis tick labels.
x_tickangle – Angle of x-axis tick labels.
x_tickfont_size – Font size of x-axis tick labels.
x_tickfont_family – Font family of x-axis tick labels.
x_tickfont_color – Font color of x-axis tick labels.
x_showgrid – Show x-axis grid lines.
x_gridcolor – Color of x-axis grid lines.
x_showline – Show the x-axis line.
x_linecolor – Color of the x-axis line.
y_title – Y-axis title.
y_showticklabels – Show y-axis tick labels.
y_tickangle – Angle of y-axis tick labels.
y_tickfont_size – Font size of y-axis tick labels.
y_tickfont_family – Font family of y-axis tick labels.
y_tickfont_color – Font color of y-axis tick labels.
y_showgrid – Show y-axis grid lines.
y_gridcolor – Color of y-axis grid lines.
y_showline – Show the y-axis line.
y_linecolor – Color of the y-axis line.
y_range – Y-axis value range.
y_dtick – Y-axis tick step.
y_tick0 – Y-axis starting tick.
y_tickformat – Y-axis tick format string.
y_zeroline – Show the y-axis zero line.
y_zerolinecolor – Color of the y-axis zero line.
marker_coloraxis_id – Shared color axis id for markers.
marker_colorscale – Colorscale for markers.
marker_showscale – Show the marker colorbar.
marker_cmin – Minimum value for marker color mapping.
marker_cmax – Maximum value for marker color mapping.
marker_colorbar_title – Title of the marker colorbar.
marker_coloraxis_override – Override the shared marker color axis.
marker_size – Field or fixed size for markers.
marker_size_range – Range to scale marker sizes into.
marker_opacity – Field or fixed opacity for markers.
marker_opacity_range – Range to scale marker opacity into.
marker_color – Field or color for markers.
marker_symbol – Field or symbol for markers.
theme – Theme to apply to the figure.
theme_path – Path to a theme file to apply to the figure.

Returns:

Plotly Figure.

Example

>>> session.viz.box(y="stable_rank", x="model_id", marker_color="layer_id")

grid(*, subplots: list[SubplotSpec], make_subplots_kwargs: dict[str, Any] | None = None, theme: Theme | None = None, theme_path: str | Path | None = None) → go.Figure¶: Create and render a GridPlot from explicit subplot specifications.

Create and render a bound grid generated from row/column axis binds.

For plot binds targeting FieldRef plot attributes, plain string bind values are automatically converted into FieldRef(field=…). The same conversion is applied to cell_rules[*].plot overrides.

violin(*, y: str | FieldRef, x: str | FieldRef, title: str | None = None, value_filter: dict[str, tuple[str, Any]] | None = None, points: Literal['all', 'outliers', False] = 'outliers', box_visible: bool = True, meanline_visible: bool = True, side: Literal['positive', 'negative', 'both'] = 'positive', bandwidth: float | None = None, jitter_enabled: bool = False, jitter_width: float = 0.12, jitter_offset: float = -0.35, jitter_seed: int = 42, jitter_density_scale: bool = True, jitter_color: str | FieldRef | None = None, jitter_colorscale: str = 'Viridis', x_title: str | None = None, x_showticklabels: bool = True, x_tickangle: int | None = None, x_tickfont_size: int | None = None, x_tickfont_family: str | None = None, x_tickfont_color: str | None = None, x_showgrid: bool = True, x_gridcolor: str | None = None, x_showline: bool = True, x_linecolor: str | None = None, y_title: str | None = None, y_showticklabels: bool = True, y_tickangle: int | None = None, y_tickfont_size: int | None = None, y_tickfont_family: str | None = None, y_tickfont_color: str | None = None, y_showgrid: bool = True, y_gridcolor: str | None = None, y_showline: bool = True, y_linecolor: str | None = None, y_range: tuple[float, float] | None = None, y_dtick: float | str | None = None, y_tick0: float | None = None, y_tickformat: str | None = None, y_zeroline: bool = False, y_zerolinecolor: str | None = None, marker_coloraxis_id: int | None = None, marker_colorscale: str = 'Viridis', marker_showscale: bool = True, marker_cmin: float | None = None, marker_cmax: float | None = None, marker_colorbar_title: str | None = None, marker_coloraxis_override: bool = False, marker_size: str | FieldRef | float | None = 6, marker_size_range: tuple[float, float] | None = None, marker_opacity: str | FieldRef | float | None = 0.7, marker_opacity_range: tuple[float, float] | None = None, marker_color: str | FieldRef | None = None, marker_symbol: str | FieldRef | None = None, theme: Theme | None = None, theme_path: str | Path | None = None) → go.Figure¶

Create a violin plot.

Parameters:

self – The bound viz namespace providing the draw() method.
y – Field for vertical values (field name or FieldRef).
x – Field for categories (field name or FieldRef).
title – Figure title.
value_filter – Filter entries by field values.
points – Show points: “all”, “outliers”, or False.
box_visible – Show inner box.
meanline_visible – Show mean line.
side – Which side to draw: “positive”, “negative”, or “both”.
bandwidth – Violin kernel bandwidth (None = auto).
jitter_enabled – Enable the jitter overlay of individual points.
jitter_width – Horizontal spread of the jitter overlay.
jitter_offset – Horizontal offset of the jitter overlay from the violin.
jitter_seed – Random seed for the jitter overlay.
jitter_density_scale – Scale jitter spread by local point density.
jitter_color – Field or color for jitter points.
jitter_colorscale – Colorscale for jitter points.
x_title – X-axis title.
x_showticklabels – Show x-axis tick labels.
x_tickangle – Angle of x-axis tick labels.
x_tickfont_size – Font size of x-axis tick labels.
x_tickfont_family – Font family of x-axis tick labels.
x_tickfont_color – Font color of x-axis tick labels.
x_showgrid – Show x-axis grid lines.
x_gridcolor – Color of x-axis grid lines.
x_showline – Show the x-axis line.
x_linecolor – Color of the x-axis line.
y_title – Y-axis title.
y_showticklabels – Show y-axis tick labels.
y_tickangle – Angle of y-axis tick labels.
y_tickfont_size – Font size of y-axis tick labels.
y_tickfont_family – Font family of y-axis tick labels.
y_tickfont_color – Font color of y-axis tick labels.
y_showgrid – Show y-axis grid lines.
y_gridcolor – Color of y-axis grid lines.
y_showline – Show the y-axis line.
y_linecolor – Color of the y-axis line.
y_range – Y-axis value range.
y_dtick – Y-axis tick step.
y_tick0 – Y-axis starting tick.
y_tickformat – Y-axis tick format string.
y_zeroline – Show the y-axis zero line.
y_zerolinecolor – Color of the y-axis zero line.
marker_coloraxis_id – Shared color axis id for markers.
marker_colorscale – Colorscale for markers.
marker_showscale – Show the marker colorbar.
marker_cmin – Minimum value for marker color mapping.
marker_cmax – Maximum value for marker color mapping.
marker_colorbar_title – Title of the marker colorbar.
marker_coloraxis_override – Override the shared marker color axis.
marker_size – Field or fixed size for markers.
marker_size_range – Range to scale marker sizes into.
marker_opacity – Field or fixed opacity for markers.
marker_opacity_range – Range to scale marker opacity into.
marker_color – Field or color for markers.
marker_symbol – Field or symbol for markers.
theme – Theme to apply to the figure.
theme_path – Path to a theme file to apply to the figure.

Returns:

Plotly Figure.

Example

>>> session.viz.violin(y="weights_svals", x="model_id", jitter_enabled=True)

Create a scatter plot.

Each entry becomes a point. group_by splits entries into separate traces.

Parameters:

self – The bound viz namespace providing the draw() method.
x – Field for horizontal values (field name or FieldRef).
y – Field for vertical values (field name or FieldRef).
title – Figure title.
value_filter – Filter entries by field values.
group_by – Field to group points into traces (field name or FieldRef or None).
x_title – X-axis title.
x_showticklabels – Show x-axis tick labels.
x_tickangle – Angle of x-axis tick labels.
x_tickfont_size – Font size of x-axis tick labels.
x_tickfont_family – Font family of x-axis tick labels.
x_tickfont_color – Font color of x-axis tick labels.
x_showgrid – Show x-axis grid lines.
x_gridcolor – Color of x-axis grid lines.
x_showline – Show the x-axis line.
x_linecolor – Color of the x-axis line.
x_range – X-axis value range.
x_dtick – X-axis tick step.
x_tick0 – X-axis starting tick.
x_tickformat – X-axis tick format string.
x_zeroline – Show the x-axis zero line.
x_zerolinecolor – Color of the x-axis zero line.
y_title – Y-axis title.
y_showticklabels – Show y-axis tick labels.
y_tickangle – Angle of y-axis tick labels.
y_tickfont_size – Font size of y-axis tick labels.
y_tickfont_family – Font family of y-axis tick labels.
y_tickfont_color – Font color of y-axis tick labels.
y_showgrid – Show y-axis grid lines.
y_gridcolor – Color of y-axis grid lines.
y_showline – Show the y-axis line.
y_linecolor – Color of the y-axis line.
y_range – Y-axis value range.
y_dtick – Y-axis tick step.
y_tick0 – Y-axis starting tick.
y_tickformat – Y-axis tick format string.
y_zeroline – Show the y-axis zero line.
y_zerolinecolor – Color of the y-axis zero line.
marker_coloraxis_id – Shared color axis id for markers.
marker_colorscale – Colorscale for markers.
marker_showscale – Show the marker colorbar.
marker_cmin – Minimum value for marker color mapping.
marker_cmax – Maximum value for marker color mapping.
marker_colorbar_title – Title of the marker colorbar.
marker_coloraxis_override – Override the shared marker color axis.
marker_size – Field or fixed size for markers.
marker_size_range – Range to scale marker sizes into.
marker_opacity – Field or fixed opacity for markers.
marker_opacity_range – Range to scale marker opacity into.
marker_color – Field or color for markers.
marker_symbol – Field or symbol for markers.
theme – Theme to apply to the figure.
theme_path – Path to a theme file to apply to the figure.

Returns:

Plotly Figure.

Example

>>> session.viz.scatter(
...     x="frob_norm",
...     y="stable_rank",
...     marker_color="model_id",
...     marker_size="layer_id",
... )

heatmap(*, z: str | FieldRef, x: str | FieldRef, y: str | FieldRef, title: str | None = None, value_filter: dict[str, tuple[str, Any]] | None = None, fill_value: float = float('nan'), show_text: bool = False, text_format: str = '.2f', text_font_size: int = 10, reverse_y: bool = True, x_title: str | None = None, x_showticklabels: bool = True, x_tickangle: int | None = None, x_tickfont_size: int | None = None, x_tickfont_family: str | None = None, x_tickfont_color: str | None = None, x_showgrid: bool = True, x_gridcolor: str | None = None, x_showline: bool = True, x_linecolor: str | None = None, x_categoryorder: str | None = None, x_categoryarray: list[str] | None = None, y_title: str | None = None, y_showticklabels: bool = True, y_tickangle: int | None = None, y_tickfont_size: int | None = None, y_tickfont_family: str | None = None, y_tickfont_color: str | None = None, y_showgrid: bool = True, y_gridcolor: str | None = None, y_showline: bool = True, y_linecolor: str | None = None, y_categoryorder: str | None = None, y_categoryarray: list[str] | None = None, heatmap_coloraxis_id: int | None = None, heatmap_colorscale: str = 'Viridis', heatmap_showscale: bool = True, heatmap_cmin: float | None = None, heatmap_cmax: float | None = None, heatmap_colorbar_title: str | None = None, heatmap_coloraxis_override: bool = False, theme: Theme | None = None, theme_path: str | Path | None = None) → go.Figure¶

Create a heatmap by pivoting a scalar field.

Parameters:

self – The bound viz namespace providing the draw() method.
z – Field for cell values (field name or FieldRef).
x – Field for columns (field name or FieldRef).
y – Field for rows (field name or FieldRef).
title – Figure title.
value_filter – Filter entries by field values.
fill_value – Value for missing (x, y) cells.
show_text – Show cell values as text.
text_format – Format string for text (e.g. “.2f”).
text_font_size – Font size for cell text.
reverse_y – Reverse y-axis so first row is at top.
x_title – X-axis title.
x_showticklabels – Show x-axis tick labels.
x_tickangle – Angle of x-axis tick labels.
x_tickfont_size – Font size of x-axis tick labels.
x_tickfont_family – Font family of x-axis tick labels.
x_tickfont_color – Font color of x-axis tick labels.
x_showgrid – Show x-axis grid lines.
x_gridcolor – Color of x-axis grid lines.
x_showline – Show the x-axis line.
x_linecolor – Color of the x-axis line.
x_categoryorder – Ordering strategy for x-axis categories.
x_categoryarray – Explicit ordering of x-axis categories.
y_title – Y-axis title.
y_showticklabels – Show y-axis tick labels.
y_tickangle – Angle of y-axis tick labels.
y_tickfont_size – Font size of y-axis tick labels.
y_tickfont_family – Font family of y-axis tick labels.
y_tickfont_color – Font color of y-axis tick labels.
y_showgrid – Show y-axis grid lines.
y_gridcolor – Color of y-axis grid lines.
y_showline – Show the y-axis line.
y_linecolor – Color of the y-axis line.
y_categoryorder – Ordering strategy for y-axis categories.
y_categoryarray – Explicit ordering of y-axis categories.
heatmap_coloraxis_id – Shared color axis id for the heatmap.
heatmap_colorscale – Colorscale for the heatmap.
heatmap_showscale – Show the heatmap colorbar.
heatmap_cmin – Minimum value for heatmap color mapping.
heatmap_cmax – Maximum value for heatmap color mapping.
heatmap_colorbar_title – Title of the heatmap colorbar.
heatmap_coloraxis_override – Override the shared heatmap color axis.
theme – Theme to apply to the figure.
theme_path – Path to a theme file to apply to the figure.

Returns:

Plotly Figure.

Example

>>> session.viz.heatmap(z="stable_rank", x="head_id", y="layer_id")

Create a line plot of a field vs a metadata key.

Automatically computes mean and std for duplicate x values. Each group (group_by) becomes a separate line trace.

Parameters:

y – Field for vertical values (field name or FieldRef).
x – Field for horizontal axis (field name or FieldRef).
title – Figure title.
value_filter – Filter entries by field values.
group_by – Field to group series by (field name or FieldRef or None).
mode – “lines”, “markers”, or “lines+markers”.
show_bands – Show mean ± std bands.
band_opacity – Opacity of std band fill.
band_line_width – Line width for band edges.
self – The bound viz namespace providing the draw() method.
x_title – X-axis title.
x_showticklabels – Show x-axis tick labels.
x_tickangle – Angle of x-axis tick labels.
x_tickfont_size – Font size of x-axis tick labels.
x_tickfont_family – Font family of x-axis tick labels.
x_tickfont_color – Font color of x-axis tick labels.
x_showgrid – Show x-axis grid lines.
x_gridcolor – Color of x-axis grid lines.
x_showline – Show the x-axis line.
x_linecolor – Color of the x-axis line.
x_categoryorder – Ordering strategy for x-axis categories.
x_categoryarray – Explicit ordering of x-axis categories.
x_range – X-axis value range.
x_dtick – X-axis tick step.
x_tick0 – X-axis starting tick.
x_tickformat – X-axis tick format string.
x_zeroline – Show the x-axis zero line.
x_zerolinecolor – Color of the x-axis zero line.
x_axis_mode – Force the x-axis data type (“numeric” or “categorical”); inferred from the data when None.
y_title – Y-axis title.
y_showticklabels – Show y-axis tick labels.
y_tickangle – Angle of y-axis tick labels.
y_tickfont_size – Font size of y-axis tick labels.
y_tickfont_family – Font family of y-axis tick labels.
y_tickfont_color – Font color of y-axis tick labels.
y_showgrid – Show y-axis grid lines.
y_gridcolor – Color of y-axis grid lines.
y_showline – Show the y-axis line.
y_linecolor – Color of the y-axis line.
y_range – Y-axis value range.
y_dtick – Y-axis tick step.
y_tick0 – Y-axis starting tick.
y_tickformat – Y-axis tick format string.
y_zeroline – Show the y-axis zero line.
y_zerolinecolor – Color of the y-axis zero line.
line_coloraxis_id – Shared color axis id for lines.
line_colorscale – Colorscale for lines.
line_showscale – Show the line colorbar.
line_cmin – Minimum value for line color mapping.
line_cmax – Maximum value for line color mapping.
line_colorbar_title – Title of the line colorbar.
line_coloraxis_override – Override the shared line color axis.
line_width – Field or fixed width for lines.
line_width_range – Range to scale line widths into.
line_color – Field or color for lines.
line_dash – Field or dash style for lines.
line_shape – Line interpolation shape.
line_smoothing – Line smoothing factor.
marker_coloraxis_id – Shared color axis id for markers.
marker_colorscale – Colorscale for markers.
marker_showscale – Show the marker colorbar.
marker_cmin – Minimum value for marker color mapping.
marker_cmax – Maximum value for marker color mapping.
marker_colorbar_title – Title of the marker colorbar.
marker_coloraxis_override – Override the shared marker color axis.
marker_size – Field or fixed size for markers.
marker_size_range – Range to scale marker sizes into.
marker_opacity – Field or fixed opacity for markers.
marker_opacity_range – Range to scale marker opacity into.
marker_color – Field or color for markers.
marker_symbol – Field or symbol for markers.
theme – Theme to apply to the figure.
theme_path – Path to a theme file to apply to the figure.

Returns:

Plotly Figure.

Example

>>> session.viz.line(y="stable_rank", x="in_model_idx", group_by="model_id")

Create a line plot of a field vs a metadata key.

Automatically computes mean and std for duplicate x values. Each group (group_by) becomes a separate line trace.

Parameters:

y – Field for vertical values (field name or FieldRef).
x – Field for horizontal axis (field name or FieldRef).
title – Figure title.
value_filter – Filter entries by field values.
group_by – Field to group series by (field name or FieldRef or None).
mode – “lines”, “markers”, or “lines+markers”.
show_bands – Show mean ± std bands.
band_opacity – Opacity of std band fill.
band_line_width – Line width for band edges.
self – The bound viz namespace providing the draw() method.
x_title – X-axis title.
x_showticklabels – Show x-axis tick labels.
x_tickangle – Angle of x-axis tick labels.
x_tickfont_size – Font size of x-axis tick labels.
x_tickfont_family – Font family of x-axis tick labels.
x_tickfont_color – Font color of x-axis tick labels.
x_showgrid – Show x-axis grid lines.
x_gridcolor – Color of x-axis grid lines.
x_showline – Show the x-axis line.
x_linecolor – Color of the x-axis line.
x_categoryorder – Ordering strategy for x-axis categories.
x_categoryarray – Explicit ordering of x-axis categories.
x_range – X-axis value range.
x_dtick – X-axis tick step.
x_tick0 – X-axis starting tick.
x_tickformat – X-axis tick format string.
x_zeroline – Show the x-axis zero line.
x_zerolinecolor – Color of the x-axis zero line.
x_axis_mode – Force the x-axis data type (“numeric” or “categorical”); inferred from the data when None.
y_title – Y-axis title.
y_showticklabels – Show y-axis tick labels.
y_tickangle – Angle of y-axis tick labels.
y_tickfont_size – Font size of y-axis tick labels.
y_tickfont_family – Font family of y-axis tick labels.
y_tickfont_color – Font color of y-axis tick labels.
y_showgrid – Show y-axis grid lines.
y_gridcolor – Color of y-axis grid lines.
y_showline – Show the y-axis line.
y_linecolor – Color of the y-axis line.
y_range – Y-axis value range.
y_dtick – Y-axis tick step.
y_tick0 – Y-axis starting tick.
y_tickformat – Y-axis tick format string.
y_zeroline – Show the y-axis zero line.
y_zerolinecolor – Color of the y-axis zero line.
line_coloraxis_id – Shared color axis id for lines.
line_colorscale – Colorscale for lines.
line_showscale – Show the line colorbar.
line_cmin – Minimum value for line color mapping.
line_cmax – Maximum value for line color mapping.
line_colorbar_title – Title of the line colorbar.
line_coloraxis_override – Override the shared line color axis.
line_width – Field or fixed width for lines.
line_width_range – Range to scale line widths into.
line_color – Field or color for lines.
line_dash – Field or dash style for lines.
line_shape – Line interpolation shape.
line_smoothing – Line smoothing factor.
marker_coloraxis_id – Shared color axis id for markers.
marker_colorscale – Colorscale for markers.
marker_showscale – Show the marker colorbar.
marker_cmin – Minimum value for marker color mapping.
marker_cmax – Maximum value for marker color mapping.
marker_colorbar_title – Title of the marker colorbar.
marker_coloraxis_override – Override the shared marker color axis.
marker_size – Field or fixed size for markers.
marker_size_range – Range to scale marker sizes into.
marker_opacity – Field or fixed opacity for markers.
marker_opacity_range – Range to scale marker opacity into.
marker_color – Field or color for markers.
marker_symbol – Field or symbol for markers.
theme – Theme to apply to the figure.
theme_path – Path to a theme file to apply to the figure.

Returns:

Plotly Figure.

Example

>>> session.viz.line(y="stable_rank", x="in_model_idx", group_by="model_id")

class diffract.session.namespaces.UtilsNamespace(session_or_context: Session | SessionContext, parameter_repository: IParameterRepository = Provide['nn.parameter_repository'], aggregate_repository: AggregateRepository = Provide['nn.aggregate_repository'], parallel_context_factory: Callable[[], ParallelContext] = Provide['parallel_singleton.thread_pool_context.provider'])[source]¶

Bases: object

Utility operations API for Session.

merge_other_session(other_session_or_context: Session | SessionContext, fields: list[str] | None = None, *, verify: bool = True, read_budget_bytes: int = 512 * 1024 * 1024) → None[source]¶

Merge parameters from another session into this one.

Copies parameters and their computed fields from another session. When verify is True, handles conflicts by skipping duplicate fields.

Parameters:

other_session_or_context – Source session to merge from.
fields – Specific fields to merge. If None, merges all fields.
verify – If True, check for conflicts and skip duplicates.
read_budget_bytes – Maximum bytes to read during merge operation.