I/O Module (rheojax.io) ¶

Returns:

Single RheoData for single-segment files List of RheoData when return_all_segments=True or multiple segments

Raises:

FileNotFoundError – File does not exist
ValueError – Unsupported format or no data found
UnicodeDecodeError – Encoding detection failed

Example

>>> data = load_trios("frequency_sweep.csv")
>>> print(data.test_mode)  # 'oscillation'
>>> print(data.is_complex)  # True (G* = G' + iG'')

>>> data = load_trios("creep_recovery.xlsx", sheet_name="all")
>>> print(len(data))  # Multiple sheets

rheojax.io.readers.load_trios_chunked(filepath, chunk_size=10000, progress_callback=None, **kwargs)[source]¶

Load TRIOS file in memory-efficient chunks (generator).

This function reads TRIOS files using a streaming approach that yields RheoData objects for each chunk of data. This is ideal for large files (> 10 MB, > 50,000 points) where loading the entire file would consume excessive memory.

Memory Efficiency: - Traditional loading: Entire file in memory (~80 bytes per point) - Chunked loading: Only chunk_size points in memory at once - Example: 150k point file with chunk_size=10k uses ~800 KB vs ~12 MB

Important Notes: - Chunks are yielded sequentially as they are read - Each chunk is an independent RheoData object with complete metadata - Chunk boundaries are based on data rows, not time or other physical units - File handle is automatically closed when generator completes or is interrupted

Progress Tracking (v0.4.0+): - Optional progress_callback parameter for monitoring large file loading - Callback signature: callback(current_points, total_points) - Called every 5-10% of file processed for efficient monitoring - Total points estimated from “Number of points” in TRIOS header

Parameters:

filepath (str | Path) – Path to TRIOS .txt file
chunk_size (int) – Number of data points per chunk (default: 10,000) - Smaller = less memory, more overhead - Larger = more memory, less overhead - Recommended: 5,000 - 20,000 for most files
progress_callback (Callable | None) – Optional callback function for progress tracking. Signature: callback(current_points: int, total_points: int) Called periodically during loading (every 5-10% progress).
**kwargs – Additional options - segment_index: If provided, only process this segment (0-based) - validate_data: Validate each chunk (default: True)

Yields:

RheoData – Chunks of data with metadata preserved

Raises:

FileNotFoundError – If file doesn’t exist
ValueError – If file format is not recognized or no segments found

Example

>>> # Process large file in chunks
>>> for chunk in load_trios_chunked('large_file.txt', chunk_size=10000):
...     print(f"Processing {len(chunk.x)} points")
...     model.fit(chunk.x, chunk.y)
>>>
>>> # Aggregate results from chunks
>>> max_stress = -float('inf')
>>> for chunk in load_trios_chunked('file.txt'):
...     max_stress = max(max_stress, chunk.y.max())
>>> print(f"Maximum stress: {max_stress}")
>>>
>>> # With progress tracking
>>> def progress(current, total):
...     pct = 100 * current / total
...     print(f"Loading: {pct:.1f}%")
>>> for chunk in load_trios_chunked('large_file.txt', progress_callback=progress):
...     process(chunk)

See also

load_trios: Standard loading (entire file in memory), auto-chunks for files > 5 MB

rheojax.io.readers.load_trios_csv(filepath, *, return_all_segments=False, test_mode=None, encoding=None, decimal_separator='.', delimiter=None, validate=True, progress_callback=None)[source]¶

Load TRIOS CSV export file.

Handles TRIOS-specific CSV format with: - Metadata header rows before data - Tab or comma delimiters (auto-detected) - Units in parentheses or separate row - Step/Segment columns for multi-step experiments - Repeated headers for multi-table files

Parameters:

filepath (str | Path) – Path to TRIOS CSV file
return_all_segments (bool) – Return list for multi-step files
test_mode (str | None) – Override auto-detection (“creep”, “relaxation”, “oscillation”, “rotation”)
encoding (str | None) – File encoding (auto-detected: UTF-8, Latin-1, CP1252)
decimal_separator (str) – “.” for US, “,” for European
delimiter (str | None) – Override delimiter detection (None = auto)
validate (bool) – Validate RheoData on creation
progress_callback (Callable[[int, int], None] | None) – Progress callback(current, total)

Return type:

Returns:

Single RheoData or list of RheoData

Raises:

FileNotFoundError – File does not exist
ValueError – No data found or invalid format

Example

>>> data = load_trios_csv('frequency_sweep.csv')
>>> print(data.test_mode)  # 'oscillation'
>>> print(np.iscomplexobj(data.y))  # True for G* = G' + iG''

rheojax.io.readers.load_trios_excel(filepath, *, sheet_name=None, return_all_segments=False, test_mode=None, validate=True)[source]¶

Load TRIOS Excel export file (.xlsx, .xls).

Handles TRIOS-specific Excel format with: - Metadata in early rows - Data table with headers - Multi-sheet support (one sheet per temperature)

Parameters:

filepath (str | Path) – Path to TRIOS Excel file
sheet_name (str | int | None) – Sheet to load (None=first, “all”=all sheets, int=index, str=name)
return_all_segments (bool) – Return list for multi-step files
test_mode (str | None) – Override auto-detection (“creep”, “relaxation”, “oscillation”, “rotation”)
validate (bool) – Validate RheoData on creation

Return type:

Returns:

Single RheoData for single-sheet files List of RheoData when sheet_name=”all” or multiple sheets/segments

Raises:

FileNotFoundError – File does not exist
ValueError – Sheet not found or no data

Example

>>> data = load_trios_excel('creep_recovery.xlsx')
>>> print(data.test_mode)  # 'creep'

>>> all_sheets = load_trios_excel('multi_temp.xlsx', sheet_name='all')
>>> for d in all_sheets:
...     print(d.metadata.get('temperature'))

rheojax.io.readers.load_trios_json(filepath, *, return_all_segments=False, test_mode=None, result_index=0, validate_json_schema=True, validate=True)[source]¶

Load TRIOS JSON export file.

Uses adapted tadatakit code to parse TRIOS JSON format with schema validation against official TRIOS JSON Export Schema.

Parameters:

filepath (str | Path) – Path to TRIOS JSON file
return_all_segments (bool) – Return list for multi-step files
test_mode (str | None) – Override auto-detection (“creep”, “relaxation”, “oscillation”, “rotation”)
result_index (int) – Result set index to load (default: 0, or -1 for all)
validate_json_schema (bool) – Validate against TRIOS schema (default: True)
validate (bool) – Validate RheoData on creation

Return type:

Returns:

Single RheoData or list of RheoData

Raises:

FileNotFoundError – File does not exist
ValueError – Invalid JSON structure or schema mismatch
json.JSONDecodeError – Invalid JSON syntax

Notes

Schema version mismatch logs warning but attempts parsing.

Example

>>> data = load_trios_json('relaxation.json')
>>> print(data.test_mode)  # 'relaxation'
>>> print(data.x_units)  # 's' (time)
>>> print(data.y_units)  # 'Pa' (relaxation modulus)

rheojax.io.readers.parse_trios_csv(filepath, *, encoding=None, decimal_separator='.', delimiter=None)[source]¶

