Build a smaller model from a finer one by collapsing its regions onto a coarser geoframe of a geoscales::GeoScale. The result is a model in its own right: it can be interpolated, solved and reported like any other.
Arguments
- object
A
model.- geoscale
A geoscales::GeoScale whose finest geoframe contains the model's regions.
NULL(default) uses the model's own.- level
Name of the target geoframe, coarser than the model's regions.
- clusters
NULL(default) collapses each coarse region to one value. Otherwise a list keyed by process group (seeget_process_groups()) that keeps some of the spread instead – see the section below. A group that is not named is aggregated plainly, so clustering is opted into one family at a time.- max_clusters
A ceiling on the number of clusters per coarse region, the readable alternative to
clusters:max_clusters = 3is "at most three clusters in everylevelregion", for every family.list(EWIN = 3, SUP_BIO = 2)sets it per family, withall = 3as the blanket that a family key overrides. Inside each coarse region the number is chosen by the best average silhouette over2 .. min(max, regions), and falls back to 1 – that region plainly aggregated – where there is nothing to separate: one region, or no candidate parameter that varies. A cap is satisfied by 1, so that is reported rather than refused. Not for a corridor family, whose parts are coarse pairs and not regions: a blanket skips those, and naming one is refused. A family may not appear in bothclustersandmax_clusters.- as
With
clusters, the shape of the result:"clusters"(default) gives one object per family, region variants becomingtechnology@clusterentries;"objects"gives one object per (family x cluster), named with the cluster's label (ECOA_W1), each keeping its own clusters. Same LP either way – what differs is how results are keyed.- name
Name for the aggregated model.
NULL(default) appendslevelto the source model's name.- resolve_conflicts
What to do with a value that has no merged form, such as a lifetime or a levy rate.
FALSE(default) stops, naming the object, the column and the regions that disagree."force"(orTRUE) takes their mean;"drop"leaves the merged value unset, so the parameter falls back to its default rather than to a fabricated number. Both warn and record what was resolved in each object's@misc$aggregation.- dryrun
Return a plan instead of aggregating: the geoframe each region-keyed slot sits at and what will happen to it (rolled up, carried, kept, or refused), the
copycolumns that disagree inside a target region, each corridor's fate, the clustering each family resolves to, the objects whose@geoframewill be cleared, and whether the call is ready. Computed by the same helpers the aggregation itself uses, so the plan and the call cannot disagree about the geography; it collects the refusals that would otherwise be raised one at a time.- verbose
Report what was aggregated, merged and dropped.
- .trade_parts
internal; a named vector mapping trade names to a part label, appended to the merge key so corridors in different parts stay separate instead of collapsing into one merged object.
Value
A model declared over the coarser regions, carrying the pruned
geoscale. With clusters, the grouping is attached and readable with
model_clusters().
Details
Every region-keyed slot is recast. Extensive quantities – capacities, demand, supply availability, import and export limits – are summed over the regions of each parent. Intensive ones – efficiencies, availability factors, costs, weather values – take a weighted mean, so an aggregated value stays within the range of the values it came from. The weight is the object's own size in each region where it carries one; an object that does not – a weather profile has no size – is weighted by the geoscale instead, by area or whatever weight it declares. When the weights of a group are all zero the mean is unweighted, which keeps a group of empty regions at their common value rather than undefined.
Values with no merged form at all, such as a lifetime or a levy rate, are
copied, and a difference between regions stops the aggregation unless
resolve_conflicts says otherwise.
Trade is different: a trade object is one region pair, so corridors that land inside a single parent region become internal and are dropped, and the rest merge – their capacities add, and their loss factors take the capacity-weighted mean. Corridors merge only when they agree on commodity and on cluster structure, so tranched and untranched routes stay apart.
Keeping the spread as clusters
Collapsing a zone's regions to one average technology throws away the
difference between its cheap sites and its dear ones, and a model that can
no longer see that difference builds the average everywhere. clusters
keeps some of it: the fine regions are grouped into k connected clusters
and carried into technology@cluster, one parallel sub-process each, with
its own capacity, availability and costs.
Settings are per technology family, because one k for the model is
meaningless – a coal fleet groups on cost and efficiency, a wind fleet on
resource quality and profile shape:
get_process_groups(mod) # what can be merged
process_cluster_sweep(mod, "ECOA", level = "zone") # where its structure is
aggregate_model_regions(
mod, level = "zone",
clusters = list(ECOA = list(k = 3, features = c("invcost", "eff")),
EWIN = list(k = 8, features = wind_shape)))Each element is a list with k and optionally features; a bare number is
shorthand for list(k = n). A bare number for the whole argument is
accepted only when the model has ONE group. k = "auto" picks the best
average silhouette, which is a rule rather than an answer – sweep and look
instead.
k runs from the number of coarse regions (one cluster each – exactly what
clusters = NULL gives) to the number of fine regions (1:1, nothing
averaged, which on a model whose fine regions already pool inside each
coarse region reproduces the fine objective exactly). Clusters cannot
straddle a coarse region.
Because of that constraint the partition is already independent inside each
coarse region, and k is only a decision about how one global budget is
shared out. max_clusters states the same thing the other way round and is
usually the easier dial: a ceiling per coarse region, with the number below
it chosen per region.
A family that ALREADY has clusters – wind by site grade – keeps them: the
two groupings compose, GOOD in W1 becoming GOOD_W1.
See also
subset_model_regions(), which takes a sub-territory at the
model's own resolution instead of coarsening the whole of it;
get_process_groups(), process_cluster_sweep(), model_clusters().
Examples
repo <- newRepository(
"mini",
newCommodity("COA", unit = "MMBtu"),
newCommodity("ELC", unit = "MWh", timeframe = "ANNUAL"),
newSupply("SUP_COA", commodity = "COA", supply = data.frame(cost = 1)),
newTechnology("ECOA", input = list(comm = "COA"), output = list(comm = "ELC"),
cap2act = 1, invcost = list(invcost = 100),
olife = list(olife = 30)),
newDemand("DEM", commodity = "ELC",
demand = data.frame(region = c("W1", "W2"), year = 2020, demand = 10))
)
mod <- newModel("MINI", data = repo, calendar = calendars$annual,
region = c("W1", "W2"), horizon = horizons$Y2020_2060_by_5)
# roll the two regions up into the zone they share
agg <- aggregate_model_regions(mod, geoscale = topia$geoscales$squares,
level = "zone")
#> Error: 2 of the model's 2 region(s) are not atoms of the geoscale, so their data would be dropped silently: W1, W2. The geoscale must be keyed the way the model is.
get_region(agg)
#> Error: object 'agg' not found
