API

scitex-bridge — cross-module adapters (stats↔plt / stats↔vis / plt↔vis) — standalone.

SciTeX Bridge Module - Cross-module adapters and transformations.

This module provides the official API for connecting SciTeX modules: - stats ↔ plt: Statistical results to plot annotations - stats ↔ vis: Statistical results to vis annotations - plt ↔ vis: Matplotlib figures to vis FigureModel

Design Principles: - Bridge functions use only public APIs of each module - All transformations go through schema validation - Single source of truth for cross-module conventions - Protocol versioning for forward/backward compatibility

Protocol Version: 1.0.0

Coordinate Conventions: - plt bridge: Uses axes coordinates (0-1 normalized) - vis bridge: Uses data coordinates (actual x/y values) - See COORDINATE_SYSTEMS for full definitions

Usage:

from scitex_bridge import (

# Protocol version BRIDGE_PROTOCOL_VERSION, check_protocol_compatibility,

# Stats to Plt add_stat_to_axes, extract_stats_from_axes,

# Stats to Vis stat_result_to_annotation, add_stats_to_figure_model,

# Plt to Vis figure_to_vis_model, axes_to_vis_axes, tracking_to_plot_configs,

)

class scitex_bridge.ProtocolInfo(version='1.0.0', source_module='', target_module='', coordinate_system='data')

Bridge protocol information for serialization and compatibility.

Parameters:

• version (str) – Protocol version string (semver)

• source_module (str) – Module that created the data

• target_module (str) – Target module for the data

• coordinate_system (str) – Coordinate system used (“axes”, “data”, “figure”, “mm”, “px”)

version: str = '1.0.0'

source_module: str = ''

target_module: str = ''

coordinate_system: str = 'data'

to_dict()

Convert to dictionary.

Return type:

Dict[str, Any]

classmethod from_dict(data)

Create from dictionary.

Return type:

ProtocolInfo

scitex_bridge.check_protocol_compatibility(data_version, current_version='1.0.0')

Check if a data version is compatible with the current protocol.

Parameters:

• data_version (str) – Version of the data being loaded

• current_version (str) – Current protocol version (default: BRIDGE_PROTOCOL_VERSION)

Returns:

(is_compatible, warning_message) - is_compatible: True if data can be safely used - warning_message: None if compatible, else a warning string

Return type:

tuple

Examples

>>> is_compat, msg = check_protocol_compatibility("1.0.0")
>>> is_compat
True

>>> is_compat, msg = check_protocol_compatibility("2.0.0")
>>> is_compat
False
>>> msg
'Major version mismatch: data v2.0.0, current v1.0.0'

scitex_bridge.add_protocol_metadata(data, source_module, target_module, coordinate_system='data')

Add bridge protocol metadata to a dictionary.

Parameters:

• data (dict) – Data dictionary to annotate

• source_module (str) – Source module name (e.g., “stats”, “plt”)

• target_module (str) – Target module name (e.g., “vis”, “plt”)

• coordinate_system (str) – Coordinate system used (default: “data”)

Returns:

Data with protocol metadata added

Return type:

dict

Examples

>>> data = {"x": 10, "y": 20}
>>> annotated = add_protocol_metadata(data, "stats", "vis")
>>> annotated["_bridge_protocol"]["bridge_protocol_version"]
'1.0.0'

scitex_bridge.extract_protocol_metadata(data)

Extract bridge protocol metadata from a dictionary.

Parameters:

data (dict) – Data dictionary that may contain protocol metadata

Returns:

Protocol info if present, None otherwise

Return type:

ProtocolInfo or None

scitex_bridge.add_stat_to_axes(ax, stat_result, x=None, y=None, format_style='asterisk', **kwargs)

Add a statistical result annotation to a matplotlib axes.

Parameters:

• ax (matplotlib.axes.Axes or scitex.plt AxisWrapper) – The axes to annotate

• stat_result (StatResult) – The statistical result to display

• x (float, optional) – X position for the annotation. If None, uses stat_result.positioning

