Concepts

Short definitions of the vocabulary the rest of these docs use. If you’ve arrived mid-page and a term is unfamiliar, it’s defined here. Terms are grouped by what they describe: the equipment, the data, the rules that turn files into runs, and who can do what.

Equipment and fleet

Instrument

A piece of lab equipment registered in Data Hub, identified by a kebab-case instrument ID (e.g., akta-fplc, bio-rad-cfx96). The ID is permanent, because it becomes the storage key prefix and the identifier used across the system. A human-readable display name sits alongside it.

An instrument has three states. The dashboard groups instruments into a tab per state and shows connection health separately:

See Set up an instrument, Manage instruments, and Retire an instrument.

Instrument type

Separate from the instrument ID. The type tells Data Hub which preprocessor to run on files from this instrument, so it controls what metadata, badges, and reports you get.

Set it from the instrument page: open the three-dot menu, choose Edit, and pick a supported type. An instrument with no matching type still stores and serves raw files. It gets no extracted metadata and no processed artifacts. See Instrument data preprocessing.

Watcher

The data-hub-watcher command-line program that runs on an instrument PC. It monitors a directory, groups new files into runs, uploads them to cloud storage, and reports status to the API. Each instrument can have at most one active watcher at a time.

A watcher is registered with the API and carries one registration ID per environment. Deregistering a watcher is a soft delete: its history stays visible for auditing. See Manage the watcher fleet.

Watcher status

What the Watchers page shows for each watcher, derived from its most recent heartbeat:

An unresponsive watcher keeps its registration and history, so you can read its last events to work out what happened. See Troubleshoot a watcher.

Heartbeat

A status ping the watcher sends to the API every 60 seconds. It carries the watcher version, instrument ID, watch directory, upload mode, activity counters, and uptime, and it drives the Last Heartbeat column and the online health shown on the dashboard. The same tick runs the auto-updater and, in manual mode, polls the upload queue.

Events

A per-watcher log of lifecycle moments and errors: watcher_started, run_reported, file_uploaded, update_succeeded, and error (with a details.kind discriminator), among others. Events are batched and flushed on each heartbeat and are visible on the dashboard, which makes them the primary tool for diagnosing a watcher remotely. See Troubleshoot a watcher.

Environment

Which Data Hub deployment a watcher talks to: staging, production, or preview (a Vercel preview deployment, which needs an explicit API base URL). Staging and production are separate deployments with separate databases, so a single PC keeps an independent registration and local state per environment and can switch between them.

Data

Run

A logical grouping of files produced by one acquisition. The watcher assigns each file a run ID using its configured run detection method, then reports the run to the API. The first file for a run creates it; later files are added incrementally to the same run’s manifest.

Run status

How far a run’s files have got from the instrument to the dashboard. These are the values you can filter by under Add filter on any run list:

File and file category

Every file in a run carries a category, shown as a label in the run’s files table:

• Raw: what the instrument wrote, uploaded unchanged
• Processed: what a preprocessor generated from a raw file, such as a CSV of well values, a contrast-adjusted PNG, or a preview JPG

Both categories download the same way, and file filters on the run page work on this label. See Download files.

Preprocessor

The server-side code that reads a raw file, extracts metadata, and writes processed files. It runs in an AWS Lambda when a file arrives in raw storage, or when you choose Reprocess. Which preprocessor runs depends on the instrument type, and not every type has one. Per-type inputs and outputs are in Instrument data preprocessing.

Run archive

The zip that Download all builds for a run. It covers the run’s active files and respects any file filter you have applied. Large archives build in the background as an archive job, so the first request can return a wait time rather than a file.

Attribution

The record of who ran a run. Use Claim on the run to attribute yourself. Attribution is self-only: you claim or unclaim your own user, and you can’t attribute someone else. Claims drive My runs and the “ran by” filters, and claiming a run subscribes you to its comments. See Claim who ran it.

Turning files into runs

Run detection

The rule that maps a file to a run ID. Two broad strategies:

• Prefix: a regex extracts the run ID from the filename. The default ^([^_]+) takes everything before the first underscore, so RUN001_data.csv → RUN001
• Directory: each subdirectory under the watch directory is its own run, so RUN001/data.csv → RUN001

The full set of presets, and the custom-regex option, is in the Configuration reference.

Stability period

How many seconds a file must stay unchanged (same size and modification time) before the watcher treats it as fully written and eligible for upload. The default is 5 seconds; raise it for instruments that write large files slowly. A file that keeps changing past max_stability_wait_seconds (default 300, or 5 minutes) is abandoned with a stability_timeout error event.

Upload mode

How files get from the instrument to cloud storage:

• auto: files upload immediately after they’re detected and stabilized
• manual: runs are reported to the server, but files aren’t uploaded until approved through the server-side upload queue, which the watcher polls on each heartbeat. Use this when uploads need human approval

Initial scan

What the watcher does with files already sitting in the watch directory the first time an environment is entered. production uploads the existing backlog (full). staging and preview record it as a baseline and skip it (new-only), so test environments aren’t flooded with history. See the Configuration reference.

Dismiss

For instruments in manual upload mode, dismissing a detected file tells the watcher not to upload it. Dismissing differs from deleting: the file never reached Data Hub storage, so there’s nothing to restore. See Manage the watcher fleet.

Soft delete

Data Hub marks things deleted rather than erasing them, so history survives for auditing. Deleting a run hides it from run lists without removing its stored files, and Show deleted runs brings it back into view. Deregistering a watcher keeps its events and heartbeats. Admins can restore a deleted run from the run page.

People and access

Role

Data Hub has two roles, Member and Admin. Members sign in, browse instruments and runs, and read the token audit list. Admins can also confirm and update instruments, create and revoke tokens, and promote or demote other users. Full permission tables are in Security and permissions.

Personal access token

A dhub_-prefixed bearer token that authenticates the watcher, and other API clients, with the Data Hub API. Tokens carry permission scopes and are created and revoked by admins. The plaintext is shown once, at creation. See Issue and revoke tokens.

Scope

A permission string carried by a token, such as runs:read. A token-authenticated request is refused with 403 FORBIDDEN when the token’s scopes don’t cover what the route requires. Dashboard sessions hold every scope, so scope checks only apply to token requests. The scope table is in Security and permissions.