🤝 Contributing a dataset

rheodata grows the way good science grows: from the literature and from the community. If you know a paper whose curves deserve a second life — or you have your own measurements to share — here’s how to get them into the registry.

1️⃣ Open a submission issue

Every dataset starts as a GitHub issue using the data submission template, which carries the data-submission label.

At minimum the issue must give us:

  • 📄 Paper name (title, authors, journal, year)

  • 🔗 DOI — every dataset cites its source with a clickable DOI link, no exceptions

  • 📊 Which figure(s) the data comes from

Anything else you know is welcome: the samples, the instrument, the geometry, the temperature, the protocol. The more you tell us, the better the metadata entry, and the more useful the dataset becomes.

A maintainer will then extract the data from the figures (digitized curves are marked as such in the provenance record), tidy it up, and open a pull request adding the dataset.

2️⃣ What good metadata looks like 🗂️

A dataset nobody can contextualize is a dataset nobody trusts. Every entry in the registry documents:

  • Material — name and kind (e.g. Carbopol 940, yield-stress fluid; aqueous PEO, linear polymer solution)

  • Source — full citation of the paper plus a clickable DOI, and the figure the data was taken from

  • Measurement — the experiment type (flow curve, frequency sweep, …), the geometry (cone–plate, parallel plate, Couette, capillary, …) with details when they matter (cone angle and diameter, gap, bob radius), the temperature in °C, and the protocol (pre-shear, equilibration time, sweep direction, points per decade…)

  • Samples — one row per curve: sample id and a human-readable label

  • Provenance — literature (digitized from a published figure) or community (contributed directly), and whether the numbers are digitized

If a field is genuinely unknown, it stays empty rather than guessed — an honest gap beats a fabricated detail.

3️⃣ Tidy-CSV rules 📋

Every dataset ships its numbers as tidy CSV files — one row per observation — and must follow these rules before it is accepted:

  1. SI units, always. Shear rate in s⁻¹, shear stress in Pa, viscosity in Pa·s, temperature in °C, moduli in Pa, frequency in rad·s⁻¹. No mPa, no cP, no hidden factors.

  2. x sorted. Within each sample, rows are sorted by the independent variable (shear rate, frequency, …) in ascending order.

  3. No NaNs. Missing values are not allowed; a row with a NaN is a row that shouldn’t exist.

  4. One header row with snake_case column names (shear_rate, shear_stress, viscosity, …).

  5. UTF-8, comma-separated, Unix line endings.

4️⃣ The dataset.yaml schema 📐

Each dataset directory (rheodata/datasets/<id>/) carries a dataset.yaml that describes the dataset. Every field:

Field

Type

Required

Description

id

string

✅

Short slug identifying the dataset, e.g. carbopol_caggioni_2020. Used in load(id) / plot(id) and as the page filename.

title

string

✅

Human-readable title shown on the dataset page.

description

string

✅

One or two sentences: what the data shows and why it’s interesting.

material.name

string

✅

Material name, e.g. Carbopol 940.

material.kind

string

✅

Material class, e.g. yield-stress fluid, linear polymer solution, wormlike micelles.

source.paper.title

string

✅

Paper title.

source.paper.authors

list of strings

✅

Authors in order.

source.paper.journal

string

✅

Journal name.

source.paper.year

integer

✅

Publication year.

source.paper.doi

string

✅

DOI (bare, e.g. 10.1122/1.5120633) — rendered as a clickable link on the dataset page.

source.figure

string

✅

Figure the data was taken from, e.g. Figure 3.

provenance.origin

string

✅

literature or community.

provenance.digitized

boolean

✅

true if the numbers were digitized from a figure; false for directly contributed data.

measurement.type

string

✅

Experiment type: flow curve, frequency sweep, amplitude sweep, …

measurement.geometry

string

✅

Geometry, e.g. cone–plate, parallel plate, Couette, capillary.

measurement.geometry_details

string

Details that matter: cone angle/diameter, gap, bob radius, …

measurement.temperature_C

number

✅

Measurement temperature in °C.

measurement.protocol

string

Protocol notes: pre-shear, equilibration, sweep direction, points per decade, …

samples

list of {id, label}

✅

One entry per curve: a short id and a human-readable label (e.g. concentration, temperature).

columns

list of {name, description}

Documents every CSV column and its units — this is what users see in the Data columns table.

tags

list of strings

Search tags, e.g. yield stress, temperature series, thixotropy.

5️⃣ What happens next 🔄

A maintainer turns the issue into a pull request: tidy CSVs, the dataset.yaml, and the registry entry. The docs build then generates the dataset’s page (metadata table, samples, preview plot) automatically. Once merged, the dataset is live in the catalog and loadable with rheodata.load("<id>").