• y (float, optional) – Y position for the annotation. If None, uses stat_result.positioning

• format_style (str) – Format style for the text (“asterisk”, “compact”, “detailed”, “publication”)

• **kwargs – Additional kwargs passed to ax.annotate() or ax.text()

Returns:

The created annotation object

Return type:

matplotlib.text.Text or matplotlib.text.Annotation

scitex_bridge.extract_stats_from_axes(ax, include_non_stat=False)

Extract StatResult objects from axes annotations.

Parameters:

• ax (matplotlib.axes.Axes or scitex.plt AxisWrapper) – The axes to extract stats from

• include_non_stat (bool) – If True, create basic StatResult for non-stat annotations

Returns:

List of StatResult objects found in annotations

Return type:

List[StatResult]

scitex_bridge.format_stat_for_plot(stat_result, format_style='asterisk')

Format a StatResult for display on a plot.

Parameters:

• stat_result (StatResult) – The statistical result to format

• format_style (str) – One of “asterisk”, “compact”, “detailed”, “publication”

Returns:

Formatted string for plot annotation

Return type:

str

scitex_bridge.stat_result_to_annotation(stat_result, format_style='asterisk', x=None, y=None)

Convert a StatResult to a vis AnnotationModel.

Parameters:

• stat_result (StatResult) – The statistical result to convert

• format_style (str) – Format style for the text (“asterisk”, “compact”, “detailed”, “publication”)

• x (float, optional) – X position (data coordinates). Overrides stat_result positioning

• y (float, optional) – Y position (data coordinates). Overrides stat_result positioning

Returns:

Annotation model for vis rendering

Return type:

AnnotationModel

scitex_bridge.add_stats_to_figure_model(figure_model, stat_results, axes_index=0, format_style='asterisk', auto_position=True)

Add statistical results as annotations to a FigureModel.

Parameters:

• figure_model (FigureModel) – The figure model to annotate

• stat_results (List[StatResult]) – List of statistical results to add

• axes_index (int) – Index of axes to add annotations to

• format_style (str) – Format style for the text

• auto_position (bool) – Whether to automatically position stats to avoid overlap

Returns:

The modified figure model (same instance)

Return type:

FigureModel

scitex_bridge.position_stat_annotation(stat_result, axes_bounds, existing_positions=None, preferred_corner='top-right')

Calculate optimal position for a stat annotation.

Parameters:

• stat_result (StatResult) – The statistical result to position

• axes_bounds (Dict[str, float]) – Axes bounds with keys: x_min, x_max, y_min, y_max

• existing_positions (List[Tuple[float, float]], optional) – List of existing annotation positions to avoid

• preferred_corner (str) – Preferred corner: “top-left”, “top-right”, “bottom-left”, “bottom-right”

Returns:

Calculated position in data coordinates

Return type:

Position

scitex_bridge.figure_to_vis_model(fig, include_data=True, include_style=True)

Convert a scitex.plt figure to a vis FigureModel.

Parameters:

• fig (scitex.plt.FigWrapper or matplotlib.figure.Figure) – The figure to convert

• include_data (bool) – Whether to include plot data in the model

• include_style (bool) – Whether to include style information

Returns:

The vis figure model

Return type:

FigureModel

scitex_bridge.axes_to_vis_axes(ax, row=0, col=0, scitex_ax=None, include_data=True, include_style=True)

Convert a matplotlib axes to a vis AxesModel.

Parameters:

• ax (matplotlib.axes.Axes) – The axes to convert

• row (int) – Row position in layout

• col (int) – Column position in layout

• scitex_ax (AxisWrapper, optional) – Scitex axis wrapper with tracking history

• include_data (bool) – Whether to include plot data

• include_style (bool) – Whether to include style information

Returns:

The vis axes model

Return type:

AxesModel

scitex_bridge.tracking_to_plot_configs(history)

Convert scitex.plt tracking history to PlotModel configurations.

Parameters:

history (Dict[str, Tuple]) – Tracking history from AxisWrapper Format: {id: (id, method_name, tracked_dict, kwargs)}