Low-level CSV parser returning raw TRIOSFile structure.

For advanced users who need access to raw tables and metadata before RheoData conversion.

Parameters:

filepath (str | Path) – Path to TRIOS CSV file
encoding (str | None) – File encoding (auto-detected if None)
decimal_separator (str) – Decimal separator (“.” or “,”)
delimiter (str | None) – Delimiter override (None = auto)

Return type:

TRIOSFile

Returns:

TRIOSFile with parsed tables and metadata

Raises:

FileNotFoundError – File does not exist
ValueError – No data tables found

rheojax.io.readers.load_csv(filepath, x_col, y_col=None, *, y_cols=None, x_units=None, y_units=None, domain=None, test_mode=None, deformation_mode=None, temperature=None, metadata=None, intended_transform=None, delimiter=None, encoding=None, column_mapping=None, strain_amplitude=None, angular_frequency=None, applied_stress=None, shear_rate=None, reference_gamma_dot=None, header=0, **kwargs)[source]¶

Load data from CSV or ASCII text file into RheoData.

Parameters:

filepath (str | Path) – Path to CSV or text file.
x_col (str | int) – Column name or index for x-axis data.
y_col (str | int | None) – Column name or index for y-axis data (single column). Mutually exclusive with y_cols.
y_cols (list[str | int] | None) – List of two column names/indices for complex modulus [G’, G’’] or [E’, E’’]. First column is storage modulus, second is loss modulus. Mutually exclusive with y_col.
x_units (str | None) – Units for x-axis (auto-detected from header if None).
y_units (str | None) – Units for y-axis (auto-detected from header if None).
domain (str | None) – Data domain (‘time’ or ‘frequency’, auto-detected if None).
test_mode (str | None) – Test mode (‘relaxation’, ‘creep’, ‘oscillation’, ‘rotation’). Auto-detected if None.
deformation_mode (str | None) – Deformation mode (‘shear’, ‘tension’, ‘bending’, ‘compression’). Auto-detected from column names if None. If ‘tension’/’bending’/’compression’, sets metadata for DMTA support.
temperature (float | None) – Temperature in Kelvin for TTS workflows.
metadata (dict | None) – Additional metadata dict to merge.
intended_transform (str | None) – Transform type for metadata validation. One of ‘mastercurve’, ‘srfs’, ‘owchirp’, ‘spp’, ‘fft’, ‘mutation’, ‘derivative’.
delimiter (str | None) – Column delimiter (auto-detected if None).
encoding (str | None) – File encoding (e.g. ‘utf-8’, ‘latin-1’, ‘cp1252’). Auto-detected if None. Use this to override detection for files with known encoding.
column_mapping (dict[str, str] | None) – Optional dict mapping original column names to new names. Applied immediately after reading, before any column lookup. Example: {“t”: “time”, “sigma”: “stress”}.
strain_amplitude (float | None) – Strain amplitude (gamma_0) stored in metadata as gamma_0. Used for LAOS/oscillation protocols.
angular_frequency (float | None) – Angular frequency (omega) stored in metadata as omega. Used for oscillation protocols.
applied_stress (float | None) – Applied stress stored in metadata as sigma_applied. Used for creep protocols.
shear_rate (float | None) – Shear rate stored in metadata as gamma_dot. Used for flow/startup protocols.
reference_gamma_dot (float | None) – Reference shear rate stored in metadata as reference_gamma_dot. Used for dimensionless flow analysis.
header (int | None) – Row number for column headers (None if no header).
**kwargs – Additional arguments passed to pandas.read_csv.

Return type:

Returns:

RheoData object with populated fields.

Raises:

FileNotFoundError – If file doesn’t exist.
KeyError – If specified columns don’t exist.
ValueError – If data cannot be parsed, y_cols has wrong length, or both y_col and y_cols are provided.

Warning

UserWarning: If intended_transform metadata is missing. UserWarning: If domain incompatible with intended_transform. UserWarning: If test_mode conflicts with intended_transform.

Example

>>> # Simple relaxation data
>>> data = load_csv("relaxation.csv", x_col="time (s)", y_col="G(t) (Pa)")
>>> # Complex modulus oscillation data
>>> data = load_csv(
...     "frequency_sweep.csv",
...     x_col="omega (rad/s)",
...     y_cols=["G' (Pa)", "G'' (Pa)"],
...     intended_transform='mastercurve',
...     temperature=298.15,
... )

rheojax.io.readers.load_excel(filepath, x_col, y_col=None, *, y_cols=None, sheet=0, x_units=None, y_units=None, domain=None, test_mode=None, deformation_mode=None, temperature=None, metadata=None, intended_transform=None, column_mapping=None, strain_amplitude=None, angular_frequency=None, applied_stress=None, shear_rate=None, reference_gamma_dot=None, header=0, **kwargs)[source]¶

Load data from Excel file into RheoData.

Parameters:

filepath (str | Path) – Path to Excel file (.xlsx or .xls).
x_col (str | int) – Column name or index for x-axis data.
y_col (str | int | None) – Column name or index for y-axis data (single column). Mutually exclusive with y_cols.
y_cols (list[str | int] | None) – List of two column names/indices for complex modulus [G’, G’’]. First column is storage modulus (G’), second is loss modulus (G’’). Mutually exclusive with y_col.
sheet (str | int) – Sheet name or index (default: 0 - first sheet).
x_units (str | None) – Units for x-axis (auto-detected from header if None).
y_units (str | None) – Units for y-axis (auto-detected from header if None).
domain (str | None) – Data domain (‘time’ or ‘frequency’, auto-detected if None).
test_mode (str | None) – Test mode (‘relaxation’, ‘creep’, ‘oscillation’, ‘rotation’). Auto-detected if None.
deformation_mode (str | None) – Deformation mode (‘shear’, ‘tension’, ‘bending’, ‘compression’). Auto-detected from column names if None. If ‘tension’/’bending’/’compression’, sets metadata for DMTA support.
temperature (float | None) – Temperature in Kelvin for TTS workflows.
metadata (dict | None) – Additional metadata dict to merge.
intended_transform (str | None) – Transform type for metadata validation. One of ‘mastercurve’, ‘srfs’, ‘owchirp’, ‘spp’, ‘fft’, ‘mutation’, ‘derivative’.
column_mapping (dict[str, str] | None) – Optional dict mapping original column names to new names. Applied immediately after reading, before any column lookup. Example: {“t”: “time”, “sigma”: “stress”}.
strain_amplitude (float | None) – Strain amplitude (gamma_0) stored in metadata as gamma_0. Used for LAOS/oscillation protocols.
angular_frequency (float | None) – Angular frequency (omega) stored in metadata as omega. Used for oscillation protocols.
applied_stress (float | None) – Applied stress stored in metadata as sigma_applied. Used for creep protocols.
shear_rate (float | None) – Shear rate stored in metadata as gamma_dot. Used for flow/startup protocols.
reference_gamma_dot (float | None) – Reference shear rate stored in metadata as reference_gamma_dot. Used for dimensionless flow analysis.
header (int | None) – Row number for column headers (None if no header).
**kwargs – Additional arguments passed to pandas.read_excel.

