API

The paper-facing workflow uses Collector for catalog-backed local data management and Indexer for unified NetCDF access. Server and Requestor remain compatibility modules but are outside the updated workflow described here.

Collector

Collector keeps the external YAML catalog separate from package releases. Package loading does not contact the network; call load_database! for a local catalog or update_database! to fetch and transactionally replace it.

GriddingMachine.Collector.configure! — Function

Configure the local data root and external catalog without performing network I/O.

GriddingMachine.Collector.load_database! — Function

Load and validate the local catalog, downloading it only when explicitly needed.

GriddingMachine.Collector.update_database! — Function

Download a validated catalog and atomically make it the active in-memory state.

GriddingMachine.Collector.clean_database! — Function

Remove old or all downloaded datasets under the configured isolated data root.

Removing a dataset leaves the directory that held it behind, so the directories that end up empty are removed as well. public itself is kept.

Remove the cached and published files of the given dataset tags.

The directories that end up empty are removed as well; public itself is kept.

GriddingMachine.Collector.sync_database! — Function

Update the catalog and synchronize selected tags (all tags by default).

GriddingMachine.Collector.download_dataset! — Function

Download a NetCDF through mirror fallback and promote it only after integrity checks.

GriddingMachine.Collector.dataset_info — Function

Return a copy of the validated catalog metadata for one dataset tag.

GriddingMachine.Collector.remove_empty_folders! — Function

remove_empty_folders!(target_dir::String)

Recursively remove empty directories inside target_dir, given

target_dir directory to clean up

Traversal is bottom-up, so a parent that becomes empty after its children are removed is removed as well. target_dir itself is kept, and a missing target_dir is a no-op.

A directory that cannot be listed or removed is skipped rather than aborting the walk: this only tidies up, so a permission error or a directory that reappeared is not a failure.

clean_database! deletes files but leaves the directories that held them, so this is offered as a separate step rather than wired into it.

GriddingMachine.Collector.verify_dataset_file — Function

Check an existing file against the optional SIZE and SHA256 catalog fields.

Indexer

GriddingMachine.Indexer.lat_ind — Function

Return the 1-based latitude-cell index for a regular global grid.

GriddingMachine.Indexer.lon_ind — Function

Return the 1-based longitude-cell index, wrapping longitudes outside [-180, 180].

GriddingMachine.Indexer.read_dataset — Function

Read an entire local NetCDF file or a catalog dataset tag.

Read one 1-based cycle from a local NetCDF file or catalog dataset tag.

Read all cycles at the grid cell containing (lat, lon).

Read one cycle at the grid cell containing (lat, lon).

GriddingMachine.Indexer.read_LUT — Function

Compatibility alias retained for code written against GriddingMachine 0.4.

Requestor

GriddingMachine.Requestor.request_site_data — Function

request_site_data(server::String, user::String, tag::String, lat::Number, lon::Number, cycle::Int = 0)

Send a request to the specified server to get the artifact data for the given location, given

server the server URL (e.g., "http://localhost:8000")
user the user name
tag the artifact tag (e.g., "LM4X1Y_V1")
lat the target latitude
lon the target longitude
cycle the data cycle number (0 for all cycles, default is 0)

GriddingMachineServer

GriddingMachineServer.sitedata_json — Function

sitedata_json(arttag::String, lat::Number, lon::Number, cyc::Int; include_std::Bool = true)

Return an HTTP response whose body is the JSON-encoded dataset value at one grid cell, given

arttag the dataset tag (e.g., "CH2X1Y_V2")
lat the target latitude
lon the target longitude
cyc the cycle number (0 reads every cycle)
include_std whether to report the error variable (default true)

Missing values are encoded as -9999 because JSON has no NaN literal; Requestor.request_site_data converts them back to NaN.

When include_std is false the Stdv key is set to null rather than removed, because Requestor.request_site_data reads that key unconditionally.

An unknown tag is reported as a warning without refreshing the catalog. Refreshing on every unknown tag means a single typo against a catalog of over a thousand entries re-downloads the whole catalog before answering; use Collector.update_database! to pick up new publications.

A dataset that cannot be downloaded is reported as a warning carrying a stable Reason. The exception is logged and never returned, because an exhausted mirror list names every url that was tried and a stacktrace names local source paths.

GriddingMachineServer.gmdict_json — Function

gmdict_json(user::String, gmversion::String, year::Int, lat::Number, lon::Number)

Return an HTTP response whose body is the JSON-encoded land parameter dictionary for one grid cell, given

user free-form label echoed back and logged; not an access control mechanism
gmversion land parameter collection, one of SUPPORTED_GM_VERSIONS
year year selecting the time dependent products
lat the target latitude
lon the target longitude

Missing values are encoded as -9999. When a required dataset is absent from the local catalog the response lists the missing tags instead of raising, and no remote catalog refresh is triggered: downloading is the responsibility of Collector.

GriddingMachineServer.weather_json — Function

weather_json(user::String, wdversion::String, year::Int, lat::Number, lon::Number)

Return an HTTP response whose body is the JSON-encoded weather driver series for one grid cell, given

user free-form label echoed back and logged; not an access control mechanism
wdversion weather driver collection, one of SUPPORTED_WD_VERSIONS
year year of the weather series
lat the target latitude
lon the target longitude

Missing values are encoded as -9999. The weather products are large and are commonly absent from a local catalog, so an incomplete catalog produces a response that names every missing tag rather than an exception.

GriddingMachineServer.query_page — Function

query_page()

Return the query page with one <option> per catalog tag.

The options are built on every call so that tags registered after module load are visible.

GriddingMachineServer.setup_url_input_routes! — Function

setup_url_input_routes!(allowed_users::Vector{String} = String[])

Register the query endpoints and the query page.

allowed_users is retained for backward compatibility and is used only for the startup log line. The user query parameter is a free-form label written to the request log, not a credential: it arrives from the query string and any caller can set it to any value. This server is meant for a local or trusted intranet network.

Registered routes:

/sitedata.json one dataset value at one grid cell
/gmdict.json land parameter dictionary at one grid cell
/weather.json weather driver series at one grid cell
/ the query page

lat and lon are required on every query endpoint. Optional settings such as cycle or include_std fall back to a default when they are missing or malformed, but coordinates never do: answering for a different grid cell than the caller asked about would be worse than refusing the request.

GriddingMachineServer.up_servers! — Function

up_servers!(port::Int = 5055)

Start the local servers, given

port Port number to start the server (default 5055)

GriddingMachineServer.down_servers! — Function

down_servers!()

Stop the local servers.