Returns:

List of PlotModel configurations

Return type:

List[PlotModel]

scitex_bridge.collect_figure_data(fig)

Collect all data from a figure for export.

This is a simpler version that just extracts data without full vis model conversion.

Parameters:

fig (scitex.plt.FigWrapper or matplotlib.figure.Figure) – The figure to collect data from

Returns:

Dictionary with figure data organized by axes/plot

Return type:

Dict[str, Any]

scitex_bridge.add_stats_from_results(target, stat_results, backend='auto', format_style='asterisk', **kwargs)

Add statistical results to a figure or axes, auto-detecting backend.

This is a high-level helper that works with both matplotlib axes and vis FigureModel, choosing the appropriate bridge function.

Parameters:

• target (matplotlib.axes.Axes, scitex.plt.AxisWrapper, or FigureModel) – The target to add statistics to

• stat_results (StatResult or List[StatResult]) – Statistical result(s) to add

• backend ({"auto", "plt", "vis"}) – Backend to use. “auto” detects from target type: - matplotlib axes or scitex AxisWrapper → “plt” - FigureModel → “vis”

• format_style (str) – Format style for stat text (“asterisk”, “compact”, “detailed”, “publication”)

• **kwargs – Additional arguments passed to the backend-specific function: - plt: passed to add_stat_to_axes (x, y, transform, etc.) - vis: passed to add_stats_to_figure_model (axes_index, auto_position, etc.)

Returns:

The modified target (for chaining)

Return type:

target

Examples

>>> # With matplotlib axes
>>> fig, ax = plt.subplots()
>>> stat = create_stat_result("pearson", "r", 0.85, 0.001)
>>> add_stats_from_results(ax, stat)

>>> # With vis FigureModel
>>> model = FigureModel(width_mm=170, height_mm=120, axes=[{}])
>>> add_stats_from_results(model, [stat1, stat2], backend="vis")

Notes

Coordinate conventions differ between backends: - plt: uses axes coordinates (0-1 normalized) by default - vis: uses data coordinates

For precise control, use the backend-specific functions directly: - scitex.bridge.add_stat_to_axes (plt backend) - scitex.bridge.add_stats_to_figure_model (vis backend)

scitex_bridge.save_with_recipe(fig, path, include_csv=True, include_recipe=True, data_format='csv', dpi=300, *, storage_resolver=<function _default_get_storage>, **kwargs)

Save figure with both CSV and figrecipe recipe.

Parameters:

• fig (FigWrapper or matplotlib Figure) – The figure to save.

• path (str or Path) – Output path. Can be: - Directory path (creates bundle) - File path with .zip extension (creates zip bundle) - File path with image extension (saves image + sidecar files)

• include_csv (bool) – If True, save SigmaPlot-compatible CSV.

• include_recipe (bool) – If True, save figrecipe YAML recipe (requires figrecipe).

• data_format (str) – Format for recipe data: ‘csv’, ‘npz’, or ‘inline’.

• dpi (int) – Resolution for image output.

• storage_resolver (callable) – Zero-arg resolver returning the bundle-storage factory, or None when scitex.io.bundle is absent. Defaults to _default_get_storage(); when it returns None the function degrades to {}.

• **kwargs – Additional arguments passed to savefig (including facecolor).

Returns:

Paths to saved files: {‘image’: Path, ‘csv’: Path, ‘recipe’: Path}

Return type:

dict

scitex_bridge.load_recipe(path, *, figrecipe_available=None)

Load figrecipe recipe from FTS bundle.

Parameters:

• path (str or Path) – Path to bundle directory, zip file, or recipe.yaml.

• figrecipe_available (bool or None) – Whether figrecipe is importable. Defaults to the module-level FIGRECIPE_AVAILABLE flag; callers (and tests) may pass False to exercise the missing-dependency branch explicitly.

Returns:

(fig, axes) reproduced from recipe.

Return type:

tuple

scitex_bridge.has_figrecipe()

Check if figrecipe is available.

Return type:

bool