Return type:

Returns:

RheoData object with populated fields.

Raises:

FileNotFoundError – If file doesn’t exist.
ImportError – If pandas or openpyxl not installed.
KeyError – If specified columns or sheet don’t exist.
ValueError – If data cannot be parsed, y_cols has wrong length, or both y_col and y_cols are provided.

Warning

UserWarning: If intended_transform metadata is missing. UserWarning: If domain incompatible with intended_transform. UserWarning: If test_mode conflicts with intended_transform.

Example

>>> # Simple creep data from specific sheet
>>> data = load_excel(
...     "data.xlsx",
...     x_col="time (s)",
...     y_col="J(t) (1/Pa)",
...     sheet="Creep Test",
... )
>>> # Flow curve with explicit test mode
>>> data = load_excel(
...     "flow_curve.xlsx",
...     x_col=0,
...     y_col=1,
...     test_mode='rotation',
...     x_units='1/s',
...     y_units='Pa·s',
... )
>>> # Complex modulus from Excel
>>> data = load_excel(
...     "frequency_sweep.xlsx",
...     x_col="omega (rad/s)",
...     y_cols=["G' (Pa)", "G'' (Pa)"],
...     intended_transform='mastercurve',
...     temperature=298.15,
... )

rheojax.io.readers.load_anton_paar(filepath, *, test_mode=None, interval=None, return_all=False, encoding=None, x_col=None, y_col=None, progress_callback=None)[source]¶

Load RheoCompass CSV export file and return RheoData object(s).

Handles interval-based file structure, auto-detects test type, extracts metadata, and normalizes units to SI.

Parameters:

filepath (str | Path) – Path to RheoCompass CSV export file
test_mode (str | None) – Explicit test mode override (“creep”, “relaxation”, “oscillation”, “rotation”). If None, auto-detected from columns.
interval (int | None) – Specific interval index to load (1-based). If None with return_all=False, returns first interval.
return_all (bool) – If True, always return list of RheoData.
encoding (str | None) – File encoding override (auto-detected if None).
x_col (str | None) – Override for x-axis column selection.
y_col (str | None) – Override for y-axis column selection.
progress_callback (Callable[[int, int], None] | None) – Callback receiving (current, total) for progress.

Return type:

Returns:

Single RheoData for single-interval files (unless return_all=True). List of RheoData for multi-interval files or when return_all=True.

Raises:

FileNotFoundError – File does not exist
ValueError – No interval blocks, cannot detect test type, or interval index out of range

rheojax.io.readers.parse_rheocompass_intervals(filepath, *, encoding=None, marker='Interval and data points:')[source]¶

Parse RheoCompass file returning raw interval blocks.

Low-level parser for advanced users who need full access to all columns and metadata without RheoData mapping.

Parameters:

filepath (str | Path) – Path to RheoCompass CSV export file
encoding (str | None) – File encoding override (auto-detected if None)
marker (str) – Interval start marker string

Return type:

tuple[dict[str, Any], list[IntervalBlock]]

Returns:

Tuple of (global_metadata, interval_blocks)

Raises:

FileNotFoundError – File does not exist
ValueError – No interval blocks found
UnicodeDecodeError – Encoding detection failed

rheojax.io.readers.save_intervals_to_excel(rheo_data_list, filepath, *, include_metadata_sheet=True, sheet_prefix='Interval')[source]¶

Export multi-interval RheoData to Excel with one sheet per interval.

Creates an Excel workbook where each interval becomes its own sheet (Interval_1, Interval_2, …) plus an optional Metadata sheet containing global metadata and per-interval summary.

Parameters:

rheo_data_list (list[RheoData] | RheoData) – Single RheoData or list of RheoData objects (typically from load_anton_paar with return_all=True)
filepath (str | Path) – Output Excel file path (.xlsx)
include_metadata_sheet (bool) – Add a Metadata sheet with global info (default True)
sheet_prefix (str) – Prefix for interval sheet names (default “Interval”)

Raises:

ImportError – If pandas or openpyxl not installed
ValueError – If rheo_data_list is empty

Return type:

Example

>>> data_list = load_anton_paar("temp_sweep.csv", return_all=True)
>>> save_intervals_to_excel(data_list, "output.xlsx")
# Creates: Metadata, Interval_1, Interval_2, Interval_3 sheets

rheojax.io.readers.auto_load(filepath, *, format=None, **kwargs)[source]¶

Automatically detect file format and load data.

This function attempts to determine the file format based on: 1. The format argument (if provided — skips auto-detection cascade) 2. File extension 3. File content inspection 4. Sequential reader attempts

Parameters:

filepath (str | Path) – Path to data file
format (str | None) – Optional format hint. Valid values: 'trios', 'anton_paar', 'csv', 'excel'. When supplied the auto-detection cascade is skipped and the chosen reader is called directly. Case-insensitive.
**kwargs – Additional arguments passed to specific readers - x_col, y_col: Required for CSV/Excel if auto-detection fails - return_all_segments: For TRIOS files with multiple segments - column_mapping: dict mapping canonical names to column names - strain_amplitude, angular_frequency: oscillation metadata - applied_stress, shear_rate, reference_gamma_dot: flow metadata

Return type:

Returns:

RheoData object or list of RheoData objects

Raises:

FileNotFoundError – If file doesn’t exist
ValueError – If no reader can parse the file or format is unknown

class rheojax.io.readers.CanonicalField(canonical_name, patterns, si_unit, applicable_modes, is_x_candidate=False, is_y_candidate=False, priority=100)[source]¶

Bases: object

Canonical field descriptor for a rheological measurement column.

canonical_name: str¶

patterns: list[str]¶

si_unit: str¶

applicable_modes: list[str]¶

is_x_candidate: bool = False¶

is_y_candidate: bool = False¶

priority: int = 100¶

__init__(canonical_name, patterns, si_unit, applicable_modes, is_x_candidate=False, is_y_candidate=False, priority=100)¶

rheojax.io.readers.match_column(header, instrument=None)[source]¶

Match a column header string to a CanonicalField.

Uses extract_unit_from_header() to strip parenthesized unit suffixes (e.g. "omega (rad/s)" → "omega"), ensuring consistent unit extraction across the I/O subsystem.

Parameters:

header (str) – Raw column header string (may include a parenthesized unit suffix).
instrument (str | None) – Optional instrument name for future instrument-specific filtering. Currently unused; reserved for Phase 2 extension.

Returns:

The first matching canonical field (ordered by priority), or None if no field matches.

Return type:

CanonicalField | None

rheojax.io.readers.match_columns(headers, instrument=None)[source]¶

Match a list of column headers to canonical fields.

Parameters:

headers (list[str]) – List of raw column header strings.
instrument (str | None) – Optional instrument name passed through to match_column().

Return type:

dict[str, CanonicalField]

rheojax.io.readers.validate_protocol(data, intended_transform=None)[source]¶

Run protocol-aware quality checks on loaded rheological data.

Infers the test protocol from data.initial_test_mode or data.metadata["detected_test_mode"] and performs protocol-specific quality checks. A RheoJaxValidationWarning is emitted for every issue found so that callers using warnings.filterwarnings can control visibility.

