Exports

When to use exports

Use an export when someone outside the platform needs a file of a sensor's readings: a regulator's data centre (CEDEN, EPA WQX), a hydraulic model (HEC-DSS), a colleague's R script (USGS RDB), a data repository (WaterML 2.0), or a spreadsheet laid out the way a lab loader expects (a custom table). Every format reads the same readings, grades them against the QC policy you pick, converts units where the target format demands a particular unit, and refuses rather than truncates a file that would be incomplete or misleading. If you need readings on a schedule instead of a one-off file, see Without the browser.

Open Export from the navigation — the item is called Export on the bar, and this is the page it leads to. The landing page lists the formats on offer and the sensors you can export (with the same folder bar, group chips and search box as the other sensor lists); pick a sensor to reach its export hub.

The formats

The hub groups formats by family. The first two need a saved CEDEN mapping before they can build anything; the rest map straight off each variable's observed property and unit from the Settings page.

Standard-unit formats (USGS, HEC-DSS, WQX, CEDEN) stamp a fixed unit on each column, so a series stored in another unit is converted when a conversion is defined (m³/s → ft³/s, m → ft, °F → °C and so on) and the file tells you so; a stored unit with no defined conversion is left out with a reason, never published under a unit it is not in. A variable with no stored unit is written unchanged with a warning asking you to confirm it.

QC export policies

