Downhole Performance · CSV schema

1. Data columns: canonical Field units

Every numeric column in the CSV is emitted in canonical Field units — depth in ft, pressure in psi, temperature in °F — regardless of the per-chart unit toggles (Auto / Field / SI) selected in the UI.

This keeps the schema stable so spreadsheets, pandas pipelines, and downstream tools can rely on a single, well-defined column shape:

depth [ft],hydrostatic [psi],wellbore_pressure [psi],geothermal_temperature [°F],flowing_temperature [°F]

The unit is restated in [brackets] on every column header per project convention.

2. Per-chart unit metadata

The pressure-vs-depth and temperature-vs-depth charts each carry an independent unit override (Auto / Field / SI). To preserve what the user saw at export time, the CSV records the resolved selection in the metadata header above the data:

# Pressure chart units: [AUTO → SI] SI (kPa, m, °C) · y-axis "Pressure [kPa]"
# Temperature chart units: [FIELD] Field (psi, ft, °F) · y-axis "Temperature [°F]"

Read the bracketed tag as the toggle state. AUTO → SI means the chart was on Auto and resolved to SI through the global unit toggle; FIELD means the chart was explicitly locked to Field.

The table below shows how each toggle resolves per quantity. Data columns are always emitted in the canonical Field column regardless of the chart toggle — only the chart axis, tooltip, and the shown as … suffix on *_ref_* columns change.

Conversions: kPa = psi × 6.894757, m = ft × 0.3048, °C = (°F − 32) × 5⁄9. Auto resolves through the app-wide unit toggle, so the same export can record AUTO → FIELD for one user and AUTO → SI for another.

3. Reference lines & scenario targets

Overlays such as BHP target, BHP min, and BHP max are recorded in two places so downstream tools can choose either representation:

• Metadata header — one line per overlay with both the canonical Field value and the chart-formatted display value:

  # Pressure chart reference lines (display in chart units):
  #   - BHP target: 8000.00 psi (canonical) · 55,158 kPa (as shown)

• Appended columns — one constant column per overlay, named <chart>_ref_<slug> with a bracket suffix that encodes both the canonical unit and the chart-selected display formatting:

  pressure_ref_bhp_target [psi | shown as 55,158 kPa]

  The numeric values in these columns are always canonical Field — the display formatting is preserved in the header label only.

Currently exported BHP columns

The Downhole results view emits exactly three pressure-chart reference overlays — the BHP target and the BHP min/max range. Each one becomes a single constant column appended after the canonical schema. Slugs come from the UI label via label.toLowerCase().replace(/[^a-z0-9]+/g, "_"), so the set is fixed:

The shown as … suffix mirrors the pressure chart's unit toggle at export time — the same overlay reads psi | shown as 8,000 psi when the chart is on Field and psi | shown as 55,158 kPa when it resolved to SI. The data value in the column body is always the canonical Field number (psi). If the BHP target/min/max inputs are blank or the pressure chart has no overlays, the corresponding columns are omitted entirely — they never appear as empty placeholders.

Two-row header structure for BHP columns

Each BHP overlay column occupies the same column index across two consecutive header rows. Row 1 carries the machine-readable column name; row 2 carries the unit cell, which encodes both the canonical unit and the chart's display formatting at export time. Pivot the column index, not the row order, when parsing — the data rows that follow line up under row 1.

• Row 1 is the only row downstream tools should key on for column lookup — it never changes with the unit toggle.
• Row 2 is informational. The substring before | is the canonical unit (always psi for BHP); the substring after shown as is the chart-formatted display (e.g. 55,158 kPa when the pressure toggle resolved to SI).
• If a row-2 cell contains a comma (it always does for BHP because of the thousands separator), the cell is CSV-quoted — "psi | shown as 8,000 psi" — so a standards-compliant CSV parser is required.

Export preview

Toggle the pressure chart's unit selection below to see the exact metadata line and the two header rows the exporter writes. The BHP overlay cells in row 2 update live; everything else stays canonical.

# Pressure chart units: [Auto → FIELD] Field (psi, ft, °F) · y-axis "Pressure [psi]"

depth,hydrostatic,wellbore_pressure,geothermal_temperature,flowing_temperature,pressure_ref_bhp_target,pressure_ref_bhp_min,pressure_ref_bhp_max

ft,psi,psi,°F,°F,"psi | shown as 8,000 psi","psi | shown as 6,500 psi","psi | shown as 9,500 psi"

4. Importer guarantees

The bundled CSV validator (drop-zone on the Downhole results view) accepts any file whose column header begins with the canonical schema and whose extra columns match (pressure|temperature)_ref_<slug> [...]. It also checks that every Auto → … tag resolves to the same system the y-axis label declares, so a CSV exported from one unit-toggle configuration and re-imported under another will be flagged with a clear error code.

5. Validation checklist

The drop-zone validator on the Downhole results view runs each of these checks in order and surfaces a stable code per issue so downstream tooling can branch on the failure type without string-matching the human message.

A file is reported as ok: true only when every error-level check passes. Warnings never block import — they're surfaced so you can still spot non-fatal drift (e.g. a hand-stripped title).

6. Sample CSV

A real export — produced by the same buildDownholeProfileCsv code path the app uses — is bundled with the site so you can verify your parser against the documented schema. It includes three pressure overlays (BHP target, BHP min, BHP max), an Auto → SI pressure chart selection, and an explicit Field temperature chart selection.

Stable schema: column shape and metadata layout match the format described in sections 1–5. Re-running the export only refreshes the # Generated: timestamp.