Parameters:

data (RheoData) – Loaded rheological data container.
intended_transform (str | None) – Optional transform name (e.g. "mastercurve", "owchirp") to validate transform compatibility in addition to protocol checks.

Return type:

LoaderReport

Returns:

LoaderReport with all findings.

rheojax.io.readers.load_tts(files, T_ref, *, temperatures=None, temperature_unit='K', format=None, **kwargs)[source]¶

Load multiple files for a Time-Temperature Superposition (TTS) workflow.

Each file corresponds to a single temperature. Files are loaded with auto_load() and tagged with temperature metadata, then sorted by temperature (ascending).

Parameters:

files (list[str | Path] | str) – List of file paths or a glob pattern string (e.g. "data/T*.csv").
T_ref (float) – Reference temperature in Kelvin stored in metadata of every returned RheoData.
temperatures (list[float] | None) – Explicit temperature values (same length as files). Converted to Kelvin using temperature_unit. If None, the function tries to read metadata["temperature"] from each loaded file.
temperature_unit (str) – Unit of temperatures — "K" (default), "C", or "F". Ignored when temperatures is None.
format (str | None) – Optional format hint forwarded to auto_load() ('trios', 'anton_paar', 'csv', 'excel').
**kwargs (Any) – Additional keyword arguments forwarded to auto_load().

Return type:

list[RheoData]

Returns:

List of RheoData objects sorted by temperature (ascending).

Raises:

FileNotFoundError – If a glob pattern matches no files.
ValueError – If temperatures length does not match the number of files, or if temperatures cannot be extracted from metadata.

rheojax.io.readers.load_srfs(files, reference_gamma_dots, *, format=None, **kwargs)[source]¶

Load multiple files for a Superposition of Rate-Frequency Sweeps (SRFS) workflow.

Each file corresponds to a different reference shear rate. Files are loaded with auto_load(), tagged with metadata["reference_gamma_dot"], and sorted by reference shear rate (ascending).

Parameters:

files (list[str | Path] | str) – List of file paths or a glob pattern string.
reference_gamma_dots (list[float]) – Reference shear rates (1/s) — one per file.
format (str | None) – Optional format hint forwarded to auto_load().
**kwargs (Any) – Additional keyword arguments forwarded to auto_load().

Return type:

list[RheoData]

Returns:

List of RheoData objects sorted by reference_gamma_dot (ascending).

Raises:

FileNotFoundError – If a glob pattern matches no files.
ValueError – If reference_gamma_dots length does not match the number of files.

rheojax.io.readers.load_series(files, protocol, *, sort_by=None, metadata_key=None, metadata_values=None, format=None, **kwargs)[source]¶

Load a series of files sharing the same rheological protocol.

A generic multi-file loader that tags each loaded dataset with a protocol label and optional metadata, then optionally sorts the resulting list by a metadata key.

Parameters:

files (list[str | Path] | str) – List of file paths or a glob pattern string.
protocol (str) – Protocol label stored as metadata["protocol"] on every returned dataset (e.g. "oscillation", "relaxation").
sort_by (str | None) – If provided, sort the output list by metadata[sort_by] (ascending). Missing keys are sorted to the end.
metadata_key (str | None) – Optional metadata key to tag each dataset with a per-file value from metadata_values.
metadata_values (list[Any] | None) – List of values (one per file) written to metadata[metadata_key]. Required when metadata_key is given.
format (str | None) – Optional format hint forwarded to auto_load().
**kwargs (Any) – Additional keyword arguments forwarded to auto_load().

Return type:

list[RheoData]

Returns:

List of RheoData objects, optionally sorted.

Raises:

FileNotFoundError – If a glob pattern matches no files.
ValueError – If metadata_values length does not match the number of files when metadata_key is provided.

Auto-Detection¶

rheojax.io.readers.auto_load(filepath, *, format=None, **kwargs)[source]

Automatically detect file format and load data.

Parameters:

filepath (str | Path) – Path to data file
format (str | None) – Optional format hint. Valid values: 'trios', 'anton_paar', 'csv', 'excel'. When supplied the auto-detection cascade is skipped and the chosen reader is called directly. Case-insensitive.
**kwargs – Additional arguments passed to specific readers - x_col, y_col: Required for CSV/Excel if auto-detection fails - return_all_segments: For TRIOS files with multiple segments - column_mapping: dict mapping canonical names to column names - strain_amplitude, angular_frequency: oscillation metadata - applied_stress, shear_rate, reference_gamma_dot: flow metadata

Return type:

Returns:

RheoData object or list of RheoData objects

Raises:

FileNotFoundError – If file doesn’t exist
ValueError – If no reader can parse the file or format is unknown

Automatically detect and read file format based on extension and content.

Supported formats:

TA Instruments TRIOS (.txt)
Generic CSV (.csv)
Microsoft Excel (.xlsx, .xls)
Anton Paar (.txt, .xls)

TRIOS Reader¶

TA Instruments TRIOS multi-format file readers.

This package provides readers for TRIOS rheometer data in multiple formats: - TXT: Plain text export (LIMS format) - CSV: Comma/tab-separated values export - Excel: .xlsx/.xls export - JSON: JSON export (schema-validated)

Usage:

>>> from rheojax.io.readers import load_trios
>>> data = load_trios('frequency_sweep.csv')  # Auto-detects format

>>> from rheojax.io.readers.trios import load_trios_csv
>>> data = load_trios_csv('frequency_sweep.csv')  # Explicit format

All loaders return RheoData objects compatible with RheoJAX analysis pipelines.

rheojax.io.readers.trios.load_trios(filepath, *, return_all_segments=False, test_mode=None, encoding=None, decimal_separator='.', validate=True, auto_chunk=True, progress_callback=None, **kwargs)[source]¶

Load TRIOS file with automatic format detection.

Parameters:

filepath (str | Path) – Path to TRIOS file
return_all_segments (bool) – Return list for multi-step files (default: False)
test_mode (str | None) – Override auto-detection (“creep”, “relaxation”, “oscillation”, “rotation”)
encoding (str | None) – File encoding override (auto-detected if None)
decimal_separator (str) – “.” for US (default), “,” for European
validate (bool) – Validate RheoData on creation (default: True)
auto_chunk (bool) – Auto-chunk large files > 5MB (default: True, TXT only)
progress_callback (Callable[[int, int], None] | None) – Progress callback(current, total) for large files
**kwargs (Any) – Format-specific options passed to underlying parser

Return type:

Returns:

Single RheoData for single-segment files List of RheoData when return_all_segments=True or multiple segments

Raises:

FileNotFoundError – File does not exist
ValueError – Unsupported format or no data found
UnicodeDecodeError – Encoding detection failed

Example

>>> data = load_trios("frequency_sweep.csv")
>>> print(data.test_mode)  # 'oscillation'
>>> print(data.is_complex)  # True (G* = G' + iG'')

>>> data = load_trios("creep_recovery.xlsx", sheet_name="all")
>>> print(len(data))  # Multiple sheets

rheojax.io.readers.trios.load_trios_chunked(filepath, chunk_size=10000, progress_callback=None, **kwargs)[source]¶

