Store-native shift workflow API — shift

shift_*() functions provide a stage-oriented workflow facade over EsgQuery, EsgStore, Downloader, and EpwMorpher. Each step returns a small S7 stage object that can be printed, inspected, saved, and passed to the next step without manually passing manifest IDs. Method/model batches can be reopened with shift_batch_get() and inspected with the same status, case, output, diagnostic, and explanation functions. shift_watch() follows all active children; shift_resume() starts saved child plans or resumes interrupted runs independently.

shift_collect(
  x,
  store = NULL,
  fields = "*",
  all = TRUE,
  limit = FALSE,
  label = NULL,
  ui = NULL,
  ...
)

shift_download(
  x,
  downloader = NULL,
  run = TRUE,
  background = FALSE,
  resume = TRUE,
  overwrite = FALSE,
  session_label = NULL,
  ui = NULL,
  ...
)

shift_extract(
  x,
  site = NULL,
  periods = NULL,
  variables = NULL,
  time = NULL,
  filters = list(),
  method = "nearest",
  fallback = c("auto", "error"),
  overwrite = FALSE,
  resume = TRUE,
  ui = NULL
)

shift_morph(
  x,
  baseline = NULL,
  transform,
  reference = NULL,
  observed_reference = NULL,
  strict = TRUE,
  complete_only = TRUE,
  by = c("source_id", "experiment_id", "variant_label", "period"),
  overwrite = FALSE,
  resume = TRUE,
  ui = NULL
)

shift_epw_write(
  x,
  dir = NULL,
  separate = TRUE,
  export_dir = NULL,
  overwrite = FALSE,
  resume = TRUE,
  ui = NULL
)

shift_check(x, strict = FALSE, network = FALSE, ...)

shift_epw_export(
  x,
  dir,
  separate = TRUE,
  overwrite = FALSE,
  resume = TRUE,
  ui = NULL
)

shift_explain(x, ...)

shift_refresh(x)

shift_ids(x, refresh = TRUE)

shift_cases(x, refresh = TRUE)

shift_missing(x)

shift_runs(store = NULL)

shift_run_get(run_id, store = NULL)

shift_result(x, store = NULL)

shift_logs(x, store = NULL, tail = 100L)

shift_files(x)

shift_data(
  x,
  n = 100L,
  variables = NULL,
  case_id = NULL,
  columns = NULL,
  refresh = TRUE
)

shift_diagnostics(x, severity = NULL, refresh = TRUE)

shift_store(x, create = FALSE)

shift_target(x)

shift_coverage(x)

shift_outputs(x, refresh = TRUE)

shift_artifacts(x)

shift_status(x, refresh = TRUE)

shift_resume(x, store = NULL, background = FALSE, ui = shift_ui())

shift_watch(
  x,
  store = NULL,
  follow = TRUE,
  interval = 1,
  events = 10L,
  ui = shift_ui()
)

shift_cancel(x, store = NULL, force = FALSE)

shift_reference_from_plan(
  plan_id,
  periods,
  role = c("model_historical", "observed_reference")
)

historical_reference(years = 1995:2014, period = "reference", ...)

shift_reference_historical(
  periods,
  experiment = "historical",
  activity = "CMIP",
  match = c("source_id", "variant_label", "frequency", "table_id", "grid_label"),
  filters = list(),
  options = list(),
  collect = list(),
  extract = list(fallback = "auto")
)

shift_ui(
  progress = c("auto", "dynamic", "log", "none"),
  detail = c("normal", "detail", "debug"),
  motion = c("auto", "full", "reduced", "none"),
  refresh = 0.12,
  heartbeat = 10
)

shift_complete(x)

shift_run(x, background = FALSE, ui = shift_ui(), ...)

shift_datasets(x, all = TRUE, limit = FALSE, store = NULL, ui = NULL)

shift_request(
  provider = "esgf",
  project = NULL,
  source = NULL,
  experiment = NULL,
  variant = NULL,
  variables = NULL,
  frequency = NULL,
  time = NULL,
  filters = list(),
  options = list(),
  ...
)

shift_site(
  id = NULL,
  lon = NULL,
  lat = NULL,
  label = NULL,
  epw = NULL,
  metadata = list()
)

shift_cmip6(
  model = 3L,
  scenarios,
  member = NULL,
  grid = NULL,
  frequency = NULL,
  table = NULL,
  activity = "ScenarioMIP",
  index_nodes = NULL,
  data_node = NULL,
  filters = list(),
  common = TRUE
)

shift_control(
  strict = TRUE,
  allow_partial = FALSE,
  download = c("auto", "always", "never"),
  resume = TRUE,
  overwrite = FALSE,
  refresh = FALSE,
  extraction_method = "nearest",
  output_layout = c("nested", "flat")
)

shift_cmip6_scenario(
  source,
  scenario,
  member = NULL,
  years = NULL,
  variables = "recommended",
  frequency = "mon",
  activity = "ScenarioMIP",
  table_id = NULL,
  grid_label = NULL,
  data_node = NULL,
  index_node = NULL,
  filters = list(),
  options = list()
)

shift_plan(
  request,
  site,
  periods,
  store,
  transform,
  reference = NULL,
  observed_reference = NULL,
  control = shift_control(),
  collect = list(),
  download = list(),
  extract = list(),
  morph = list(),
  epw = list()
)

shift_epw_future(
  sites,
  climate,
  periods,
  transform = NULL,
  dir,
  reference = NULL,
  observed_reference = NULL,
  control = shift_control(),
  ui = shift_ui(),
  store = NULL,
  dry_run = FALSE,
  background = FALSE,
  methods = NULL,
  calibration = NULL
)

Arguments

x: A shift stage object.
store: An EsgStore, store path, or NULL.
fields: File fields collected from Dataset records. The default requests all fields and lets the result/store layers preserve and validate provider response metadata.
all, limit: Collection controls passed to EsgQuery / EsgResultDataset. If a numeric limit is supplied without explicitly setting all, it caps the Dataset result count. With all = TRUE, a numeric limit retains the low-level meaning of pagination page size.
label: Optional label recorded with collected File records.
ui: Runtime presentation options from shift_ui().
...: Additional provider-specific filters or workflow options.
downloader: Optional Downloader instance.
run: Whether to run queued downloads immediately. Downloading full NetCDF files is optional for the normal workflow because shift_extract() can use OPeNDAP first and only download as a fallback when requested.
background: For shift_download(), whether to run queued downloads in a background job. For task-level run/resume functions, whether to launch a detached Rscript worker. Single plans return a queued ShiftRun; batches return a queued ShiftBatch whose single coordinator shares source reads and starts child workflows. Both modes honor the same source-worker limit from options(epwshiftr.mirai_workers = 4L). Use shift_refresh() or shift_watch() to follow source reading and newly registered child runs.
resume: Whether to reuse complete existing downloads, extraction outputs, morphing results, or EPW outputs.
overwrite: Whether to overwrite existing downloads, extraction outputs, morphing results, or EPW outputs.
session_label: Optional download session label.
site: A shift_site() object.
periods: A period table, usually from epw_morph_periods(). shift_epw_future() and shift_plan() also accept a numeric vector of target years; each year becomes an independently named output period.
variables: Provider-neutral request alias in shift_request(), optional extraction variables in shift_extract(), or optional variables to read in shift_data().
time: Optional request or extraction time filter. Numeric years such as 2060L are expanded to the full UTC year; otherwise supply one or two date-time values accepted by the provider/store.
filters: Provider-specific query filters in shift_request(), or extraction filters in shift_extract().
method: Grid extraction method used by shift_extract().
fallback: Extraction fallback policy.
baseline: Optional baseline EPW path or shift_site() object containing epw.
transform: A reusable specification from monthly_transform(), daily_transform(), or hourly_transform().
reference: Optional ShiftReferenceSpec or ShiftClimate stage containing historical model climate when required by transform.
observed_reference: Optional plan-backed ShiftReferenceSpec or ShiftClimate stage containing observed weather when required by transform.
strict: If TRUE, abort when diagnostics contain errors.
complete_only: Whether shift_morph() should morph only complete extraction plans when a climate stage also contains failed or incomplete plans.
by: Grouping columns used to create morphing cases.
dir: In shift_epw_future(), the user-facing delivery directory. In shift_epw_write(), an output directory inside the store root; relative paths are resolved under the store root.
separate: Whether to create separate output directories per morphing case.
export_dir: Optional directory outside or inside the store where EPW files should also be copied for user-facing delivery.
network: For a reanalysis source, whether to verify the configured token against the provider. The default performs local configuration checks only and never submits a data request.
refresh: In shift_control(), whether to refresh remote catalogs and service addresses instead of resuming persisted inputs. In shift_ui(), minimum seconds between visual animation frames. In ShiftRun inspectors, whether to reload persisted state first.
run_id: Persisted workflow run ID.
tail: Maximum number of trailing execution log lines to return.
n: Maximum number of data rows to read. Use Inf to read all rows.
case_id: Optional morphing case IDs to read from morphed or EPW output stages.
columns: Optional data columns to keep.
severity: Optional diagnostic severities to keep.
create: Whether to create a store when x is a path.
follow: Whether to continue watching until the run reaches a terminal status.
interval: Polling interval in seconds.
events: Number of recent events to display or return.
force: If FALSE, request cancellation at the next safe workflow boundary. If TRUE, persist the request and then terminate the recorded background worker process immediately. For coordinated batches, send an interrupt to the owner so it can close its source workers; cooperative cancellation remains requested if the platform cannot deliver the interrupt.
plan_id: Store extraction plan IDs for manually selected reference climate data.
role: Semantic role of the plan-backed climate. Use "observed_reference" only for an observational extraction plan.
years: Optional years used to constrain the future request time window.
period: Reference period name used when constructing periods from years.
activity: CMIP6 activity ID. shift_cmip6_scenario() defaults to "ScenarioMIP" and shift_reference_historical() defaults to "CMIP".
match: File metadata fields copied from the future climate stage when resolving an automatic historical reference.
options: Provider-specific request options. For ESGF, index_node and time_filter_method are recognized.
collect: Named collection options. Historical reference collection may use fields, all, limit, label, and time; shift_plan() applies the same strict field validation to its collection stage.
extract: Named extraction options. Historical reference extraction may use variables, time, filters, method, and fallback; shift_plan() applies the same strict field validation to its extraction stage.
progress: In shift_ui(), workflow presentation mode: "auto", "dynamic", "log", or "none".
detail: Presentation detail level. "normal" shows task progress, "detail" adds selection, reuse, and fallback decisions, and "debug" also shows full URLs, paths, and low-level transfer context.
motion: Dynamic-terminal animation policy: "auto", "full", "reduced", or "none". This never changes log, JSON, or workflow data.
heartbeat: Minimum seconds between job-liveness updates. Durable writes are always throttled to at least one second. Use progress = "log" for screen readers, reduced-motion use, redirected output, and stable captured logs.
provider: Climate data provider. The first implementation supports "esgf".
project: Optional provider project, for example "CMIP6".
source, experiment, variant, frequency: Provider-neutral request fields. Values must use the selected provider's controlled vocabulary. In shift_cmip6(), an unnamed scalar frequency applies to every transform input, while a named character vector assigns one frequency to every source variable so 3hrPt, 3hr, and day data can be collected together. In shift_reference_historical(), experiment is the historical reference experiment filter. Values are not translated; for ESGF, use exact facet values such as project = "CMIP6" and frequency = "mon".
id: Optional site identifier. If id is an EPW file path and epw is NULL, it is treated as epw.
lon, lat: Optional site longitude and latitude. Missing values are read from the EPW LOCATION header when epw is supplied.
epw: A baseline EPW path, internal EpwFile, or external object inheriting from "Epw" in site and task APIs; in shift_plan(), a named EPW export option list.
metadata: Optional site metadata.
model: CMIP6 model selection. A positive whole number selects that many compatible models after complete File-year coverage is verified, preferring candidates that require fewer source files and then sorting by model/member/grid identity; a character vector selects explicit source/model IDs; NULL selects every compatible model. The default selects three models.
scenarios: CMIP6 future scenario experiment IDs.
member: CMIP6 variant label, for example "r1i1p1f1".
grid: Optional single CMIP6 grid label.
table: Optional CMIP6 table selection. NULL automatically maps each transform input to its native table (including snd to LImon); an unnamed scalar pins every variable to one table; a named character vector overrides individual variables.
index_nodes: Ordered ESGF index nodes used for failover.
data_node: Optional ESGF data node filter.
common: A logical flag for batch candidate selection. TRUE (default) uses the same model/member/grid identities across methods. FALSE selects independently: a numeric model requests that many models per method, NULL keeps all compatible models, and explicit IDs limit the eligible pool. Every explicit model must qualify for at least one method. Different pools are reported in batch diagnostics; their results confound method differences with model selection. File-year coverage is checked before either selection policy is applied.
allow_partial: Whether a task-level run may complete with missing cases.
download: Source-data policy in shift_control() ("auto", "always", or "never"), or a named download-stage option list in shift_plan().
extraction_method: Grid extraction method.
output_layout: Output directory layout.
scenario: CMIP6 scenario experiment IDs, for example "ssp126" or "ssp585".
table_id: One or more CMIP6 table IDs. If NULL, the native table is inferred for each variable's frequency.
grid_label: Optional CMIP6 grid label.
index_node: Optional ESGF index node.
request: A shift_request() object, commonly from shift_cmip6_scenario().
control: Workflow controls from shift_control().
morph: Named morph-stage options. Stage option lists are validated and cannot override task-level controls or the transform/reference inputs.
sites: A shift_site() object or a non-empty list of them, each with a baseline EPW. The constructor derives omitted coordinates and labels from the EPW header. Time zone and elevation remain those of the baseline. Always returns a ShiftBatch, ordered by site ID, with separate output and store directories per location, method, and model. Candidate discovery and bounded native reads are shared; each child owns its persisted outputs. Use declarative historical/reanalysis references. For previously extracted site-specific references, use shift_plan() with the matching site and store.
climate: A complete future-climate specification from shift_cmip6().
dry_run: If TRUE, discover eligible datasets and return a planned batch without extracting climate values or generating EPWs.
methods: One or more unambiguous method keys from weather_transforms(). This high-level form creates a ShiftBatch across every selected method and model.
calibration: Alias for observed_reference in high-level multi-method workflows. It is routed only to methods that accept observational input.

Value

A shift stage object.