🔧 API reference

The full public API of the rheodata package: list the registry, load tidy data, and plot it.

Top-level package

rheodata — curated, quality-checked rheology datasets.

Find experimental datasets for training, simulation, and benchmarking:

>>> import rheodata
>>> rheodata.list()                      # every dataset, one row each
>>> rheodata.search(material="carbopol")  # substring filters
>>> rheodata.info("caggioni_pg_carbopol_2pct")    # human-readable summary
>>> ds = rheodata.load("caggioni_pg_carbopol_2pct")
>>> ds.df.head()                         # tidy DataFrame
>>> fig = rheodata.plot("caggioni_pg_carbopol_2pct")
>>> rdf = rheodata.to_rheofit("caggioni_pg_carbopol_2pct", sample="carbopol_2pct")

class rheodata.Dataset(df: DataFrame, meta: dict, id: str)

Bases: object

One loaded dataset: tidy data, metadata, and id.

df: DataFrame

Tidy data as stored in data.csv.

id: str

Dataset id (directory name).

meta: dict

Full parsed dataset.yaml metadata.

exception rheodata.DatasetError

Bases: Exception

Raised when a dataset fails registry validation.

rheodata.info(ds_id: str) → None

Print a readable summary of a dataset.

rheodata.list() → DataFrame

One row per dataset: id, title, material, experiment, samples, year, doi.

rheodata.load(ds_id: str) → Dataset

Load a dataset: Dataset(df, meta, id) with the tidy data.csv.

rheodata.load_registry(root: Path | str | None = None) → dict

Load and validate every dataset under root.

Defaults to the packaged rheodata/datasets directory discovered via importlib.resources. Returns {dataset_id: {"meta": ..., "path": ...}}. Raises DatasetError naming the offending dataset on failure.

rheodata.plot(ds_id: str, sample: str | int | None = None) → Figure

Experiment-appropriate plot; returns a matplotlib.figure.Figure.

• flow_curve: log-log σ(x) and η(x) = y/x on twin y-axes, one curve per sample

• amplitude_sweep / frequency_sweep: G′, G″ vs x (log-log)

• shear_startup: stress vs strain (log-linear x)

• creep / stress_relaxation: strain/stress vs time (log-log)

rheodata.search(material: str | None = None, experiment: str | None = None, tag: str | None = None, query: str | None = None) → DataFrame

Substring filters (case-insensitive) over the registry.

query matches title, description, and material name.

rheodata.to_rheofit(ds_id: str, sample: str | int) → DataFrame

Flow-curve sample as a rheofit-compatible DataFrame.

Columns "Shear rate / 1/s" and "Stress / Pa", x sorted ascending. Raises a clear error if the dataset is not a flow curve.