Inspect Future-Weather Transformations

shift_future_epw() is the recommended interface for generating future EPW files. A weather transform selects the scientific calculation, while each run supplies the EPW template, climate data, study periods, references, and output directory. Keeping those responsibilities separate lets the same transform be reused for different sites, GCMs, scenarios, and periods.

Discover Methods

weather_transforms() is the public method catalog. Each row is one selectable combination of transformation scale, scientific method, and hourly reconstruction.

catalog <- weather_transforms()
catalog[, .(
    scale,
    method,
    label,
    reconstruction,
    reconstruction_label,
    statistical_grouping,
    output_frequency,
    status
)]

The catalog and constructors use the same registry. This prevents the documentation from advertising a combination that the executor cannot resolve. The input-contract columns are list columns because different semantic roles can require different variables and source frequencies.

catalog[scale == "daily" & method == "qdm", .(
    required_inputs,
    source_frequencies,
    evidence,
    references
)]

Construct a Transform

Use the constructor that names the scale on which the climate signal is calculated or applied:

original_morphing <- monthly_transform("original_morphing")
bws_btws <- monthly_transform("bws_btws")
daily_power <- daily_transform(
    "epwshiftr",
    reconstruction = "power"
)
daily_btws <- daily_transform(
    "epwshiftr",
    reconstruction = "btws"
)
qdm <- daily_transform("qdm")
hourly_kqdm <- hourly_transform("kernel_qdm")

Only methods with more than one permitted hourly reconstruction accept the reconstruction argument. Method-specific values are supplied through ...; unknown names and invalid values fail before climate data are accessed.

configured <- daily_transform(
    "qdm",
    seasonal_window_days = 31L,
    min_samples = 30L
)

Printing a transform distinguishes five temporal concepts that are easy to confuse:

print(bws_btws)

Concept	Meaning
Transformation scale	Lattice on which the climate signal is estimated or applied
Source frequency	Native frequency required from each climate input
Statistical grouping	Samples combined to estimate a factor or distribution
Hourly reconstruction	Rule that transfers the result to the EPW hourly profile
Output frequency	Frequency of the delivered weather sequence

For example, the BWS+BTWS transform calculates change factors from monthly tas, tasmin, tasmax, rsds, and clt. It uses BTWS to reconstruct hourly dry-bulb temperature and BWS to transform global solar radiation and total sky cover while preserving their physical bounds. Both its transformation scale and its required CMIP6 source frequency are monthly.

Inspect Input Roles

WeatherTransformSpec records required and optional semantic roles. The role contract includes representations, variable alternatives, source frequencies, and calendars.

original_morphing@required_inputs
bws_btws@source_frequencies

The main roles are:

Role	Supplied by
`weather_template`	`epw`
`model_future`	`climate`
`model_historical`	`reference`
`observed_reference`	`observed_reference`

shift_future_epw() checks these roles before collecting or calculating data. Supplying an irrelevant reference is an error, as is omitting a required one. References are execution inputs and never become part of a reusable transform.

Run a Complete Workflow

The original morphing method published by Belcher et al. requires matching historical model data:

Its CMIP6 temperature contract includes monthly tas, tasmax, and tasmin. The mean change comes from tas; the published combined transformation uses the future-minus-historical change in average daily range from tasmax and tasmin, divided by the EPW’s monthly average daily range. The remaining input contract and its humidity alternatives are visible in monthly_transform("original_morphing")@required_inputs.

run <- shift_future_epw(
    epw = system.file(
        "extdata/examples/SGP_Singapore.486980_IWEC.epw",
        package = "epwshiftr"
    ),
    climate = shift_cmip6(
        model = "BCC-CSM2-MR",
        scenarios = c("ssp126", "ssp585")
    ),
    periods = list(`2060s` = 2055:2065),
    transform = monthly_transform("original_morphing"),
    reference = historical_reference(1995:2014),
    dir = "future-epw"
)

shift_status(run)
shift_outputs(run)
shift_diagnostics(run)

The package’s enhanced monthly method accepts a matching historical model reference when one is available and can also use the EPW climatology without one:

run <- shift_future_epw(
    epw = epw,
    climate = shift_cmip6("BCC-CSM2-MR", "ssp585"),
    periods = list(`2080s` = 2075:2085),
    transform = monthly_transform("epwshiftr"),
    reference = NULL,
    dir = "future-epw"
)