Load TRIOS file in memory-efficient chunks (generator).

Parameters:

filepath (str | Path) – Path to TRIOS .txt file
chunk_size (int) – Number of data points per chunk (default: 10,000) - Smaller = less memory, more overhead - Larger = more memory, less overhead - Recommended: 5,000 - 20,000 for most files
progress_callback (Callable | None) – Optional callback function for progress tracking. Signature: callback(current_points: int, total_points: int) Called periodically during loading (every 5-10% progress).
**kwargs – Additional options - segment_index: If provided, only process this segment (0-based) - validate_data: Validate each chunk (default: True)

Yields:

RheoData – Chunks of data with metadata preserved

Raises:

FileNotFoundError – If file doesn’t exist
ValueError – If file format is not recognized or no segments found

Example

>>> # Process large file in chunks
>>> for chunk in load_trios_chunked('large_file.txt', chunk_size=10000):
...     print(f"Processing {len(chunk.x)} points")
...     model.fit(chunk.x, chunk.y)
>>>
>>> # Aggregate results from chunks
>>> max_stress = -float('inf')
>>> for chunk in load_trios_chunked('file.txt'):
...     max_stress = max(max_stress, chunk.y.max())
>>> print(f"Maximum stress: {max_stress}")
>>>
>>> # With progress tracking
>>> def progress(current, total):
...     pct = 100 * current / total
...     print(f"Loading: {pct:.1f}%")
>>> for chunk in load_trios_chunked('large_file.txt', progress_callback=progress):
...     process(chunk)

CSV Reader¶

CSV file reader for rheological data.

rheojax.io.readers.csv_reader.load_csv(filepath, x_col, y_col=None, *, y_cols=None, x_units=None, y_units=None, domain=None, test_mode=None, deformation_mode=None, temperature=None, metadata=None, intended_transform=None, delimiter=None, encoding=None, column_mapping=None, strain_amplitude=None, angular_frequency=None, applied_stress=None, shear_rate=None, reference_gamma_dot=None, header=0, **kwargs)[source]

Load data from CSV or ASCII text file into RheoData.

Parameters:

filepath (str | Path) – Path to CSV or text file.
x_col (str | int) – Column name or index for x-axis data.
y_col (str | int | None) – Column name or index for y-axis data (single column). Mutually exclusive with y_cols.
y_cols (list[str | int] | None) – List of two column names/indices for complex modulus [G’, G’’] or [E’, E’’]. First column is storage modulus, second is loss modulus. Mutually exclusive with y_col.
x_units (str | None) – Units for x-axis (auto-detected from header if None).
y_units (str | None) – Units for y-axis (auto-detected from header if None).
domain (str | None) – Data domain (‘time’ or ‘frequency’, auto-detected if None).
test_mode (str | None) – Test mode (‘relaxation’, ‘creep’, ‘oscillation’, ‘rotation’). Auto-detected if None.
deformation_mode (str | None) – Deformation mode (‘shear’, ‘tension’, ‘bending’, ‘compression’). Auto-detected from column names if None. If ‘tension’/’bending’/’compression’, sets metadata for DMTA support.
temperature (float | None) – Temperature in Kelvin for TTS workflows.
metadata (dict | None) – Additional metadata dict to merge.
intended_transform (str | None) – Transform type for metadata validation. One of ‘mastercurve’, ‘srfs’, ‘owchirp’, ‘spp’, ‘fft’, ‘mutation’, ‘derivative’.
delimiter (str | None) – Column delimiter (auto-detected if None).
encoding (str | None) – File encoding (e.g. ‘utf-8’, ‘latin-1’, ‘cp1252’). Auto-detected if None. Use this to override detection for files with known encoding.
column_mapping (dict[str, str] | None) – Optional dict mapping original column names to new names. Applied immediately after reading, before any column lookup. Example: {“t”: “time”, “sigma”: “stress”}.
strain_amplitude (float | None) – Strain amplitude (gamma_0) stored in metadata as gamma_0. Used for LAOS/oscillation protocols.
angular_frequency (float | None) – Angular frequency (omega) stored in metadata as omega. Used for oscillation protocols.
applied_stress (float | None) – Applied stress stored in metadata as sigma_applied. Used for creep protocols.
shear_rate (float | None) – Shear rate stored in metadata as gamma_dot. Used for flow/startup protocols.
reference_gamma_dot (float | None) – Reference shear rate stored in metadata as reference_gamma_dot. Used for dimensionless flow analysis.
header (int | None) – Row number for column headers (None if no header).
**kwargs – Additional arguments passed to pandas.read_csv.

Return type:

Returns:

RheoData object with populated fields.

Raises:

FileNotFoundError – If file doesn’t exist.
KeyError – If specified columns don’t exist.
ValueError – If data cannot be parsed, y_cols has wrong length, or both y_col and y_cols are provided.

Warning

UserWarning: If intended_transform metadata is missing. UserWarning: If domain incompatible with intended_transform. UserWarning: If test_mode conflicts with intended_transform.

Example

>>> # Simple relaxation data
>>> data = load_csv("relaxation.csv", x_col="time (s)", y_col="G(t) (Pa)")
>>> # Complex modulus oscillation data
>>> data = load_csv(
...     "frequency_sweep.csv",
...     x_col="omega (rad/s)",
...     y_cols=["G' (Pa)", "G'' (Pa)"],
...     intended_transform='mastercurve',
...     temperature=298.15,
... )

rheojax.io.readers.csv_reader.detect_csv_delimiter(filepath)[source]

Public helper to auto-detect CSV/TSV delimiter.

Wrapper around the internal detection so that GUI helpers and previews can share the same logic as the main CSV reader.

Parameters:: filepath (str | Path) – Path to the text-based data file
Return type:: str
Returns:: Detected delimiter character

Load data from CSV or ASCII text file into RheoData.

Parameters:

filepath (str | Path) – Path to CSV or text file.
x_col (str | int) – Column name or index for x-axis data.
y_col (str | int | None) – Column name or index for y-axis data (single column). Mutually exclusive with y_cols.
y_cols (list[str | int] | None) – List of two column names/indices for complex modulus [G’, G’’] or [E’, E’’]. First column is storage modulus, second is loss modulus. Mutually exclusive with y_col.
x_units (str | None) – Units for x-axis (auto-detected from header if None).
y_units (str | None) – Units for y-axis (auto-detected from header if None).
domain (str | None) – Data domain (‘time’ or ‘frequency’, auto-detected if None).
test_mode (str | None) – Test mode (‘relaxation’, ‘creep’, ‘oscillation’, ‘rotation’). Auto-detected if None.
deformation_mode (str | None) – Deformation mode (‘shear’, ‘tension’, ‘bending’, ‘compression’). Auto-detected from column names if None. If ‘tension’/’bending’/’compression’, sets metadata for DMTA support.
temperature (float | None) – Temperature in Kelvin for TTS workflows.
metadata (dict | None) – Additional metadata dict to merge.
intended_transform (str | None) – Transform type for metadata validation. One of ‘mastercurve’, ‘srfs’, ‘owchirp’, ‘spp’, ‘fft’, ‘mutation’, ‘derivative’.
delimiter (str | None) – Column delimiter (auto-detected if None).
encoding (str | None) – File encoding (e.g. ‘utf-8’, ‘latin-1’, ‘cp1252’). Auto-detected if None. Use this to override detection for files with known encoding.
column_mapping (dict[str, str] | None) – Optional dict mapping original column names to new names. Applied immediately after reading, before any column lookup. Example: {“t”: “time”, “sigma”: “stress”}.
strain_amplitude (float | None) – Strain amplitude (gamma_0) stored in metadata as gamma_0. Used for LAOS/oscillation protocols.
angular_frequency (float | None) – Angular frequency (omega) stored in metadata as omega. Used for oscillation protocols.
applied_stress (float | None) – Applied stress stored in metadata as sigma_applied. Used for creep protocols.
shear_rate (float | None) – Shear rate stored in metadata as gamma_dot. Used for flow/startup protocols.
reference_gamma_dot (float | None) – Reference shear rate stored in metadata as reference_gamma_dot. Used for dimensionless flow analysis.
header (int | None) – Row number for column headers (None if no header).
**kwargs – Additional arguments passed to pandas.read_csv.

