NEWS.md
from and to are now source and target everywhere: the frame arguments of recast_scale(), recast_crosswalk(), recast_to_atoms(), recast_from_atoms(), reconcile_scale(), recast_product() and the navigation functions, the scale arguments and label columns of scale_map(), scale_map_between() and their registry, and the columns of scale_atom_pairs(). recast() takes the scale as scale and the source frame as source. The crosswalk columns n_from and w_from are unchanged. No deprecation aliases.clear_scale_rules(), clear_scale_maps() and clear_scale_distances() take name (and scope where it applies); clear_scale_maps() can now remove named keys..ms_* are now the backend_* functions: backend_of() (errors on an unsupported input), backend_is_lazy(), backend_schema(), backend_lazy(), backend_pull(), backend_restore() and backend_bind_rows(), plus the new backend_scan() and backend_distinct(). They are documented together under ?backend.(frame, unit): attributes (a value with its kind, bounds, unit_of_measure, source and note) and aliases (alternative labels). scale_from_leaftable() takes them as attributes= and aliases=; attach_attributes_scale() and attach_aliases_scale() append rows and never overwrite; scale_attributes() reads them, resolved along the hierarchy when a frame is given; scale_aliases() and scale_match() resolve labels exactly and report ambiguity. convert_scale() converts value columns row by row with a resolved attribute: a property is invertible, a factor is one-way (SCALE_ATTRIBUTE_KINDS). Both tables survive filter_scale(), [, prune_scale() and clustering, which now keep a subclass as well; scale_payload_collapse() is the hook a subclass with a positional payload overrides for prune_scale(). Objects saved by 0.1.x load unchanged.write_scale() and read_scale() exchange a scale as a language-neutral definition: a JSON header with the tables inline, or a <name>.scale/ bundle with Arrow IPC or CSV tables; YAML is accepted as input and as an output option. scale_write_payload(), scale_read_payload() and register_scale_class() let a dimension package store and restore its subclass.register_scale_dir(), list_scale_dirs(), clear_scale_dirs() and scale_catalog() list the definitions shipped by installed packages; read_scale(id) takes a catalogue id.carriers: 71 fuels in group > carrier > fuel from the energypal taxonomy, with the IPCC 2006 default net calorific values and CO2 emission factors as attributes and energypal’s spellings and model commodity codes as aliases (?shipped_scales). The IPCC tables ship as inst/extdata/ipcc2006_fuel_defaults.csv.write_scale_dataset() writes _scales/manifest.json; a legacy manifest.yaml is still read. jsonlite is a new import.vignette("anatomy") (the object, its tables and what the validator guarantees) and vignette("attributes") (attributes, aliases and conversion on the shipped carriers). The article Fuels, regions and months on the package site joins a fuel scale, a GeoScale and a Calendar on one table.write_scale_dataset() now falls back to uncompressed Arrow IPC files, with a warning, when the requested compression codec is unavailable in the installed Arrow build.Calendar and Geoscale classes are subclasses of its NestedScale, so every verb below works on calendars and region hierarchies as well as on any other dimension.NestedScale is a flat table of atoms plus the ordered frames that group them. Build one with scale_from_leaftable(); read it with scale_frames(), scale_units(), scale_key(), scale_leaftable(), scale_weights(), scale_rank() and scale_atom_level().NA). The atoms may be the codes of the finest frame or, as for a calendar, combinations of frames held in the key column.scale_family(), scale_ancestry(), scale_nests(), scale_children(), scale_parents(), scale_descendants() and scale_ancestors() navigate the hierarchy; scale_share() and scale_coverage() report weights.scale_nests(), scale_crosses() and scale_is_uniform() report the structure a pair of frames (or one frame) actually has, computed from the atoms; the order of frames is the convention the direction-dependent rules (share, residuals, reconciliation) follow.filter_scale() (or x[frame, unit]) and prune_scale() subset and collapse a scale, recording the result’s coverage of the original.scale_class(), scale_is() and their product counterparts stand in for the classes, which are not exported; the package’s surface is its functions.recast_scale() converts data between resolutions in either direction with the rules sum, weighted_mean, mean, copy, sd, share and logshare (SCALE_RULES), one per value column if needed. Other columns are kept as identifiers.recast_to_atoms() and recast_from_atoms() are the two halves of the route, and recast between two scales that share atom keys.recast_crosswalk() runs the same engine over a crosswalk built elsewhere, such as timescales’ mapping of one calendar onto another.recast() is the S7 generic that timescales and geoscales extend, so one pipeline can recast time and space in turn.scale_map(x, from, to) returns the crosswalk between two frames of a scale and scale_map_between(from, to) the one between two scales; register_scale_map() / register_scale_map_between() and register_scale_rule() record exact crosswalks and per-column rules. A value column without a rule is an error, never a guess.join_scale() attaches a scale’s labels, coarser frames (attach =), shares and weights to a dataset.scale_from_leaftable(residuals = ), scale_residuals()) aggregate upward but never receive a share when a coarse value is split. reconcile_scale() compares aggregated data with an independent total and can balance the gap.data.frame, tibble, data.table, dtplyr table or arrow table/dataset, and returns the same class. Lazy inputs return a query unless collect = TRUE.NA; missing_sources = "ignore" aggregates whatever is there instead.diagnostics = controls the checks that scan the data (off by default for lazy inputs); batch = and batch_by = process a job in chunks of identifier values.scale_product() combines several scales (time x space, …) into one multi-index without building its atoms. product_size(), product_keys(), product_frames(), product_weights(), product_coverage() and scale_axes() describe it; product_atoms() realises the grid on request.recast_product() converts any subset of the axes in one call, with rules per value column and axis. join_product() and filter_product() work axis by axis.cluster_scale() groups units by their data (k-medoids, hierarchical or k-means) and returns the scale with the clusters as a new frame, so the rest of the package applies to them directly.cluster_contiguous() keeps clusters contiguous in order or in an adjacency graph; cluster_medoids() returns representative units; cluster_sweep() reports cluster quality across a range of k.scale_distance() and its registry (SCALE_DISTANCES, register_scale_distance()) supply level and shape distances.as_scale_array() and as_scale_table() convert between long data and a dense array over a scale or product.write_scale_dataset(), open_scale_dataset() and scale_dataset_info() store data as a partitioned Arrow dataset together with its scales, so it reopens ready to recast.vignette("nestedscales") introduces the representation and the main functions; the package website includes a roadmap of what the package offers and what is planned.NestedScale subclass, as timescales and geoscales do. scale_alias_property() gives an inherited property the dimension’s own name; scale_vocab() puts the dimension’s words in error messages; scale_payload_slice() keeps per-atom data (such as geometry) in step when rows are subset; scale_atom_pairs() lets a dimension generate its atom layer..ms_backend() and the other .ms_* helpers provide the backend handling to packages built on nestedscales.