NEWS.md
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.