Return type:

Returns:

RheoData object with populated fields.

Raises:

FileNotFoundError – If file doesn’t exist.
KeyError – If specified columns don’t exist.
ValueError – If data cannot be parsed, y_cols has wrong length, or both y_col and y_cols are provided.

Warning

UserWarning: If intended_transform metadata is missing. UserWarning: If domain incompatible with intended_transform. UserWarning: If test_mode conflicts with intended_transform.

Example

>>> # Simple relaxation data
>>> data = load_csv("relaxation.csv", x_col="time (s)", y_col="G(t) (Pa)")
>>> # Complex modulus oscillation data
>>> data = load_csv(
...     "frequency_sweep.csv",
...     x_col="omega (rad/s)",
...     y_cols=["G' (Pa)", "G'' (Pa)"],
...     intended_transform='mastercurve',
...     temperature=298.15,
... )

Excel Reader¶

Excel file reader for rheological data.

rheojax.io.readers.excel_reader.load_excel(filepath, x_col, y_col=None, *, y_cols=None, sheet=0, x_units=None, y_units=None, domain=None, test_mode=None, deformation_mode=None, temperature=None, metadata=None, intended_transform=None, column_mapping=None, strain_amplitude=None, angular_frequency=None, applied_stress=None, shear_rate=None, reference_gamma_dot=None, header=0, **kwargs)[source]

Load data from Excel file into RheoData.

Parameters:

filepath (str | Path) – Path to Excel file (.xlsx or .xls).
x_col (str | int) – Column name or index for x-axis data.
y_col (str | int | None) – Column name or index for y-axis data (single column). Mutually exclusive with y_cols.
y_cols (list[str | int] | None) – List of two column names/indices for complex modulus [G’, G’’]. First column is storage modulus (G’), second is loss modulus (G’’). Mutually exclusive with y_col.
sheet (str | int) – Sheet name or index (default: 0 - first sheet).
x_units (str | None) – Units for x-axis (auto-detected from header if None).
y_units (str | None) – Units for y-axis (auto-detected from header if None).
domain (str | None) – Data domain (‘time’ or ‘frequency’, auto-detected if None).
test_mode (str | None) – Test mode (‘relaxation’, ‘creep’, ‘oscillation’, ‘rotation’). Auto-detected if None.
deformation_mode (str | None) – Deformation mode (‘shear’, ‘tension’, ‘bending’, ‘compression’). Auto-detected from column names if None. If ‘tension’/’bending’/’compression’, sets metadata for DMTA support.
temperature (float | None) – Temperature in Kelvin for TTS workflows.
metadata (dict | None) – Additional metadata dict to merge.
intended_transform (str | None) – Transform type for metadata validation. One of ‘mastercurve’, ‘srfs’, ‘owchirp’, ‘spp’, ‘fft’, ‘mutation’, ‘derivative’.
column_mapping (dict[str, str] | None) – Optional dict mapping original column names to new names. Applied immediately after reading, before any column lookup. Example: {“t”: “time”, “sigma”: “stress”}.
strain_amplitude (float | None) – Strain amplitude (gamma_0) stored in metadata as gamma_0. Used for LAOS/oscillation protocols.
angular_frequency (float | None) – Angular frequency (omega) stored in metadata as omega. Used for oscillation protocols.
applied_stress (float | None) – Applied stress stored in metadata as sigma_applied. Used for creep protocols.
shear_rate (float | None) – Shear rate stored in metadata as gamma_dot. Used for flow/startup protocols.
reference_gamma_dot (float | None) – Reference shear rate stored in metadata as reference_gamma_dot. Used for dimensionless flow analysis.
header (int | None) – Row number for column headers (None if no header).
**kwargs – Additional arguments passed to pandas.read_excel.

Return type:

Returns:

RheoData object with populated fields.

Raises:

FileNotFoundError – If file doesn’t exist.
ImportError – If pandas or openpyxl not installed.
KeyError – If specified columns or sheet don’t exist.
ValueError – If data cannot be parsed, y_cols has wrong length, or both y_col and y_cols are provided.

Warning

UserWarning: If intended_transform metadata is missing. UserWarning: If domain incompatible with intended_transform. UserWarning: If test_mode conflicts with intended_transform.

Example

>>> # Simple creep data from specific sheet
>>> data = load_excel(
...     "data.xlsx",
...     x_col="time (s)",
...     y_col="J(t) (1/Pa)",
...     sheet="Creep Test",
... )
>>> # Flow curve with explicit test mode
>>> data = load_excel(
...     "flow_curve.xlsx",
...     x_col=0,
...     y_col=1,
...     test_mode='rotation',
...     x_units='1/s',
...     y_units='Pa·s',
... )
>>> # Complex modulus from Excel
>>> data = load_excel(
...     "frequency_sweep.xlsx",
...     x_col="omega (rad/s)",
...     y_cols=["G' (Pa)", "G'' (Pa)"],
...     intended_transform='mastercurve',
...     temperature=298.15,
... )

Load data from Excel file into RheoData.

Parameters:

