@seasketch/geoprocessing/dist/src/metrics/helpers.d.ts

Geoprocessing and reporting framework for SeaSketch 2.0

import { Sketch, SketchCollection, NullSketch, NullSketchCollection, Metric, MetricPack, MetricDimension, MetricProperty, DataClass, MetricIdTypes, GroupMetricSketchAgg, SketchProperties } from "../types/index.js";
/** Properties used in Metric */
export declare const MetricProperties: readonly ["geographyId", "metricId", "classId", "sketchId", "groupId", "value", "extra"];
/**
 * Creates a new metric.  Defaults to ID values of null and then copies in passed metric properties
 * @param metric - partial metric
 * @returns metric
 */
export declare const createMetric: (metric: Partial<Metric>) => Metric;
/**
 * Creates fully defined metrics from partial.  Metric values not provided are initialized to null
 * @param metric - partial metrics
 * @returns metrics
 */
export declare const createMetrics: (metrics: Partial<Metric>[]) => Metric[];
/**
 * Reorders metrics (by mutation) to a consistent key order for readability
 */
export declare const rekeyMetrics: (metrics: Metric[], idOrder?: MetricProperty[]) => Metric[];
/**
 * Converts Metric array to a new MetricPack.
 * Assumes metric dimensions are consistent for each element in the array, and null values are used
 */
export declare const packMetrics: (inMetrics: Metric[]) => MetricPack;
/**
 * Converts MetricPack to a new Metric array.
 * @param metricPack
 * @returns
 */
export declare const unpackMetrics: (inMetricPack: MetricPack) => Metric[];
/**
 * Checks if object is a MetricPack.  Any code inside a block guarded by a conditional call to this function will have type narrowed to MetricPack
 */
export declare const isMetricPack: (json: any) => json is MetricPack;
/**
 * Checks if object is a Metric array and returns narrowed type
 */
export declare const isMetricArray: (metrics: any) => metrics is Metric[];
/**
 * Checks if object is a Metric and returns narrowed type
 */
export declare const isMetric: (metric: any) => metric is Metric;
/**
 * Sorts metrics to a consistent order for readability
 * Defaults to [metricId, classId, sketchId]
 */
export declare const sortMetrics: (metrics: Metric[], sortIds?: MetricDimension[]) => {
    value: number;
    classId: string | null;
    metricId: string;
    geographyId: string | null;
    sketchId: string | null;
    groupId: string | null;
    extra?: Record<string, import("../types/base.js").JSONValue> | undefined;
}[];
/**
 * Sorts metrics by ID given a user-defined metric dimension (sortId) and array of ID
 * values in the order they should be sorted
 * Useful for applying a "display order" to metrics
 * Example - sortId = classId, displayOrder = ['sand','gravel','coral']
 * @param metrics
 * @param sortId
 * @param displayOrder
 * @returns new array of sorted metrics
 */
export declare const sortMetricsDisplayOrder: (metrics: Metric[], sortId: MetricDimension | undefined, displayOrder: string[]) => {
    value: number;
    classId: string | null;
    metricId: string;
    geographyId: string | null;
    sketchId: string | null;
    groupId: string | null;
    extra?: Record<string, import("../types/base.js").JSONValue> | undefined;
}[];
/**
 * Returns new sketchMetrics array with first sketchMetric matched set with new value.
 * If no match, returns copy of sketchMetrics.  Does not mutate array in place.
 */
export declare const findAndUpdateMetricValue: <T extends Metric>(sketchMetrics: T[], matcher: (sk: T) => boolean, value: number) => T[];
/**
 * Returns the first metric that returns true for metricFilter
 * @returns
 */
export declare const firstMatchingMetric: <M extends Metric>(metrics: M[], metricFilter: (metric: M) => boolean) => M;
/**
 * Given sketch(es), returns ID(s)
 */
export declare const sketchToId: (sketch: Sketch | NullSketch | Sketch[] | NullSketch[]) => string | any[];
/**
 * Returns metrics with matching sketchId (can be an array of sketchids)
 */
export declare const metricsSketchIds: <M extends Metric>(metrics: M[]) => string[];
/**
 * Returns metrics with matching sketchId (can be an array of sketchids)
 */
export declare const metricsWithSketchId: <M extends Metric>(metrics: M[], sketchId: string | string[]) => M[];
/**
 * Returns metrics with matching sketchId (can be an array of sketchids)
 */
export declare const metricsWithClassId: <M extends Metric>(metrics: M[], classId: string | string[]) => M[];
/**
 * Returns metrics for given sketch (can be an array of sketches)
 */