Daily bias-adjustment methods such as QDM and ISIMIP3BASD require both historical model and observed reference data. The observed role must point to a plan containing observations; an automatically resolved CMIP6 historical run cannot silently substitute for observations.

reference_periods <- epw_morph_periods(reference = 1995:2014)
historical <- shift_reference_plan(
    historical_plan_id,
    reference_periods
)
observed <- shift_reference_plan(
    observed_plan_id,
    reference_periods,
    role = "observed_reference"
)

run <- shift_future_epw(
    epw = epw,
    climate = future_cmip6,
    periods = c(2050, 2080),
    transform = daily_transform("isimip3basd"),
    reference = historical,
    observed_reference = observed,
    dir = "future-epw"
)

Use dry_run = TRUE to inspect the plan without accessing ESGF:

plan <- shift_future_epw(
    epw = epw,
    climate = shift_cmip6("BCC-CSM2-MR", "ssp585"),
    periods = list(`2060s` = 2055:2065),
    transform = monthly_transform("original_morphing"),
    reference = historical_reference(1995:2014),
    dir = "future-epw",
    dry_run = TRUE
)

shift_explain(plan)
run <- shift_run(plan)

With the default shift_control(resume = TRUE), repeating the same call with the same store and output directory returns the existing durable run without repeating catalog queries, service checks, extraction, morphing, or EPW writing. Set control = shift_control(refresh = TRUE) only when remote CMIP6 catalog and service information must be refreshed deliberately. The refreshed selection is then persisted for later ordinary resumes.

Use EpwMorpher Directly

EpwMorpher is the store-native calculation engine used by shift_morph(). Use it directly when extraction plans already exist and you need separate climate summaries, baseline summaries, preflight diagnostics, factor previews, or control over morph/write reruns.

store <- EsgStore$new("~/cmip6-singapore-store", create = FALSE)

morpher <- epw_morpher(
    store = store,
    epw = epw,
    site_id = "SIN",
    transform = monthly_transform("original_morphing"),
    label = "Singapore baseline"
)

morpher$required_variables()
periods <- epw_morph_periods(`2060s` = 2055:2065)
reference_periods <- epw_morph_periods(reference = 1995:2014)

result <- morpher$workflow(
    plan_id = future_plan_id,
    periods = periods,
    reference_plan_id = historical_plan_id,
    reference_periods = reference_periods,
    by = c("source_id", "experiment_id", "variant_label", "period"),
    strict = TRUE,
    dir = "outputs/future-epw",
    overwrite = FALSE,
    resume = TRUE
)

names(result)

The morpher stores climate summaries, baseline summaries, plans, intermediate hourly weather, diagnostics, and EPW outputs in EsgStore. Existing results are addressed by stable IDs, so a failed or interrupted execution can resume without repeating completed calculations.

Internal Execution Stages

Complete methods execute through seven ordered component responsibilities. The stages are internal; ordinary users select a complete transform instead of assembling them manually.

Stage	Responsibility	Problem solved
`preprocess`	Normalize variables, units, and representations	Gives later calculations a consistent input contract
`calendar`	Map source calendars and annual phase	Prevents implicit Gregorian, no-leap, or 360-day assumptions
`signal`	Estimate or apply the climate-change adjustment	Owns the scientific transformation method
`sequence`	Preserve or construct daily and multi-year ordering	Keeps temporal dependence and realization identity explicit
`hourly`	Reconstruct hourly EPW candidates	Separates daily or monthly signals from hourly profile rules
`physics`	Apply the method’s canonical physical treatment	Centralizes humidity, radiation, wind, pressure, and field bounds
`output`	Produce representative-year or multi-year weather results	Standardizes metadata and handoff to EPW writing

Every built-in complete transform selects one physical treatment internally. Users do not choose backend profiles or physical-policy switches. This keeps each public method definition stable while allowing the common physical layer to be reused by all implementations.

Diagnostics and Provenance

shift_diagnostics() reports input coverage, calendar mapping, fallback use, physical closure, and output status with the case identity that produced each message. shift_explain() reports the selected public transform and its execution inputs; backend, component, and internal recipe keys are not required to configure a normal run.

shift_explain(plan)
shift_diagnostics(run)
shift_data(run, n = 24L)

For incomplete ESGF data or extraction failures, see Troubleshoot ESGF Workflows. For the complete task-oriented workflow, see Create Future EPW Files.