filepath (str | Path) – Path to Excel file (.xlsx or .xls).
x_col (str | int) – Column name or index for x-axis data.
y_col (str | int | None) – Column name or index for y-axis data (single column). Mutually exclusive with y_cols.
y_cols (list[str | int] | None) – List of two column names/indices for complex modulus [G’, G’’]. First column is storage modulus (G’), second is loss modulus (G’’). Mutually exclusive with y_col.
sheet (str | int) – Sheet name or index (default: 0 - first sheet).
x_units (str | None) – Units for x-axis (auto-detected from header if None).
y_units (str | None) – Units for y-axis (auto-detected from header if None).
domain (str | None) – Data domain (‘time’ or ‘frequency’, auto-detected if None).
test_mode (str | None) – Test mode (‘relaxation’, ‘creep’, ‘oscillation’, ‘rotation’). Auto-detected if None.
deformation_mode (str | None) – Deformation mode (‘shear’, ‘tension’, ‘bending’, ‘compression’). Auto-detected from column names if None. If ‘tension’/’bending’/’compression’, sets metadata for DMTA support.
temperature (float | None) – Temperature in Kelvin for TTS workflows.
metadata (dict | None) – Additional metadata dict to merge.
intended_transform (str | None) – Transform type for metadata validation. One of ‘mastercurve’, ‘srfs’, ‘owchirp’, ‘spp’, ‘fft’, ‘mutation’, ‘derivative’.
column_mapping (dict[str, str] | None) – Optional dict mapping original column names to new names. Applied immediately after reading, before any column lookup. Example: {“t”: “time”, “sigma”: “stress”}.
strain_amplitude (float | None) – Strain amplitude (gamma_0) stored in metadata as gamma_0. Used for LAOS/oscillation protocols.
angular_frequency (float | None) – Angular frequency (omega) stored in metadata as omega. Used for oscillation protocols.
applied_stress (float | None) – Applied stress stored in metadata as sigma_applied. Used for creep protocols.
shear_rate (float | None) – Shear rate stored in metadata as gamma_dot. Used for flow/startup protocols.
reference_gamma_dot (float | None) – Reference shear rate stored in metadata as reference_gamma_dot. Used for dimensionless flow analysis.
header (int | None) – Row number for column headers (None if no header).
**kwargs – Additional arguments passed to pandas.read_excel.

Return type:

Returns:

RheoData object with populated fields.

Raises:

FileNotFoundError – If file doesn’t exist.
ImportError – If pandas or openpyxl not installed.
KeyError – If specified columns or sheet don’t exist.
ValueError – If data cannot be parsed, y_cols has wrong length, or both y_col and y_cols are provided.

Warning

UserWarning: If intended_transform metadata is missing. UserWarning: If domain incompatible with intended_transform. UserWarning: If test_mode conflicts with intended_transform.

Example

>>> # Simple creep data from specific sheet
>>> data = load_excel(
...     "data.xlsx",
...     x_col="time (s)",
...     y_col="J(t) (1/Pa)",
...     sheet="Creep Test",
... )
>>> # Flow curve with explicit test mode
>>> data = load_excel(
...     "flow_curve.xlsx",
...     x_col=0,
...     y_col=1,
...     test_mode='rotation',
...     x_units='1/s',
...     y_units='Pa·s',
... )
>>> # Complex modulus from Excel
>>> data = load_excel(
...     "frequency_sweep.xlsx",
...     x_col="omega (rad/s)",
...     y_cols=["G' (Pa)", "G'' (Pa)"],
...     intended_transform='mastercurve',
...     temperature=298.15,
... )

Anton Paar Reader¶

RheoCompass CSV parser for Anton Paar rheometer exports.

This module provides a complete parser for RheoCompass CSV exports with: - Interval-based data block parsing - Automatic encoding detection (UTF-16, UTF-8, Latin-1) - Test type auto-detection (creep, relaxation, oscillation, rotation) - Metadata extraction (geometry, gap, temperature) - Unit normalization to SI - Derived quantity computation (J(t), G(t), G*)

The parser handles RheoCompass-specific format features including tab-separated values, “Interval and data points:” markers, and locale-aware decimal separators.

rheojax.io.readers.anton_paar.parse_rheocompass_intervals(filepath, *, encoding=None, marker='Interval and data points:')[source]¶

Parse RheoCompass file returning raw interval blocks.

Low-level parser for advanced users who need full access to all columns and metadata without RheoData mapping.

Parameters:

filepath (str | Path) – Path to RheoCompass CSV export file
encoding (str | None) – File encoding override (auto-detected if None)
marker (str) – Interval start marker string

Return type:

tuple[dict[str, Any], list[IntervalBlock]]

Returns:

Tuple of (global_metadata, interval_blocks)

Raises:

FileNotFoundError – File does not exist
ValueError – No interval blocks found
UnicodeDecodeError – Encoding detection failed

rheojax.io.readers.anton_paar.load_anton_paar(filepath, *, test_mode=None, interval=None, return_all=False, encoding=None, x_col=None, y_col=None, progress_callback=None)[source]¶

Load RheoCompass CSV export file and return RheoData object(s).

Handles interval-based file structure, auto-detects test type, extracts metadata, and normalizes units to SI.

Parameters:

filepath (str | Path) – Path to RheoCompass CSV export file
test_mode (str | None) – Explicit test mode override (“creep”, “relaxation”, “oscillation”, “rotation”). If None, auto-detected from columns.
interval (int | None) – Specific interval index to load (1-based). If None with return_all=False, returns first interval.
return_all (bool) – If True, always return list of RheoData.
encoding (str | None) – File encoding override (auto-detected if None).
x_col (str | None) – Override for x-axis column selection.
y_col (str | None) – Override for y-axis column selection.
progress_callback (Callable[[int, int], None] | None) – Callback receiving (current, total) for progress.

Return type:

Returns:

Single RheoData for single-interval files (unless return_all=True). List of RheoData for multi-interval files or when return_all=True.

Raises:

FileNotFoundError – File does not exist
ValueError – No interval blocks, cannot detect test type, or interval index out of range

rheojax.io.readers.anton_paar.save_intervals_to_excel(rheo_data_list, filepath, *, include_metadata_sheet=True, sheet_prefix='Interval')[source]¶

Export multi-interval RheoData to Excel with one sheet per interval.

Creates an Excel workbook where each interval becomes its own sheet (Interval_1, Interval_2, …) plus an optional Metadata sheet containing global metadata and per-interval summary.

Parameters:

rheo_data_list (list[RheoData] | RheoData) – Single RheoData or list of RheoData objects (typically from load_anton_paar with return_all=True)
filepath (str | Path) – Output Excel file path (.xlsx)
include_metadata_sheet (bool) – Add a Metadata sheet with global info (default True)
sheet_prefix (str) – Prefix for interval sheet names (default “Interval”)

Raises:

ImportError – If pandas or openpyxl not installed
ValueError – If rheo_data_list is empty

Return type:

Example

>>> data_list = load_anton_paar("temp_sweep.csv", return_all=True)
>>> save_intervals_to_excel(data_list, "output.xlsx")
# Creates: Metadata, Interval_1, Interval_2, Interval_3 sheets

rheojax.io.readers.anton_paar.load_anton_paar(filepath, *, test_mode=None, interval=None, return_all=False, encoding=None, x_col=None, y_col=None, progress_callback=None)[source]

Load RheoCompass CSV export file and return RheoData object(s).

Handles interval-based file structure, auto-detects test type, extracts metadata, and normalizes units to SI.

Parameters:

filepath (str | Path) – Path to RheoCompass CSV export file
test_mode (str | None) – Explicit test mode override (“creep”, “relaxation”, “oscillation”, “rotation”). If None, auto-detected from columns.
interval (int | None) – Specific interval index to load (1-based). If None with return_all=False, returns first interval.
return_all (bool) – If True, always return list of RheoData.
encoding (str | None) – File encoding override (auto-detected if None).
x_col (str | None) – Override for x-axis column selection.
y_col (str | None) – Override for y-axis column selection.
progress_callback (Callable[[int, int], None] | None) – Callback receiving (current, total) for progress.