Every format offers the same four answers to "what do I submit, given what the data-quality pass found". The policy decides which readings are written and, in the formats that have a flag cell, what the recipient is told about each one (CEDEN's QACode and ResultsComments, WQX's Result Comment and Result Status ID, USGS's _cd qualifier column). Flags themselves are explained on the Data quality page.

Two details apply under every policy. A gap-filled (interpolated) point passes QC but is not a measurement, so it is always published as estimated — QAX with the comment "Estimated: interpolated over a gap, not measured" in CEDEN, the e qualifier in USGS. And in USGS RDB the two cases NWIS has no code for are written with local codes declared in the file's own comment block: x for a reading that failed QC and u for one never graded.

From landing page to file

The sensor's export hub

Clicking a sensor on the landing page opens its hub: one card per format, grouped by family. The CEDEN cards carry a link to open the CEDEN workbench, because those two formats cannot build anything until the sensor is a station with its variables mapped. The Custom table card opens the builder; any saved custom formats you can use appear as buttons beneath it and open the custom workbench directly.

The workbench

Each format has the same workbench. The What will export panel lists every variable as exports or skipped with the reason (no USGS parameter code, no defined unit conversion, no CEDEN analyte mapped…) and shows the warnings the file will carry. Below it, the Export form:

If the preview examines its first 20,000 readings and none survive the policy, it says so in those words rather than claiming the window is empty — the count above it still covers the whole window.

What the summary after a download tells you

The line under the buttons is the completeness evidence for the file you just saved: "Downloaded N row(s), M left out." followed by one line per drop reason (failed QC, no value, outside an approved period, and so on) and any writer warnings (a unit that was converted or guessed, the HEC-DSS flag note). WQX files are streamed, so their counts arrive a moment after the file does; if a streamed download ended before the export finished, the summary says the saved file is INCOMPLETE and to run it again. Keep the summary with the file if you are filing a submission — the same counts are in the file's response headers but a browser does not show those.

Refusals, and what to do

A refusal is a message instead of a file. The ones you are most likely to meet:

• Over the row limit — "That window produces N rows, more than the limit-row limit one export file should carry. Export a shorter window…" The limit is sized to what the server can build inside its request timeout (160,000 rows at the default settings; the message quotes the live number). Shorten the window or export fewer columns.
• Still building at the deadline — "This export was still building after N seconds…" The server refused rather than being cut off part-way. Export a shorter window, or a single variable.
• Nothing survived — "Refusing to build this … export: every one of the N reading(s) in this window was left out…" with the reasons. Widen the window, choose a different QC policy, or use a format that can carry these readings.
• Nothing maps — not one selected variable can be carried by this format (no parameter code, no analyte, no unit conversion). Choose another format, or fix the variable's observed property and unit on the Settings page.
• Collisions — two readings of one series inside the same minute (CEDEN legacy) or second (CEDEN 2.0, WQX, USGS), or two series that build the same DSS pathname, would overwrite each other in the target format, so the window is refused; export the variables separately or a window that avoids the duplicate.
• Not set up for CEDEN — "This sensor is not set up for CEDEN yet. Create a profile and map its variables in the CEDEN workbench first."
• Rate limit — "Too many exports from this account in the last hour." Each account may download 60 exports and run 240 previews an hour; wait a few minutes.

The CEDEN mapping workbench

A CEDEN FieldResults file is long: your wide logger table (one row per instant, one column per variable) becomes one row per measurement, and every row carries descriptive cells your header never held — project, agency, station, analyte, unit, fraction, matrix, method. The CEDEN workbench is where you say what those cells are, once, so both CEDEN formats can fill them in. Reach it from the landing page (Set up CEDEN mapping), from a sensor's export hub, or from Data quality.

Submission profiles

The CEDEN export hub lists your profiles and creates new ones. A profile holds the cells CEDEN expects to be identical on every row of a project's submission — you fill them in once rather than per station. It is shared with your group when you have one.

Create profile saves it; Delete on a profile removes its stations and variable mappings with it. Each profile lists its stations, and each station name opens that sensor's workbench under that profile. Download the example spreadsheet (example.csv) gives you a filled-in FieldResults sample to open beside the blank template your data centre sent you.

The sensor's workbench: station and variables

The per-sensor workbench has three steps. Step 1 shows what CEDEN expects, column by column, colour-coded by where each cell comes from (your profile, this station, each variable, the reading, its data-quality flag, or a constant). Step 2, Match your variables, is the mapping:

• Profile — which submission profile this station reports under (project, agency and protocol come from it).
• StationCode (must already be registered with CEDEN), LocationCode (default Midchannel), CollectionDeviceName (the instrument, e.g. Hydros 21), CollectionDepth and its Depth unit, PositionWaterColumn.
• One card per variable with AnalyteName, UnitName, FractionName, MatrixName and MethodName, pre-filled from what the column measures. The badge says where the card stands: Confirmed (a person saved it), Suggested, Check this, or No analyte. Choosing — do not export this variable — as the analyte is a real answer: battery voltage has no business in a FieldResults file. Analytes the app could not confirm against CEDEN's published lookup lists are marked "(verify)".
• Accept all suggestions fills every card from the suggestion; Save mapping saves the station and marks every variable above as confirmed. An unconfirmed mapping still exports, but the export warns you which analytes went out on a suggestion nobody checked.

Step 3, Preview and export, is the CEDEN-only twin of the workbench above: From/To in the sensor's timezone, the four policies as cards with their descriptions, Preview rows (the first 12 rows exactly as they will be written) and Download CSV. Step 3 writes the legacy FieldResults CSV; the CEDEN cards on the export hub build the same file, or the 2.0 template, from this same mapping.

The custom format builder

Open Custom export formats from the landing page (Build a custom format) or the hub. A saved format lists its name, layout and column count with Edit and Delete; the form below it creates a new one.

Then the columns. + Add column adds a row with a Header (the text in the file's header line), a Source, and the option that source needs; ✕ removes it. A new format starts with a time timestamp column and a value column.

Save format validates the definition and keeps it; it then appears in the Custom format drop-down of every sensor's custom workbench. The QC policy you pick at export time still governs which readings appear — a custom file drops exactly the readings the chosen policy drops, no more, no less.

Unit provenance warnings

Three warnings about units can appear in a preview, a download summary or the CEDEN workbench, and all three are about evidence rather than arithmetic:

• "…the unit X was inferred from the column name when this variable was discovered, not recorded from the source or confirmed by anyone…" — the unit was guessed at discovery. Check it on the Settings page and save the variable, which confirms it and silences the warning.
• "…stored in X, converted to Y for this export." — the numbers in the file are not the stored numbers; a defined conversion was applied.
• "…this variable's unit was CHANGED on date (previously X)…" — a unit edit applies to the whole stored series, including readings taken before the edit. Check the export window against the change date before submitting.

Without the browser

Everything above is a one-off file. For a client that needs to pull data on a schedule there are two read services: the OGC SensorThings API for querying, and a WaterML 2.0 endpoint that returns the same document the WaterML 2.0 format builds. Both serve public series openly; a private sensor's series is served to a signed-in member who can read it, or to a client presenting the sensor's read token (X-Read-Token or Authorization: Bearer). See the API documentation.