Home › reference › api

API and data access

Fifteen public functions and two objects. This page is a map, not a full reference: every signature below has a docstring with the argument semantics spelled out, and help(tc.analyse) is the authoritative text if this page and the code disagree.

Machine-readable datasets

Three files make up the published side of the registry. They are static documents served as-is; a retrieval is an ordinary GET with no key, no quota and no session. Record counts and the schema version are stated so a downstream script can check them before parsing.

Conventions that apply everywhere

• Levels keep the units of the input file and are never converted. The unit string travels with the record.
• Times are numpy.datetime64 in UTC. A file without a declared zone is an error, not a guess.
• Phase is a lag in degrees at the solution's reference time, increasing with delay.
• Durations are given as strings with a unit suffix: "3h", "25h", "72h", "18.6y".
• Nothing mutates in place. Functions that look like modifiers return a new object.

Record

A parsed gauge series. Built by the readers, never by hand in normal use.

time, level, flags

Three arrays of equal length: timestamps, values with NaN for gaps, and uint8 quality flags.

station, units, reference

Strings copied from the file header. reference is the vertical datum as the file names it; the library does not interpret it.

n, missing, step, span

Sample count, count of NaN values, median sampling interval and total span as a duration.

subset(start, end)

A new record over a closed time interval. Both bounds accept ISO 8601 strings.

to_frame()

A pandas frame with a UTC index. Needs the frames extra.

Solution

The result of a fit. Immutable and cheap to keep around; a 68-constituent solution is a few kilobytes.

names

Fitted constituent names in catalogue order, as a tuple.

amplitude(name), phase(name), error(name), snr(name)

Scalar accessors. Unknown names raise rather than returning zero.

table(top=None)

A printable table sorted by amplitude. Terms with a signal-to-noise ratio under 2 get a trailing asterisk.

ref_time, nodal

The phase reference and whether the 18.61-year correction was applied.

coverage, n_used, weights_used

Fraction of the span that entered the fit, number of samples used, and the flag-to-weight mapping that produced them.

to_json(path, include=...), to_frame()

Serialisation. The JSON schema is not frozen before 1.0.

Functions

The same list, machine-readable: /api/reference.json.

Exceptions

Command line

Four subcommands: analyse, reconstruct, qc and catalogue. The flags below belong to analyse; the others share the input and output flags.

tidalcore qc station-7.csv --format csv-flagged --table
tidalcore catalogue --species semidiurnal --table
tidalcore reconstruct station-7.json --from 2026-11-01 --to 2026-11-08 --step 10min

Exit codes are meant for scripts: 0 success, 2 bad usage, 3 the record was too short or too sparse, 4 the input could not be read. Anything else is a bug worth reporting.

Determinism

Two runs on the same input with the same arguments produce bit-identical output; there is no random seed anywhere in the fit and no iteration limit that could stop early. The only module-level state is the constituent catalogue, which is read-only after import, so calling analyse from several threads is safe. It will not be faster, because the work happens inside NumPy.

See also: the tutorial uses most of these calls in order, and the changelog records when each of them last changed shape.