export declare const metricsForSketch: <M extends Metric>(metrics: M[], sketch: Sketch | NullSketch | Sketch[] | NullSketch[]) => M[];
/**
 * Matches numerator metrics with denominator metrics and divides their value,
 * returning a new array of percent metrics.
 * Matches on the optional idProperty given, otherwise defaulting to classId
 * Deep copies and maintains all other properties from the numerator metric
 * If denominator metric has value of 0, returns NaN
 *   NaN allows downstream consumers to understand this isn't just any 0.
 *   It's an opportunity to tell the user that no matter where they put their sketch, there is no way for the value to be more than zero.
 *   For example, the ClassTable component looks for `NaN` metric values and will automatically display 0%,
 *   along with an informative popover explaining that no data class features are within the current geography.
 * @param numerators array of metrics, to be used as numerators (often sketch metrics)
 * @param denominators array of metrics, to be used as denominators (often planning region metrics)
 * @param metricIdOverride optional metricId value to assign to outputted metrics
 * @param idProperty optional id property to match metric with total metric, defaults to classId
 * @returns Metric[] of percent values or NaN if denominator was 0
 */
export declare const toPercentMetric: (numerators: Metric[], denominators: Metric[], options?: {
    metricIdOverride?: string;
    idProperty?: string;
    debug?: boolean;
}) => Metric[];
/**
 * Recursively groups metrics by ID in order of ids specified to create arbitrary nested hierarchy for fast lookup.
 * Caller responsible for all metrics having the ID properties defined
 * If an id property is not defined on a metric, then 'undefined' will be used for the key
 */
export declare const nestMetrics: (metrics: Metric[], ids: MetricDimension[]) => Record<string, any>;
/**
 * Flattens class sketch metrics into array of objects, one for each sketch,
 * where each object contains sketch id, sketch name, and all metric values for each class
 * @param metrics List of metrics, expects one metric per sketch and class combination
 * @param classes Data classes represented in metrics
 * @param sketchProperties SketchProperties of sketches represented in metrics
 * @param sortFn Function to sort class configs using Array.sort (defaults to alphabetical by display name)
 * @returns An array of objects with flattened sketch metrics
 */
export declare const flattenBySketchAllClass: (metrics: Metric[], classes: DataClass[], sketchProperties: SketchProperties[], sortFn?: (a: DataClass, b: DataClass) => number) => Record<string, string | number>[];
/**
 * Aggregates metrics by group
 * @param collection sketch collection metrics are for
 * @param groupMetrics metrics with assigned groupId (except group total metric) and sketchIds for collection
 * @param totalMetrics totals by class
 * @returns one aggregate object for every groupId present in metrics.  Each object includes:
 * [numSketches] - count of child sketches in the group
 * [classId] - a percValue for each classId present in metrics for group
 * [value] - sum of value across all classIds present in metrics for group
 * [percValue] - given sum value across all classIds, contains ratio of total sum across all class IDs
 */
export declare const flattenByGroupAllClass: (collection: SketchCollection | NullSketchCollection, groupMetrics: Metric[], totalMetrics: Metric[]) => {
    value: number;
    groupId: string;
    percValue: number;
}[];
/**
 * Flattens group class metrics, one for each group and sketch.
 * Each object includes the percValue for each class, and the total percValue with classes combined
 * groupId, sketchId, class1, class2, ..., total
 * @param groupMetrics - group metric data
 * @param totalValue - total value with classes combined
 * @param classes - class config
 */
export declare const flattenByGroupSketchAllClass: (sketches: Sketch[] | NullSketch[], groupMetrics: Metric[], totals: Metric[]) => GroupMetricSketchAgg[];
/**
 * Given sketch collection, returns IDs of sketches in the collection
 * @deprecated
 */
export declare const getSketchCollectionChildIds: (collection: SketchCollection | NullSketchCollection) => any[];
/**
 * Returns an array of shorthand sketches (id + name) given a Sketch or SketchCollection.
 * Includes a shorthand of parent collection also
 * @deprecated
 */
export declare const toShortSketches: (input: Sketch | SketchCollection | NullSketch | NullSketchCollection) => {
    id: string;
    name: string;
}[];
/**
 * Returns one aggregate object for every sketch ID present in metrics,
 * with additional property for each unique value for idProperty present for sketch.
 * Example - idProperty of 'classId', and two classes are present in metrics of 'classA', and 'classB'
 * then each flattened object will have two extra properties per sketch, .classA and .classB, each with the first metric value for that sketch/idProperty found
 * @param metrics - metrics with assigned sketch
 * @param extraIdProperty - optional second id property to cross flatten with idProperty.  Properties will be keyed extraId_idProperty
 * @deprecated
 */
export declare const flattenSketchAllId: (metrics: Metric[], idProperty: MetricDimension, options?: {
    extraIdProperty?: MetricDimension;
}) => Record<MetricProperty | string, MetricIdTypes>[];