canVODpy¶

canVODpy computes vegetation optical depth from GNSS signals received below a forest canopy and in the open, and keeps the data and results in versioned stores. These are the words the project uses; use them in code, docs, issues and messages.

Science¶

GNSS-T (GNSS transmissometry): Estimating how much vegetation weakens satellite navigation signals, by comparing the same signal received below the canopy and in the open. Avoid: GNSS-IR, GNSS reflectometry (different methods)

VOD (vegetation optical depth): The attenuation of a microwave signal by vegetation along its path, normalized to a vertical path; it tracks vegetation water content and biomass. Avoid: optical depth, tau (alone)

Transmissivity: The fraction of a signal's power that passes through the canopy: the canopy signal strength relative to the reference signal strength. Avoid: transmittance

SNR: The signal strength the receiver reports for a signal, in dB-Hz; the observable VOD is computed from. Avoid: C/N0, CN0, signal power

Polar angle: The angle between the zenith and the direction to a satellite, seen from the receiver (0 overhead, 90 degrees at the horizon). Avoid: zenith angle, elevation (its complement)

Azimuth: The direction to a satellite in the horizontal plane, clockwise from north.

Signal ID (SID): One signal of one satellite: satellite, frequency band and tracking code, e.g. G01|L1|C. Avoid: signal, channel, observable

Epoch: The time of an observation, always GPS time. Avoid: timestamp, time step

Ephemeris: The orbit (and clock) of the satellites, from agency products or from the receiver's broadcast navigation data; gives each epoch's polar angle and azimuth. Avoid: aux data, orbit file (for the data itself)

Hemisphere grid: A division of the sky seen from the receiver into cells, used to aggregate observations and VOD by direction. Avoid: sky map, mesh

Sites and receivers¶

Site: A place with at least one canopy receiver and one reference receiver, processed together into one GNSS store and one VOD store. Avoid: station, location

Canopy receiver: A receiver below the vegetation. Avoid: forest receiver, below-canopy receiver

Reference receiver: A receiver with an open view of the sky near the canopy receiver. Avoid: sky receiver, open-sky receiver, clear-sky receiver

VOD analysis: One pairing of a canopy receiver with a reference receiver for which VOD is computed. Avoid: pair, combination

Receiver-day: One receiver's files of one GPS day; the smallest piece of a run that succeeds or fails on its own. Avoid: day file

Unit of days: The days a run writes together and commits once to the store. The run sizes it from its memory budget, at most 31 days; a run of one new day is a unit of one day. A day in a unit still fails alone. Avoid: batch, wave

Files¶

Raw archive: Where a site's receiver files are kept before canvodpy reads them; the source every store is rebuilt from. Its files may have been prepared on the way (compressed, renamed, reduced to some observables), but are not yet read by canvodpy. Avoid: input folder, data share

Completeness: The share of the files a receiver-day should have, by its cadence and file length, that are in the raw archive. Avoid: coverage, availability

canVOD file name: The file name convention that states a file's receiver identity, start time, length, sampling and type, e.g. ROSA01TUW_R_20250010000_15M_05S_AA.rnx. Avoid: canonical name (in user-facing text), standard name

Receiver identity: The first nine characters of a canVOD file name: site, receiver role, receiver number and agency. Avoid: station ID, marker name

File type: The TYPE field at the end of a canVOD file name, naming the file's format (e.g. rnx, sbf). Avoid: extension

Naming recipe: A description of how a receiver's own file names translate to canVOD file names, for files not named by the convention. Avoid: name mapping, pattern

File index: The names of the files a run found in each folder of a receiver directory, kept so a run need not list folders that hold none of the days it processes. Avoid: file cache, file list

Reader format: The setting that tells a run which reader reads a receiver's files. Avoid: file format (for the setting)

Test data: The full set of receiver and auxiliary files the tests run on. Avoid: demo data

Setting profile: A named settings folder that a reference run uses on the test data. Avoid: test config, fixture settings

Reference store: A GNSS or VOD store built from the test data with a setting profile, which new code must reproduce within the comparison tolerances. Avoid: golden store, baseline store

Demo data: The small, published set of files the demo notebooks work with: part of one day of the test data, plus reference stores built from it. Avoid: test data, example data, sample data

Processing and storage¶

Run: One processing of a site's receiver-days, started from the command line, Python or a scheduler such as Airflow; all behave the same. Avoid: job, pipeline execution

Run history: The record canvodpy keeps on one machine of every run: its settings, progress, timings, machine and problems. Avoid: journal, run log, database

Preprocessing: Optional changes to the observations before they are stored (temporal aggregation, grid assignment), applied only when the settings ask for them. Avoid: filtering, cleaning

Store: An Icechunk repository holding one kind of a site's data: a GNSS store, a VOD store, or a store of an extension (geodesy, rollup, statistics). Avoid: repo, database

Store name: The name of a store's folder: its kind (gnss, vod, geodesy), or the kind, - and a suffix for a second store of that kind (vod-recompute). The store id is the site name and the store name. Avoid: store directory name, rinex (the GNSS store's name before v1.0.0)

GNSS store: A site's versioned store of the observations of all its receivers. Avoid: RINEX store, observation store

VOD store: A site's versioned store of the VOD of all its VOD analyses.

Derived store: A store computed from other stores (VOD, geodesy, rollup, statistics); it can be rebuilt from them. Avoid: secondary store, product store

Geodesy store: A site's versioned store of the geodetic products computed from its GNSS data (reflector height, multipath).

Rollup store: A site's store of VOD summed per hemisphere cell and time bin, from which the aggregate over any time window is computed quickly. Avoid: cube, rolled store, summary store

Rollup level: The length of a rollup store's time bins (hour, day, week).

Statistics store: A site's store of running statistics per hemisphere cell and signal, updated with each new day without reading the history again. Avoid: accumulator store

Group: One receiver's data (in the GNSS store) or one VOD analysis's results (in the VOD store). Avoid: table, dataset (for the stored unit)

Log book: The record a store keeps of what was written to each group: source files, their hashes, and the preprocessing applied. Avoid: metadata table, registry

Day block: The part of a group that holds one receiver-day (or one day of a VOD analysis): every possible epoch of that day at its cadence, with or without data, padded with empty epochs to whole chunks. Avoid: day chunk, partition

Cadence: The time between the epochs a day block holds: the sampling interval of the day's files, or the aggregation interval when aggregation is set. Avoid: resolution, frequency

Snapshot: One committed state of a store, which can be read again later. Avoid: version (for a store state), checkpoint

Provisional branch: A branch of a store that holds the most recent days processed with a quicker orbit product than the store's own, until those days are processed again with the store's product; the main branch never holds them. Avoid: rapid branch, test branch

Repository metadata (Icechunk's term): The description of a store that belongs to no snapshot and no branch: who made it, what it holds, where, under which license. Some of its fields never change; the others change only by amendment. Avoid: global attributes, store identity

Commit metadata (Icechunk's term): What one commit records about how it was made: software versions, environment and settings of the run that wrote it. Avoid: history, provenance (the log books hold provenance)

Snapshot summary: The description of what one snapshot holds (time coverage, receivers, counts), written in the same commit as the data it describes. Avoid: statistics, store state

Fixed field: A field of the repository metadata that never changes once the store exists, such as its id or creation date. Avoid: immutable field

Content settings: The settings that shape a store's data, such as the signals kept, the preprocessing, the orbit product and the chunking: set by whoever creates the store, fixed with it, and the same for every run that writes to it. Avoid: fingerprint, store config

Amendable field: A field of the repository metadata that changes only by amendment, such as the creator's email or the license.

Amendment: A recorded change to an amendable field: old and new value, reason, who and when. Avoid: edit, update (for repository metadata)

Metadata rule: A rule a standard sets for a metadata field, such as the license being an SPDX identifier. New metadata that breaks one is refused; a store that already breaks one still opens, with a warning, until an amendment fixes the field, or, for a value computed from the data, the next commit. Avoid: constraint, policy

Catalog: The STAC description of all stores under one data root, kept beside them: one item per store, grouped into GNSS observations and VOD. Avoid: inventory, index

Release: A named, fixed state of all stores under a data root: a tag in each store plus a catalog that pins each store's snapshot. Avoid: version (for a store state), export

Plugin: An installed package that adds a reader or a VOD calculator to runs. Avoid: extension (canvodpy-extensions are separate packages)