Return type:

Returns:

Single RheoData for single-interval files (unless return_all=True). List of RheoData for multi-interval files or when return_all=True.

Raises:

FileNotFoundError – File does not exist
ValueError – No interval blocks, cannot detect test type, or interval index out of range

Writers¶

File writers for rheological data.

This module provides writers for various output formats: - HDF5 for data archiving - Excel for reporting - NumPy .npz for lightweight archiving

rheojax.io.writers.save_hdf5(data, filepath, compression=True, compression_level=4, **kwargs)[source]¶

Save RheoData to HDF5 file.

HDF5 is the recommended format for archiving rheological data. It provides: - Efficient storage with compression - Preservation of all metadata - Fast read/write performance - Cross-platform compatibility

Parameters:

data (RheoData) – RheoData object to save
filepath (str | Path) – Output file path
compression (bool) – Enable gzip compression (default: True)
compression_level (int) – Compression level 0-9 (default: 4)
**kwargs – Additional arguments passed to h5py

Raises:

ImportError – If h5py not installed
ValueError – If data is invalid
IOError – If file cannot be written

Return type:

rheojax.io.writers.load_hdf5(filepath)[source]¶

Load RheoData from HDF5 file.

Parameters:

filepath (str | Path) – Path to HDF5 file

Return type:

Returns:

RheoData object

Raises:

ImportError – If h5py not installed
FileNotFoundError – If file doesn’t exist
ValueError – If file format is invalid

rheojax.io.writers.save_excel(results, filepath, include_plots=False, **kwargs)[source]¶

Save results to Excel file for reporting.

Creates an Excel workbook with multiple sheets for different result types: - Parameters sheet: Model parameters and values - Fit Quality sheet: R², RMSE, and other metrics - Predictions sheet: Model predictions - Residuals sheet: Fitting residuals

Parameters:

results (dict[str, Any]) – Dictionary containing results - ‘parameters’: dict of parameter names and values - ‘fit_quality’: dict of fit metrics (R2, RMSE, etc.) - ‘predictions’: array of model predictions (optional) - ‘residuals’: array of residuals (optional)
filepath (str | Path) – Output file path (.xlsx)
include_plots (bool) – Include embedded plots (requires matplotlib)
**kwargs – Additional arguments

Raises:

ImportError – If pandas or openpyxl not installed
ValueError – If results format is invalid
IOError – If file cannot be written

Return type:

rheojax.io.writers.save_npz(data, filepath, compressed=True)[source]¶

Save a RheoData object to a NumPy .npz archive.

Strings and metadata are stored as UTF-8 encoded uint8 byte arrays — no pickle is used.

Parameters:

data (RheoData) – RheoData object to save.
filepath (str | Path) – Destination path (np.savez appends .npz if not present).
compressed (bool) – If True (default), use np.savez_compressed. If False, use np.savez (larger file, faster write).

Raises:

OSError – If the file cannot be written.

Return type:

rheojax.io.writers.load_npz(filepath)[source]¶

Load a RheoData object from a NumPy .npz archive.

Parameters:

filepath (str | Path) – Path to the .npz file (with or without .npz extension).

Return type:

Returns:

Reconstructed RheoData object.

Raises:

FileNotFoundError – If the file does not exist.
ValueError – If the file is not a valid RheoData npz archive.

HDF5 Writer¶

HDF5 writer for rheological data.

rheojax.io.writers.hdf5_writer.save_hdf5(data, filepath, compression=True, compression_level=4, **kwargs)[source]¶

Save RheoData to HDF5 file.

Parameters:

data (RheoData) – RheoData object to save
filepath (str | Path) – Output file path
compression (bool) – Enable gzip compression (default: True)
compression_level (int) – Compression level 0-9 (default: 4)
**kwargs – Additional arguments passed to h5py

Raises:

ImportError – If h5py not installed
ValueError – If data is invalid
IOError – If file cannot be written

Return type:

rheojax.io.writers.hdf5_writer.save_fit_result_hdf5(result, filepath, compression=True, compression_level=4)[source]¶

Save a FitResult to HDF5 file.

Stores model parameters, statistics, fitted curve, and metadata in a structured HDF5 layout.

Parameters:

result (Any) – A FitResult instance (from rheojax.core.fit_result).
filepath (str | Path) – Output file path.
compression (bool) – Enable gzip compression (default: True).
compression_level (int) – Compression level 0-9 (default: 4).

Raises:

ImportError – If h5py not installed.

Return type:

rheojax.io.writers.hdf5_writer.load_hdf5(filepath)[source]¶

Load RheoData from HDF5 file.

Parameters:

filepath (str | Path) – Path to HDF5 file

Return type:

Returns:

RheoData object

Raises:

ImportError – If h5py not installed
FileNotFoundError – If file doesn’t exist
ValueError – If file format is invalid

rheojax.io.writers.hdf5_writer.save_hdf5(data, filepath, compression=True, compression_level=4, **kwargs)[source]

Save RheoData to HDF5 file.

Parameters:

data (RheoData) – RheoData object to save
filepath (str | Path) – Output file path
compression (bool) – Enable gzip compression (default: True)
compression_level (int) – Compression level 0-9 (default: 4)
**kwargs – Additional arguments passed to h5py

Raises:

ImportError – If h5py not installed
ValueError – If data is invalid
IOError – If file cannot be written

Return type:

Write RheoData to HDF5 file with full metadata preservation.

HDF5 Structure:

file.h5
|-- x_data (dataset)         # Independent variable
|-- y_data (dataset)         # Dependent variable
|-- attributes/
|   |-- x_units (attr)
|   |-- y_units (attr)
|   |-- domain (attr)
|   \-- ... (metadata)

Excel Writer¶

Excel writer for rheological data and results.

rheojax.io.writers.excel_writer.save_excel(results, filepath, include_plots=False, **kwargs)[source]¶

Save results to Excel file for reporting.

Parameters:

results (dict[str, Any]) – Dictionary containing results - ‘parameters’: dict of parameter names and values - ‘fit_quality’: dict of fit metrics (R2, RMSE, etc.) - ‘predictions’: array of model predictions (optional) - ‘residuals’: array of residuals (optional)
filepath (str | Path) – Output file path (.xlsx)
include_plots (bool) – Include embedded plots (requires matplotlib)
**kwargs – Additional arguments

Raises:

ImportError – If pandas or openpyxl not installed
ValueError – If results format is invalid
IOError – If file cannot be written

Return type:

rheojax.io.writers.excel_writer.save_excel(results, filepath, include_plots=False, **kwargs)[source]

Save results to Excel file for reporting.

Parameters:

results (dict[str, Any]) – Dictionary containing results - ‘parameters’: dict of parameter names and values - ‘fit_quality’: dict of fit metrics (R2, RMSE, etc.) - ‘predictions’: array of model predictions (optional) - ‘residuals’: array of residuals (optional)
filepath (str | Path) – Output file path (.xlsx)
include_plots (bool) – Include embedded plots (requires matplotlib)
**kwargs – Additional arguments

Raises:

ImportError – If pandas or openpyxl not installed
ValueError – If results format is invalid
IOError – If file cannot be written

Return type: