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.

shift_complete(x)

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_morph_method(recipe, reference = NULL, observed_reference = NULL)

belcher(reference = NULL, methods = NULL, profile = "enhanced", options = NULL)

shift_cmip6(
  model,
  scenarios,
  member = NULL,
  grid = NULL,
  frequency = "mon",
  table = NULL,
  activity = "ScenarioMIP",
  index_nodes = NULL,
  data_node = NULL,
  filters = list()
)

shift_control(
  strict = TRUE,
  allow_partial = FALSE,
  download = c("auto", "always", "never"),
  resume = TRUE,
  overwrite = 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_reference_plan(plan_id, periods)

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

shift_plan(
  request,
  site,
  periods,
  store,
  method,
  control = shift_control(),
  collect = list(),
  download = list(),
  extract = list(),
  morph = list(),
  epw = list()
)

shift_future_epw(
  epw,
  climate,
  periods,
  method,
  dir,
  control = shift_control(),
  ui = shift_ui(),
  store = NULL,
  dry_run = FALSE,
  background = FALSE
)

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_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,
  recipe = epw_morph_recipe("belcher"),
  reference = NULL,
  reference_plan_id = NULL,
  reference_periods = NULL,
  observed_reference = NULL,
  observed_plan_id = NULL,
  observed_periods = NULL,
  strict = TRUE,
  complete_only = TRUE,
  by = c("source_id", "experiment_id", "variant_label", "period"),
  overwrite = FALSE,
  resume = TRUE,
  ui = NULL
)

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

shift_explain(x, ...)

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

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

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

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_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_logs(x, store = NULL, tail = 100L)

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

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_ui(
  progress = c("auto", "dynamic", "log", "none"),
  detail = c("normal", "detail", "debug"),
  motion = c("auto", "full", "reduced", "none"),
  refresh = 0.12,
  heartbeat = 10
)

Arguments

x: A shift stage object.
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_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".
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().
options: For belcher(), an optional named list created by belcher_options(). For shift_request(), provider-specific request options; ESGF recognizes index_node and time_filter_method.
...: Additional provider-specific filters or workflow options.
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.
label: Optional label recorded with collected File records.
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.
recipe: Morphing recipe, usually from epw_morph_recipe().
reference: Optional ShiftReferenceSpec or ShiftClimate stage for change-factor morphing.
observed_reference: Optional plan-backed ShiftReferenceSpec or ShiftClimate stage containing multi-year observed daily weather.
methods: Optional named Belcher step method overrides.
profile: Belcher compatibility profile, "enhanced" by default.
model: CMIP6 source/model IDs.
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 recipe 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.
activity: CMIP6 activity ID. shift_cmip6_scenario() defaults to "ScenarioMIP" and shift_reference_historical() defaults to "CMIP".
index_nodes: Ordered ESGF index nodes used for failover.
data_node: Optional ESGF data node filter.
strict: If TRUE, abort when diagnostics contain errors.
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().
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.
extraction_method: Grid extraction method.
output_layout: Output directory layout.
scenario: CMIP6 scenario experiment IDs, for example "ssp126" or "ssp585".
years: Optional years used to constrain the future request time window.
table_id: One or more CMIP6 table IDs. If NULL, a common atmospheric table is inferred from frequency.
grid_label: Optional CMIP6 grid label.
index_node: Optional ESGF index node.
plan_id: Store extraction plan IDs for manually selected reference climate data.
periods: A period table, usually from epw_morph_periods().
period: Reference period name used when constructing periods from years.
request: A shift_request() object, commonly from shift_cmip6_scenario().
site: A shift_site() object.
store: An EsgStore, store path, or NULL.
method: In task-level planning, a complete shift_morph_method() object. In shift_extract(), the grid extraction method.
control: Workflow controls from shift_control().
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.
morph: Named morph-stage options. Stage option lists are validated and cannot override task-level controls or the method recipe/reference.
climate: A complete future-climate specification from shift_cmip6().
dir: In shift_future_epw(), the user-facing delivery directory. In shift_epw(), an output directory inside the store root; relative paths are resolved under the store root.
ui: Runtime presentation options from shift_ui().
dry_run: If TRUE, return the planned workflow without running it.
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 and return a queued ShiftRun immediately.
match: File metadata fields copied from the future climate stage when resolving an automatic historical reference.
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.
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.
session_label: Optional download session label.
fallback: Extraction fallback policy.
baseline: Optional baseline EPW path or shift_site() object containing epw.
reference_plan_id, reference_periods: Optional store plan IDs and period table for reference climate data.
observed_plan_id, observed_periods: Optional store plan IDs and period table for observed daily weather.
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.
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.
refresh: In shift_ui(), minimum seconds between visual animation frames. In ShiftRun inspectors, whether to reload persisted state first.
run_id: Persisted workflow run ID.
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.
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.
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.

Value

A shift stage object.