@sdeverywhere/check-core 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-declare type SourceName = string;
-declare type VarId = string;
-declare type DatasetKey = string;
-declare type Dataset = Map<number, number>;
-declare type DatasetMap = Map<DatasetKey, Dataset>;
+type SourceName = string;
+type VarId = string;
+type DatasetKey = string;
+type Dataset = Map<number, number>;
+type DatasetMap = Map<DatasetKey, Dataset>;
 
 /** A unique identifier for the scenario, derived from its input settings. */
-declare type ScenarioSpecUid = string;
-declare type InputPosition = 'at-default' | 'at-minimum' | 'at-maximum';
+type ScenarioSpecUid = string;
+type InputPosition = 'at-default' | 'at-minimum' | 'at-maximum';
 interface PositionSetting {
     kind: 'position';
     inputVarId: VarId;
@@ -17,7 +17,7 @@ interface ValueSetting {
     inputVarId: VarId;
     value: number;
 }
-declare type InputSetting = PositionSetting | ValueSetting;
+type InputSetting = PositionSetting | ValueSetting;
 interface InputSettingsSpec {
     kind: 'input-settings';
     uid: ScenarioSpecUid;
@@ -28,7 +28,7 @@ interface AllInputsSpec {
     uid: ScenarioSpecUid;
     position: InputPosition;
 }
-declare type ScenarioSpec = InputSettingsSpec | AllInputsSpec;
+type ScenarioSpec = InputSettingsSpec | AllInputsSpec;
 
 interface DatasetsResult {
     /**
@@ -56,7 +56,7 @@ interface RelatedItem {
     locationPath: string[];
 }
 /** A unique, stable input identifier. */
-declare type InputId = string;
+type InputId = string;
 /**
  * Holds information about an input variable used in the model.
  */
@@ -145,6 +145,12 @@ interface ImplVar {
     varType: string;
 }
 
+/** The human-readable name for a group of inputs. */
+type InputGroupName = string;
+/** The alias name for an input. */
+type InputAliasName = string;
+/** The human-readable name for a group of dataset. */
+type DatasetGroupName = string;
 /**
  * Includes the properties needed to display a legend item in the UI.
  */
@@ -165,7 +171,8 @@ interface LinkItem {
     /** The link content (a URL or text). */
     content: string;
 }
-declare type BundleGraphId = string;
+/** The identifier for a bundle-specific graph. */
+type BundleGraphId = string;
 /**
  * Describes a dataset in a bundle-specific graph.
  */
@@ -225,11 +232,11 @@ interface ModelSpec {
     /** The map of all variables (both internal and exported) in this version of the model. */
     implVars: Map<DatasetKey, ImplVar>;
     /** The custom input variable aliases defined for this model. */
-    inputAliases?: Map<string, VarId>;
+    inputAliases?: Map<InputAliasName, VarId>;
     /** The custom input variable groups defined for this model. */
-    inputGroups?: Map<string, InputVar[]>;
+    inputGroups?: Map<InputGroupName, InputVar[]>;
     /** The custom dataset (output variable) groups defined for this model. */
-    datasetGroups?: Map<string, DatasetKey[]>;
+    datasetGroups?: Map<DatasetGroupName, DatasetKey[]>;
     /** The start time (year) for the model. */
     startTime?: number;
     /** The end time (year) for the model. */
@@ -289,7 +296,7 @@ interface LoadedBundle {
     model: BundleModel;
 }
 
-declare type CheckDataRequestKey = string;
+type CheckDataRequestKey = string;
 /**
  * Coordinates on-demand loading of data used to display a graph representation
  * of a check/predicate.
@@ -302,17 +309,17 @@ declare class CheckDataCoordinator {
     cancelRequest(key: CheckDataRequestKey): void;
 }
 
-declare type CheckPredicateOp = 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'approx';
+type CheckPredicateOp = 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'approx';
 
-declare type CheckPredicateTimeSingle = number;
-declare type CheckPredicateTimeRange = [number, number];
+type CheckPredicateTimeSingle = number;
+type CheckPredicateTimeRange = [number, number];
 interface CheckPredicateTimeOptions {
     after_excl?: number;
     after_incl?: number;
     before_excl?: number;
     before_incl?: number;
 }
-declare type CheckPredicateTimeSpec = CheckPredicateTimeSingle | CheckPredicateTimeRange | CheckPredicateTimeOptions;
+type CheckPredicateTimeSpec = CheckPredicateTimeSingle | CheckPredicateTimeRange | CheckPredicateTimeOptions;
 
 interface CheckResultErrorInfo {
     kind: 'unknown-dataset' | 'unknown-input' | 'unknown-input-group' | 'empty-input-group';
@@ -328,7 +335,7 @@ interface CheckResult {
     errorInfo?: CheckResultErrorInfo;
 }
 
-declare type CheckDatasetError = 'no-matches-for-dataset' | 'no-matches-for-group' | 'no-matches-for-type';
+type CheckDatasetError = 'no-matches-for-dataset' | 'no-matches-for-group' | 'no-matches-for-type';
 interface CheckDataset {
     /** The key for the matched dataset; can be undefined if no dataset matched. */
     datasetKey?: DatasetKey;
@@ -367,7 +374,7 @@ interface CheckScenario {
 /**
  * The key type for data references (in the form `<ScenarioUid::DatasetKey>`).
  */
-declare type CheckDataRefKey = string;
+type CheckDataRefKey = string;
 /**
  * The scenario and dataset referenced by a particular predicate (for cases
  * where the check is against another dataset rather than a constant value).
@@ -381,9 +388,9 @@ interface CheckDataRef {
     dataset: CheckDataset;
 }
 
-declare type CheckKey = number;
+type CheckKey = number;
 
-declare type CheckStatus = 'passed' | 'failed' | 'error';
+type CheckStatus = 'passed' | 'failed' | 'error';
 interface CheckPredicateOpConstantRef {
     kind: 'constant';
     value: number;
@@ -392,7 +399,7 @@ interface CheckPredicateOpDataRef {
     kind: 'data';
     dataRef: CheckDataRef;
 }
-declare type CheckPredicateOpRef = CheckPredicateOpConstantRef | CheckPredicateOpDataRef;
+type CheckPredicateOpRef = CheckPredicateOpConstantRef | CheckPredicateOpDataRef;
 interface CheckPredicateReport {
     checkKey: CheckKey;
     result: CheckResult;
@@ -423,7 +430,7 @@ interface CheckGroupReport {
 interface CheckReport {
     groups: CheckGroupReport[];
 }
-declare type StyleFunc = (s: string) => string;
+type StyleFunc = (s: string) => string;
 /**
  * Return a string representation of the given scenario.
  *
@@ -492,11 +499,26 @@ declare function checkSummaryFromReport(checkReport: CheckReport): CheckSummary;
  */
 declare function checkReportFromSummary(checkConfig: CheckConfig, checkSummary: CheckSummary): CheckReport | undefined;
 
-declare type ComparisonScenarioId = string;
-declare type ComparisonScenarioTitle = string;
-declare type ComparisonScenarioSubtitle = string;
-declare type ComparisonScenarioInputName = string;
-declare type ComparisonScenarioInputPosition = 'default' | 'min' | 'max';
+type ComparisonDatasetName = string;
+type ComparisonDatasetSource = string;
+/**
+ * Specifies a dataset (variable) used for comparison.
+ */
+interface ComparisonDatasetSpec {
+    kind: 'dataset';
+    /** The name of the dataset (variable). */
+    name: ComparisonDatasetName;
+    /**
+     * The source of the dataset, if it is from an external data file.  If
+     * undefined, the dataset is assumed to be a model output.
+     */
+    source?: ComparisonDatasetSource;
+}
+type ComparisonScenarioId = string;
+type ComparisonScenarioTitle = string;
+type ComparisonScenarioSubtitle = string;
+type ComparisonScenarioInputName = string;
+type ComparisonScenarioInputPosition = 'default' | 'min' | 'max';
 /**
  * Specifies an input that is set to a specific position (default / min / max).
  */
@@ -521,7 +543,7 @@ interface ComparisonScenarioInputAtValueSpec {
  * A single input setting for a scenario.  An input can be set to a specific number value,
  * or it can be set to a "position" (default / min / max).
  */
-declare type ComparisonScenarioInputSpec = ComparisonScenarioInputAtPositionSpec | ComparisonScenarioInputAtValueSpec;
+type ComparisonScenarioInputSpec = ComparisonScenarioInputAtPositionSpec | ComparisonScenarioInputAtValueSpec;
 /**
  * Specifies a single scenario that sets one or more inputs to a value/position.
  */
@@ -536,6 +558,23 @@ interface ComparisonScenarioWithInputsSpec {
     /** The input settings for this scenario. */
     inputs: ComparisonScenarioInputSpec[];
 }
+/**
+ * Specifies a single scenario that configures inputs differently for the two
+ * model instances.
+ */
+interface ComparisonScenarioWithDistinctInputsSpec {
+    kind: 'scenario-with-distinct-inputs';
+    /** The unique identifier for the scenario. */
+    id?: ComparisonScenarioId;
+    /** The title of the scenario. */
+    title?: ComparisonScenarioTitle;
+    /** The subtitle of the scenario. */
+    subtitle?: ComparisonScenarioSubtitle;
+    /** The input settings for this scenario when run with the "left" model. */
+    inputsL: ComparisonScenarioInputSpec[];
+    /** The input settings for this scenario when run with the "right" model. */
+    inputsR: ComparisonScenarioInputSpec[];
+}
 /**
  * Specifies a single scenario that sets all available inputs to position.
  */
@@ -564,7 +603,7 @@ interface ComparisonScenarioPresetMatrixSpec {
  * A definition of input scenario(s).  A scenario can set one input to a value/position, or it
  * can set multiple inputs to particular values/positions.
  */
-declare type ComparisonScenarioSpec = ComparisonScenarioWithInputsSpec | ComparisonScenarioWithAllInputsSpec | ComparisonScenarioPresetMatrixSpec;
+type ComparisonScenarioSpec = ComparisonScenarioWithInputsSpec | ComparisonScenarioWithDistinctInputsSpec | ComparisonScenarioWithAllInputsSpec | ComparisonScenarioPresetMatrixSpec;
 /** A reference to a scenario definition. */
 interface ComparisonScenarioRefSpec {
     kind: 'scenario-ref';
@@ -575,8 +614,8 @@ interface ComparisonScenarioRefSpec {
     /** The optional subtitle that is used instead of the referenced scenario's subtitle. */
     subtitle?: ComparisonScenarioSubtitle;
 }
-declare type ComparisonScenarioGroupId = string;
-declare type ComparisonScenarioGroupTitle = string;
+type ComparisonScenarioGroupId = string;
+type ComparisonScenarioGroupTitle = string;
 /**
  * A definition of a group of input scenarios.  Multiple scenarios can be grouped together under a single name, and
  * can later be referenced by group ID in a view definition.
@@ -596,44 +635,101 @@ interface ComparisonScenarioGroupRefSpec {
     /** The ID of the scenario group that is referenced. */
     groupId: ComparisonScenarioGroupId;
 }
-declare type ComparisonViewTitle = string;
-declare type ComparisonViewSubtitle = string;
-declare type ComparisonViewGraphId = string;
+type ComparisonGraphId = string;
 /**
  * Specifies a list of graphs to be shown in a view.
  */
-interface ComparisonViewGraphsArraySpec {
+interface ComparisonGraphsArraySpec {
     kind: 'graphs-array';
     /** The array of IDs for graphs to show. */
-    graphIds: ComparisonViewGraphId[];
+    graphIds: ComparisonGraphId[];
 }
 /**
  * Specifies a preset list of graphs to be shown in a view.
  */
-interface ComparisonViewGraphsPresetSpec {
+interface ComparisonGraphsPresetSpec {
     kind: 'graphs-preset';
     /** The preset (currently only "all" is supported, which shows all available graphs). */
     preset: 'all';
 }
+type ComparisonGraphGroupId = string;
+/**
+ * A definition of a group of graphs to be shown in a view.  Multiple graphs can be grouped together
+ * under a single ID, and can later be referenced by group ID in a view definition.
+ */
+interface ComparisonGraphGroupSpec {
+    kind: 'graph-group';
+    /** The unique identifier for the group. */
+    id: ComparisonGraphGroupId;
+    /** The graphs that are included in this group. */
+    graphIds: ComparisonGraphId[];
+}
+/** A reference to a graph group definition. */
+interface ComparisonGraphGroupRefSpec {
+    kind: 'graph-group-ref';
+    /** The ID of the graph group that is referenced. */
+    groupId: ComparisonGraphGroupId;
+}
+type ComparisonViewTitle = string;
+type ComparisonViewSubtitle = string;
+type ComparisonViewRowTitle = string;
+type ComparisonViewRowSubtitle = string;
+type ComparisonViewItemTitle = string;
+type ComparisonViewItemSubtitle = string;
+type ComparisonViewGraphOrder = 'default' | 'grouped-by-diffs';
+/**
+ * Specifies a single comparison box to be shown in a view.
+ */
+interface ComparisonViewBoxSpec {
+    kind: 'view-box';
+    /** The title of the box. */
+    title: ComparisonViewItemTitle;
+    /** The subtitle of the box. */
+    subtitle?: ComparisonViewItemSubtitle;
+    /** The dataset shown in this comparison box. */
+    dataset: ComparisonDatasetSpec;
+    /** The scenario shown in this comparison box. */
+    scenarioId: ComparisonScenarioId;
+}
+/**
+ * Specifies a row of comparison boxes to be shown in a view.
+ */
+interface ComparisonViewRowSpec {
+    kind: 'view-row';
+    /** The title of the row. */
+    title: ComparisonViewRowTitle;
+    /** The subtitle of the row. */
+    subtitle?: ComparisonViewRowSubtitle;
+    /** The array of boxes to be shown in the row. */
+    boxes: ComparisonViewBoxSpec[];
+}
 /**
  * Specifies a set of graphs to be shown in a view.
  */
-declare type ComparisonViewGraphsSpec = ComparisonViewGraphsArraySpec | ComparisonViewGraphsPresetSpec;
+type ComparisonViewGraphsSpec = ComparisonGraphsPresetSpec | ComparisonGraphsArraySpec | ComparisonGraphGroupRefSpec;
 /**
- * A definition of a view.  A view presents a set of graphs for a single input scenario.
+ * A definition of a view.  A view presents a set of graphs, either for a single input scenario
+ * or for a mix of different dataset/scenario combinations.
  */
 interface ComparisonViewSpec {
     kind: 'view';
     /** The title of the view.  If undefined, the title will be inferred from the scenario. */
     title?: ComparisonViewTitle;
     /** The subtitle of the view.  If undefined, the subtitle will be inferred from the scenario. */
-    subtitle?: ComparisonViewGroupTitle;
-    /** The scenario to be shown in the view. */
-    scenarioId: ComparisonScenarioId;
-    /** The graphs to be shown for each scenario view. */
-    graphs: ComparisonViewGraphsSpec;
+    subtitle?: ComparisonViewSubtitle;
+    /** The scenario to be shown in the view if this is a single-scenario view. */
+    scenarioId?: ComparisonScenarioId;
+    /** The array of rows to be shown in the view if this is a freeform view. */
+    rows?: ComparisonViewRowSpec[];
+    /** The graphs to be shown in the view. */
+    graphs?: ComparisonViewGraphsSpec;
+    /**
+     * The order in which the graphs will be displayed.  If undefined, the graphs will be
+     * displayed in the "default" order, i.e., in the same order that the IDs were specified.
+     */
+    graphOrder?: ComparisonViewGraphOrder;
 }
-declare type ComparisonViewGroupTitle = string;
+type ComparisonViewGroupTitle = string;
 /**
  * Specifies a view group with an explicit array of view definitions.
  */
@@ -656,23 +752,30 @@ interface ComparisonViewGroupWithScenariosSpec {
     scenarios: (ComparisonScenarioRefSpec | ComparisonScenarioGroupRefSpec)[];
     /** The graphs to be shown for each scenario view. */
     graphs: ComparisonViewGraphsSpec;
+    /**
+     * The order in which the graphs will be displayed.  If undefined, the graphs will be
+     * displayed in the "default" order, i.e., in the same order that the IDs were specified.
+     */
+    graphOrder?: ComparisonViewGraphOrder;
 }
 /**
  * A definition of a group of views.  Multiple related views can be grouped together under a single title
  * to make them easy to distinguish in a report.
  */
-declare type ComparisonViewGroupSpec = ComparisonViewGroupWithViewsSpec | ComparisonViewGroupWithScenariosSpec;
+type ComparisonViewGroupSpec = ComparisonViewGroupWithViewsSpec | ComparisonViewGroupWithScenariosSpec;
 /**
  * Contains the scenario and view definitions from one or more sources (JSON/YAML files or manually
  * defined specs).
  */
 interface ComparisonSpecs {
     /** The requested scenarios. */
-    scenarios: ComparisonScenarioSpec[];
+    scenarios?: ComparisonScenarioSpec[];
     /** The requested scenario groups. */
-    scenarioGroups: ComparisonScenarioGroupSpec[];
+    scenarioGroups?: ComparisonScenarioGroupSpec[];
+    /** The requested graph groups. */
+    graphGroups?: ComparisonGraphGroupSpec[];
     /** The requested view groups. */
-    viewGroups: ComparisonViewGroupSpec[];
+    viewGroups?: ComparisonViewGroupSpec[];
 }
 /** A source of comparison scenario and specifications. */
 interface ComparisonSpecsSource {
@@ -700,7 +803,7 @@ interface ComparisonDataset {
     outputVarR?: OutputVar;
 }
 /** A unique key for a `ComparisonScenario`, generated internally for use by the library. */
-declare type ComparisonScenarioKey = string & {
+type ComparisonScenarioKey = string & {
     _brand?: 'ComparisonScenarioKey';
 };
 interface ComparisonResolverUnknownInputError {
@@ -709,7 +812,7 @@ interface ComparisonResolverUnknownInputError {
 interface ComparisonResolverInvalidValueError {
     kind: 'invalid-value';
 }
-declare type ComparisonResolverError = ComparisonResolverUnknownInputError | ComparisonResolverInvalidValueError;
+type ComparisonResolverError = ComparisonResolverUnknownInputError | ComparisonResolverInvalidValueError;
 /** Describes the resolution state for a scenario input relative to a specific model. */
 interface ComparisonScenarioInputState {
     /** The matched input variable; can be undefined if no input matched. */
@@ -746,7 +849,7 @@ interface ComparisonScenarioAllInputsSettings {
  * The configuration for an input scenario, either a set of individual input settings, or one
  * that sets all inputs in the model to a certain position.
  */
-declare type ComparisonScenarioSettings = ComparisonScenarioInputSettings | ComparisonScenarioAllInputsSettings;
+type ComparisonScenarioSettings = ComparisonScenarioInputSettings | ComparisonScenarioAllInputsSettings;
 /** A single resolved input scenario. */
 interface ComparisonScenario {
     kind: 'scenario';
@@ -779,7 +882,7 @@ interface ComparisonScenarioGroup {
     /** The title of the group. */
     title: ComparisonScenarioGroupTitle;
     /**
-     * The scenarios that are included in this group.  This includes scenario that were successfully
+     * The scenarios that are included in this group.  This includes scenarios that were successfully
      * resolved as well as scenario references that could not be resolved.
      */
     scenarios: (ComparisonScenario | ComparisonUnresolvedScenarioRef)[];
@@ -790,17 +893,58 @@ interface ComparisonUnresolvedScenarioGroupRef {
     /** The ID of the referenced scenario group that could not be resolved. */
     scenarioGroupId: ComparisonScenarioGroupId;
 }
-/** A resolved view definition.  A view presents a set of graphs for a single input scenario. */
+/** A resolved group of graphs. */
+interface ComparisonGraphGroup {
+    kind: 'graph-group';
+    /** The unique identifier for the group. */
+    id: ComparisonScenarioGroupId;
+    /** The graphs that are included in this group. */
+    graphIds: ComparisonGraphId[];
+}
+/**
+ * A resolved comparison box to be shown in a view.
+ */
+interface ComparisonViewBox {
+    kind: 'view-box';
+    /** The title of the box. */
+    title: ComparisonViewItemTitle;
+    /** The subtitle of the box. */
+    subtitle?: ComparisonViewItemSubtitle;
+    /** The resolved dataset shown in this comparison box. */
+    dataset: ComparisonDataset;
+    /** The resolved scenario shown in this comparison box. */
+    scenario: ComparisonScenario;
+}
+/**
+ * A resolved row of comparison boxes to be shown in a view.
+ */
+interface ComparisonViewRow {
+    kind: 'view-row';
+    /** The title of the row. */
+    title: ComparisonViewRowTitle;
+    /** The subtitle of the row. */
+    subtitle?: ComparisonViewRowSubtitle;
+    /** The array of resolved boxes to be shown in the row. */
+    boxes: ComparisonViewBox[];
+}
+/**
+ * A resolved view definition.  A view presents a set of graphs, either for a single input scenario
+ * or for a mix of different dataset/scenario combinations.
+ */
 interface ComparisonView {
     kind: 'view';
     /** The title of the view. */
     title: ComparisonViewTitle;
     /** The subtitle of the view. */
     subtitle?: ComparisonViewSubtitle;
-    /** The resolved scenario to be shown in the view. */
-    scenario: ComparisonScenario;
+    /** The resolved scenario to be shown in the view if this is a single-scenario view. */
+    scenario?: ComparisonScenario;
+    /** The array of resolved rows to be shown in the view if this is a freeform view. */
+    rows?: ComparisonViewRow[];
     /** The graphs to be shown for each scenario view. */
-    graphs: 'all' | ComparisonViewGraphId[];
+    graphIds: ComparisonGraphId[];
+    /** The order in which the graphs will be displayed. */
+    graphOrder: ComparisonViewGraphOrder;
 }
 /** An unresolved view. */
 interface ComparisonUnresolvedView {
@@ -809,6 +953,10 @@ interface ComparisonUnresolvedView {
     title?: ComparisonViewTitle;
     /** The requested subtitle of the view, if provided. */
     subtitle?: ComparisonViewSubtitle;
+    /** The name of the referenced dataset that could not be resolved. */
+    datasetName?: ComparisonDatasetName;
+    /** The source of the referenced dataset that could not be resolved. */
+    datasetSource?: ComparisonDatasetSource;
     /** The ID of the referenced scenario that could not be resolved. */
     scenarioId?: ComparisonScenarioId;
     /** The ID of the referenced scenario group that could not be resolved. */
@@ -844,6 +992,21 @@ interface ComparisonDatasets {
      * @param scenario The scenario definition.
      */
     getDatasetKeysForScenario(scenario: ComparisonScenario): DatasetKey[];
+    /**
+     * Return the reference plots that should be shown in the comparison graph for the
+     * given dataset and scenario.
+     *
+     * @param datasetKey The key for the dataset.
+     * @param scenario The scenario for which the dataset will be displayed.
+     */
+    getReferencePlotsForDataset(datasetKey: DatasetKey, scenario: ComparisonScenario): ComparisonPlot[];
+    /**
+     * Return the context graph IDs that should be shown for the given dataset and scenario.
+     *
+     * @param datasetKey The key for the dataset.
+     * @param scenario The scenario for which the dataset will be displayed.
+     */
+    getContextGraphIdsForDataset(datasetKey: DatasetKey, scenario: ComparisonScenario): BundleGraphId[];
 }
 
 interface ComparisonScenarios {
@@ -859,6 +1022,19 @@ interface ComparisonScenarios {
     getScenario(key: ComparisonScenarioKey): ComparisonScenario | undefined;
 }
 
+/**
+ * Describes an extra plot to be shown in a comparison graph.
+ */
+interface ComparisonPlot {
+    /** The dataset key for the plot. */
+    datasetKey: DatasetKey;
+    /** The plot color. */
+    color: string;
+    /** The plot style.  If undefined, defaults to 'normal'. */
+    style?: 'normal' | 'dashed';
+    /** The plot line width, in px units.  If undefined, a default width will be used. */
+    lineWidth?: number;
+}
 interface ComparisonDatasetOptions {
     /**
      * The mapping of renamed dataset keys (old or "left" name as the map key,
@@ -872,6 +1048,21 @@ interface ComparisonDatasetOptions {
      * datasets (for example, to omit datasets that are not relevant).
      */
     datasetKeysForScenario?: (allDatasetKeys: DatasetKey[], scenario: ComparisonScenario) => DatasetKey[];
+    /**
+     * An optional function that allows for including additional reference plots
+     * on a comparison graph for a given dataset and scenario.  By default, no
+     * additional reference plots are included, but if a custom function is
+     * provided, it can return an array of `ComparisonPlot` objects.
+     */
+    referencePlotsForDataset?: (dataset: ComparisonDataset, scenario: ComparisonScenario) => ComparisonPlot[];
+    /**
+     * An optional function that allows for customizing the set of context graphs
+     * that are shown for a given dataset and scenario.  By default, all graphs in
+     * which the dataset appears will be shown, but if a custom function is provided,
+     * it can return a different set of graphs (for example, to omit graphs that are
+     * not relevant under the given scenario).
+     */
+    contextGraphIdsForDataset?: (dataset: ComparisonDataset, scenario: ComparisonScenario) => BundleGraphId[];
 }
 interface ComparisonOptions {
     /** The left-side ("baseline") bundle being compared. */
@@ -907,7 +1098,7 @@ interface ComparisonConfig {
     viewGroups: ComparisonViewGroup[];
 }
 
-declare type ComparisonDataRequestKey = string;
+type ComparisonDataRequestKey = string;
 /**
  * Coordinates loading of data in parallel from two models.
  */
@@ -928,7 +1119,7 @@ interface DiffPoint {
     valueL: number;
     valueR: number;
 }
-declare type DiffValidity = 'neither' | 'left-only' | 'right-only' | 'both';
+type DiffValidity = 'neither' | 'left-only' | 'right-only' | 'both';
 interface DiffReport {
     validity: DiffValidity;
     minValue: number;
@@ -1002,7 +1193,7 @@ interface ComparisonSummary {
     perfReportR: PerfReport;
 }
 
-declare type GraphInclusion = 'neither' | 'left-only' | 'right-only' | 'both';
+type GraphInclusion = 'neither' | 'left-only' | 'right-only' | 'both';
 interface GraphComparisonMetadataReport {
     /** The key for the metadata field. */
     key: string;
@@ -1046,8 +1237,8 @@ declare function diffGraphs(graphL: BundleGraphSpec | undefined, graphR: BundleG
  */
 declare function comparisonSummaryFromReport(comparisonReport: ComparisonReport): ComparisonSummary;
 
-declare type ComparisonGroupKind = 'by-dataset' | 'by-scenario';
-declare type ComparisonGroupKey = string;
+type ComparisonGroupKind = 'by-dataset' | 'by-scenario';
+type ComparisonGroupKey = string;
 /**
  * A group of comparison test summaries associated with a particular scenario or dataset.
  */
@@ -1063,7 +1254,7 @@ interface ComparisonGroup {
     testSummaries: ComparisonTestSummary[];
 }
 /** Describes the "root" or primary item for a group of comparisons. */
-declare type ComparisonGroupRoot = ComparisonDataset | ComparisonScenario;
+type ComparisonGroupRoot = ComparisonDataset | ComparisonScenario;
 /** A summary of scores for a group of comparisons. */
 interface ComparisonGroupScores {
     /** The total number of comparisons (sample size) for this group. */
@@ -1124,12 +1315,23 @@ interface ComparisonGroupSummariesByCategory {
  * Rolls up all by-scenario and by-dataset groupings.
  */
 interface ComparisonCategorizedResults {
+    /** All summaries for the comparison tests that were performed. */
+    allTestSummaries: ComparisonTestSummary[];
     /** The full set of by-scenario groupings. */
     byScenario: ComparisonGroupSummariesByCategory;
     /** The full set of by-dataset groupings. */
     byDataset: ComparisonGroupSummariesByCategory;
 }
 
+/**
+ * Compute the overall scores for the given group of comparison test summaries.
+ *
+ * @param testSummaries The comparison test summaries to consider.
+ * @param thresholds The array of thresholds that determine the buckets into which
+ * the scores will be summarized.
+ */
+declare function getScoresForTestSummaries(testSummaries: ComparisonTestSummary[], thresholds: number[]): ComparisonGroupScores;
+
 /**
  * Given a set of terse test summaries (which only includes summaries for tests with non-zero `maxDiff`
  * scores), restore the full set of summaries and then categorize them.
@@ -1216,7 +1418,7 @@ interface SuiteSummary {
     comparisonSummary?: ComparisonSummary;
 }
 
-declare type CancelRunSuite = () => void;
+type CancelRunSuite = () => void;
 interface RunSuiteCallbacks {
     onProgress?: (pct: number) => void;
     onComplete?: (suiteReport: SuiteReport) => void;
@@ -1245,4 +1447,4 @@ declare function runSuite(config: Config, callbacks: RunSuiteCallbacks, options?
  */
 declare function suiteSummaryFromReport(suiteReport: SuiteReport): SuiteSummary;
 
-export { AllInputsSpec, Bundle, BundleGraphData, BundleGraphDatasetSpec, BundleGraphId, BundleGraphSpec, BundleGraphView, BundleModel, CheckDataCoordinator, CheckDataRequestKey, CheckDatasetReport, CheckGroupReport, CheckKey, CheckPredicateOp, CheckPredicateOpConstantRef, CheckPredicateOpDataRef, CheckPredicateOpRef, CheckPredicateReport, CheckPredicateSummary, CheckPredicateTimeOptions, CheckPredicateTimeRange, CheckPredicateTimeSingle, CheckPredicateTimeSpec, CheckReport, CheckResult, CheckResultErrorInfo, CheckScenario, CheckScenarioError, CheckScenarioInputDesc, CheckScenarioReport, CheckStatus, CheckSummary, CheckTestReport, ComparisonCategorizedResults, ComparisonConfig, ComparisonDataCoordinator, ComparisonDataRequestKey, ComparisonDataset, ComparisonDatasetOptions, ComparisonDatasets, ComparisonGroup, ComparisonGroupKey, ComparisonGroupKind, ComparisonGroupRoot, ComparisonGroupScores, ComparisonGroupSummariesByCategory, ComparisonGroupSummary, ComparisonOptions, ComparisonReport, ComparisonResolverError, ComparisonResolverInvalidValueError, ComparisonResolverUnknownInputError, ComparisonScenario, ComparisonScenarioAllInputsSettings, ComparisonScenarioGroup, ComparisonScenarioGroupId, ComparisonScenarioGroupRefSpec, ComparisonScenarioGroupSpec, ComparisonScenarioGroupTitle, ComparisonScenarioId, ComparisonScenarioInput, ComparisonScenarioInputAtPositionSpec, ComparisonScenarioInputAtValueSpec, ComparisonScenarioInputName, ComparisonScenarioInputPosition, ComparisonScenarioInputSettings, ComparisonScenarioInputSpec, ComparisonScenarioInputState, ComparisonScenarioKey, ComparisonScenarioPresetMatrixSpec, ComparisonScenarioRefSpec, ComparisonScenarioSettings, ComparisonScenarioSpec, ComparisonScenarioSubtitle, ComparisonScenarioTitle, ComparisonScenarioWithAllInputsSpec, ComparisonScenarioWithInputsSpec, ComparisonScenarios, ComparisonSpecs, ComparisonSpecsSource, ComparisonSummary, ComparisonTestReport, ComparisonTestSummary, ComparisonUnresolvedScenarioGroupRef, ComparisonUnresolvedScenarioRef, ComparisonUnresolvedView, ComparisonView, ComparisonViewGraphId, ComparisonViewGraphsArraySpec, ComparisonViewGraphsPresetSpec, ComparisonViewGraphsSpec, ComparisonViewGroup, ComparisonViewGroupSpec, ComparisonViewGroupTitle, ComparisonViewGroupWithScenariosSpec, ComparisonViewGroupWithViewsSpec, ComparisonViewSpec, ComparisonViewSubtitle, ComparisonViewTitle, Config, ConfigInitOptions, ConfigOptions, DataSource, Dataset, DatasetKey, DatasetMap, DatasetsResult, DiffPoint, DiffReport, DiffValidity, Dimension, GraphComparisonDatasetReport, GraphComparisonMetadataReport, GraphComparisonReport, GraphInclusion, ImplVar, InputId, InputPosition, InputSetting, InputSettingsSpec, InputVar, LegendItem, LinkItem, LoadedBundle, ModelSpec, NamedBundle, OutputVar, PerfReport, PerfRunner, PerfStats, PositionSetting, RelatedItem, RunSuiteCallbacks, RunSuiteOptions, ScenarioSpec, ScenarioSpecUid, SourceName, Subscript, SuiteReport, SuiteSummary, ValueSetting, VarId, categorizeComparisonTestSummaries, checkReportFromSummary, checkSummaryFromReport, comparisonSummaryFromReport, createConfig, datasetMessage, diffDatasets, diffGraphs, predicateMessage, runSuite, scenarioMessage, suiteSummaryFromReport };
+export { type AllInputsSpec, type Bundle, type BundleGraphData, type BundleGraphDatasetSpec, type BundleGraphId, type BundleGraphSpec, type BundleGraphView, type BundleModel, CheckDataCoordinator, type CheckDataRequestKey, type CheckDatasetReport, type CheckGroupReport, type CheckKey, type CheckPredicateOp, type CheckPredicateOpConstantRef, type CheckPredicateOpDataRef, type CheckPredicateOpRef, type CheckPredicateReport, type CheckPredicateSummary, type CheckPredicateTimeOptions, type CheckPredicateTimeRange, type CheckPredicateTimeSingle, type CheckPredicateTimeSpec, type CheckReport, type CheckResult, type CheckResultErrorInfo, type CheckScenario, type CheckScenarioError, type CheckScenarioInputDesc, type CheckScenarioReport, type CheckStatus, type CheckSummary, type CheckTestReport, type ComparisonCategorizedResults, type ComparisonConfig, ComparisonDataCoordinator, type ComparisonDataRequestKey, type ComparisonDataset, type ComparisonDatasetName, type ComparisonDatasetOptions, type ComparisonDatasetSource, type ComparisonDatasetSpec, type ComparisonDatasets, type ComparisonGraphGroup, type ComparisonGraphGroupId, type ComparisonGraphGroupRefSpec, type ComparisonGraphGroupSpec, type ComparisonGraphId, type ComparisonGraphsArraySpec, type ComparisonGraphsPresetSpec, type ComparisonGroup, type ComparisonGroupKey, type ComparisonGroupKind, type ComparisonGroupRoot, type ComparisonGroupScores, type ComparisonGroupSummariesByCategory, type ComparisonGroupSummary, type ComparisonOptions, type ComparisonPlot, type ComparisonReport, type ComparisonResolverError, type ComparisonResolverInvalidValueError, type ComparisonResolverUnknownInputError, type ComparisonScenario, type ComparisonScenarioAllInputsSettings, type ComparisonScenarioGroup, type ComparisonScenarioGroupId, type ComparisonScenarioGroupRefSpec, type ComparisonScenarioGroupSpec, type ComparisonScenarioGroupTitle, type ComparisonScenarioId, type ComparisonScenarioInput, type ComparisonScenarioInputAtPositionSpec, type ComparisonScenarioInputAtValueSpec, type ComparisonScenarioInputName, type ComparisonScenarioInputPosition, type ComparisonScenarioInputSettings, type ComparisonScenarioInputSpec, type ComparisonScenarioInputState, type ComparisonScenarioKey, type ComparisonScenarioPresetMatrixSpec, type ComparisonScenarioRefSpec, type ComparisonScenarioSettings, type ComparisonScenarioSpec, type ComparisonScenarioSubtitle, type ComparisonScenarioTitle, type ComparisonScenarioWithAllInputsSpec, type ComparisonScenarioWithDistinctInputsSpec, type ComparisonScenarioWithInputsSpec, type ComparisonScenarios, type ComparisonSpecs, type ComparisonSpecsSource, type ComparisonSummary, type ComparisonTestReport, type ComparisonTestSummary, type ComparisonUnresolvedScenarioGroupRef, type ComparisonUnresolvedScenarioRef, type ComparisonUnresolvedView, type ComparisonView, type ComparisonViewBox, type ComparisonViewBoxSpec, type ComparisonViewGraphOrder, type ComparisonViewGraphsSpec, type ComparisonViewGroup, type ComparisonViewGroupSpec, type ComparisonViewGroupTitle, type ComparisonViewGroupWithScenariosSpec, type ComparisonViewGroupWithViewsSpec, type ComparisonViewItemSubtitle, type ComparisonViewItemTitle, type ComparisonViewRow, type ComparisonViewRowSpec, type ComparisonViewRowSubtitle, type ComparisonViewRowTitle, type ComparisonViewSpec, type ComparisonViewSubtitle, type ComparisonViewTitle, type Config, type ConfigInitOptions, type ConfigOptions, type DataSource, type Dataset, type DatasetGroupName, type DatasetKey, type DatasetMap, type DatasetsResult, type DiffPoint, type DiffReport, type DiffValidity, type Dimension, type GraphComparisonDatasetReport, type GraphComparisonMetadataReport, type GraphComparisonReport, type GraphInclusion, type ImplVar, type InputAliasName, type InputGroupName, type InputId, type InputPosition, type InputSetting, type InputSettingsSpec, type InputVar, type LegendItem, type LinkItem, type LoadedBundle, type ModelSpec, type NamedBundle, type OutputVar, type PerfReport, PerfRunner, PerfStats, type PositionSetting, type RelatedItem, type RunSuiteCallbacks, type RunSuiteOptions, type ScenarioSpec, type ScenarioSpecUid, type SourceName, type Subscript, type SuiteReport, type SuiteSummary, type ValueSetting, type VarId, categorizeComparisonTestSummaries, checkReportFromSummary, checkSummaryFromReport, comparisonSummaryFromReport, createConfig, datasetMessage, diffDatasets, diffGraphs, getScoresForTestSummaries, predicateMessage, runSuite, scenarioMessage, suiteSummaryFromReport };