@sdeverywhere/check-core 0.1.2 → 0.1.4

package/dist/index.d.cts

@@ -499,6 +499,21 @@ declare function checkSummaryFromReport(checkReport: CheckReport): CheckSummary;
  */
 declare function checkReportFromSummary(checkConfig: CheckConfig, checkSummary: CheckSummary): CheckReport | undefined;
 
+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;
@@ -620,42 +635,99 @@ interface ComparisonScenarioGroupRefSpec {
     /** The ID of the scenario group that is referenced. */
     groupId: ComparisonScenarioGroupId;
 }
-type ComparisonViewTitle = string;
-type ComparisonViewSubtitle = string;
-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.
  */
-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;
 }
 type ComparisonViewGroupTitle = string;
 /**
@@ -680,6 +752,11 @@ 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
@@ -692,11 +769,13 @@ type ComparisonViewGroupSpec = ComparisonViewGroupWithViewsSpec | ComparisonView
  */
 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 {
@@ -803,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)[];
@@ -814,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 {
@@ -833,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. */
@@ -847,104 +971,16 @@ interface ComparisonViewGroup {
     views: (ComparisonView | ComparisonUnresolvedView)[];
 }
 
-/**
- * Provides access to the set of dataset definitions (`ComparisonDataset` instances) that are used
- * when comparing the two models.
- */
-interface ComparisonDatasets {
-    /**
-     * Return all `ComparisonDataset` instances that are available for comparisons.
-     */
-    getAllDatasets(): IterableIterator<ComparisonDataset>;
-    /**
-     * Return the dataset metadata for the given key.
-     *
-     * @param datasetKey The key for the dataset.
-     */
-    getDataset(datasetKey: DatasetKey): ComparisonDataset | undefined;
-    /**
-     * Return the keys for the datasets that should be compared for the given scenario.
-     *
-     * @param scenario The scenario definition.
-     */
-    getDatasetKeysForScenario(scenario: ComparisonScenario): DatasetKey[];
-}
-
-interface ComparisonScenarios {
-    /**
-     * Return all `ComparisonScenario` instances that are available for comparisons.
-     */
-    getAllScenarios(): IterableIterator<ComparisonScenario>;
-    /**
-     * Return the scenario definition for the given key.
-     *
-     * @param key The key for the scenario.
-     */
-    getScenario(key: ComparisonScenarioKey): ComparisonScenario | undefined;
-}
-
-interface ComparisonDatasetOptions {
-    /**
-     * The mapping of renamed dataset keys (old or "left" name as the map key,
-     * new or "right" name as the value).
-     */
-    renamedDatasetKeys?: Map<DatasetKey, DatasetKey>;
-    /**
-     * An optional function that allows for limiting the datasets that are compared
-     * for a given scenario.  By default, all datasets are compared for a given
-     * scenario, but if a custom function is provided, it can return a subset of
-     * datasets (for example, to omit datasets that are not relevant).
-     */
-    datasetKeysForScenario?: (allDatasetKeys: DatasetKey[], scenario: ComparisonScenario) => DatasetKey[];
-}
-interface ComparisonOptions {
-    /** The left-side ("baseline") bundle being compared. */
-    baseline: NamedBundle;
-    /**
-     * The array of thresholds used to color differences, e.g., [1, 5, 10] will use
-     * buckets of 0%, 0-1%, 1-5%, 5-10%, and >10%.
-     */
-    thresholds: number[];
-    /**
-     * The requested comparison scenario and view specifications.  These can be
-     * specified in YAML or JSON files, or using `Spec` objects.
-     */
-    specs: (ComparisonSpecs | ComparisonSpecsSource)[];
-    /** Optional configuration for the datasets that are compared for different scenarios. */
-    datasets?: ComparisonDatasetOptions;
-}
-interface ComparisonConfig {
-    /** The loaded left-side ("baseline") bundle being compared. */
-    bundleL: LoadedBundle;
-    /** The loaded right-side ("current") bundle being compared. */
-    bundleR: LoadedBundle;
-    /**
-     * The array of thresholds used to color differences, e.g., [1, 5, 10] will use
-     * buckets of 0%, 0-1%, 1-5%, 5-10%, and >10%.
-     */
-    thresholds: number[];
-    /** The set of resolved scenarios that will be compared. */
-    scenarios: ComparisonScenarios;
-    /** The set of resolved datasets that will be compared. */
-    datasets: ComparisonDatasets;
-    /** The set of resolved view groups. */
-    viewGroups: ComparisonViewGroup[];
+interface PerfReport {
+    readonly minTime: number;
+    readonly maxTime: number;
+    readonly avgTime: number;
+    readonly allTimes: number[];
 }
-
-type ComparisonDataRequestKey = string;
-/**
- * Coordinates loading of data in parallel from two models.
- */
-declare class ComparisonDataCoordinator {
-    readonly bundleModelL: BundleModel;
-    readonly bundleModelR: BundleModel;
-    private readonly taskQueue;
-    constructor(bundleModelL: BundleModel, bundleModelR: BundleModel);
-    private processDatasetRequest;
-    private processGraphDataRequest;
-    requestDatasetMaps(requestKey: ComparisonDataRequestKey, scenarioSpecL: ScenarioSpec, scenarioSpecR: ScenarioSpec, datasetKeys: DatasetKey[], onResponse: (datasetMapL?: DatasetMap, datasetMapR?: DatasetMap) => void): void;
-    requestGraphData(requestKey: ComparisonDataRequestKey, scenarioSpecL: ScenarioSpec, scenarioSpecR: ScenarioSpec, graphId: BundleGraphId, onResponse: (graphDataL?: BundleGraphData, graphDataR?: BundleGraphData) => void): void;
-    cancelRequest(key: ComparisonDataRequestKey): void;
+declare class PerfStats {
+    private readonly times;
+    addRun(timeInMillis: number): void;
+    toReport(): PerfReport;
 }
 
 interface DiffPoint {
@@ -964,18 +1000,6 @@ interface DiffReport {
 }
 declare function diffDatasets(datasetL: Dataset | undefined, datasetR: Dataset | undefined): DiffReport;
 
-interface PerfReport {
-    readonly minTime: number;
-    readonly maxTime: number;
-    readonly avgTime: number;
-    readonly allTimes: number[];
-}
-declare class PerfStats {
-    private readonly times;
-    addRun(timeInMillis: number): void;
-    toReport(): PerfReport;
-}
-
 /**
  * The report for a single comparison test (involving a dataset produced under
  * a specific input scenario).  This includes the full `DiffReport`, whereas
@@ -1026,50 +1050,6 @@ interface ComparisonSummary {
     perfReportR: PerfReport;
 }
 
-type GraphInclusion = 'neither' | 'left-only' | 'right-only' | 'both';
-interface GraphComparisonMetadataReport {
-    /** The key for the metadata field. */
-    key: string;
-    /** The value of the metadata field in the left bundle. */
-    valueL?: string;
-    /** The value of the metadata field in the right bundle. */
-    valueR?: string;
-}
-interface GraphComparisonDatasetReport {
-    /** The dataset key. */
-    datasetKey: DatasetKey;
-    /** The max diff for this dataset. */
-    maxDiff?: number;
-}
-interface GraphComparisonReport {
-    /** Indicates which bundles the graph is defined in. */
-    inclusion: GraphInclusion;
-    /** The metadata fields with differences. */
-    metadataReports: GraphComparisonMetadataReport[];
-    /** The datasets with differences. */
-    datasetReports: GraphComparisonDatasetReport[];
-}
-/**
- * Comparison the metadata and datasets for the given graphs.
- *
- * @param graphL The graph defined in the left bundle.
- * @param graphR The graph defined in the right bundle.
- * @param scenarioKey The key of the scenario used for comparing datasets.
- * @param testSummaries The set of test summaries from a previous comparison run.
- */
-declare function diffGraphs(graphL: BundleGraphSpec | undefined, graphR: BundleGraphSpec | undefined, scenarioKey: ComparisonScenarioKey, testSummaries: ComparisonTestSummary[]): GraphComparisonReport;
-
-/**
- * Convert a full `ComparisonReport` to a simplified `ComparisonSummary` that includes
- * the minimum set of fields needed to keep the file smaller when there are many
- * reported differences.  This only includes comparison results for which there
- * is a non-zero `maxDiff` value.
- *
- * @param comparisonReport The full comparison report.
- * @return The terse summary.
- */
-declare function comparisonSummaryFromReport(comparisonReport: ComparisonReport): ComparisonSummary;
-
 type ComparisonGroupKind = 'by-dataset' | 'by-scenario';
 type ComparisonGroupKey = string;
 /**
@@ -1148,12 +1128,300 @@ 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;
 }
 
+/**
+ * Provides access to the set of dataset definitions (`ComparisonDataset` instances) that are used
+ * when comparing the two models.
+ */
+interface ComparisonDatasets {
+    /**
+     * Return all `ComparisonDataset` instances that are available for comparisons.
+     */
+    getAllDatasets(): IterableIterator<ComparisonDataset>;
+    /**
+     * Return the dataset metadata for the given key.
+     *
+     * @param datasetKey The key for the dataset.
+     */
+    getDataset(datasetKey: DatasetKey): ComparisonDataset | undefined;
+    /**
+     * Return the keys for the datasets that should be compared for the given scenario.
+     *
+     * @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 {
+    /**
+     * Return all `ComparisonScenario` instances that are available for comparisons.
+     */
+    getAllScenarios(): IterableIterator<ComparisonScenario>;
+    /**
+     * Return the scenario definition for the given key.
+     *
+     * @param key The key for the scenario.
+     */
+    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,
+     * new or "right" name as the value).
+     */
+    renamedDatasetKeys?: Map<DatasetKey, DatasetKey>;
+    /**
+     * An optional function that allows for limiting the datasets that are compared
+     * for a given scenario.  By default, all datasets are compared for a given
+     * scenario, but if a custom function is provided, it can return a subset of
+     * 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[];
+}
+/**
+ * Describes a row in the comparison report summary view.
+ */
+interface ComparisonReportSummaryRow {
+    /** The group summary represented by the row. */
+    groupSummary: ComparisonGroupSummary;
+    /** The custom title for the row (this overrides the default title derived from the summary). */
+    title?: string;
+    /** The custom subtitle for the row (this overrides the default subtitle derived from the summary). */
+    subtitle?: string;
+}
+/**
+ * Describes a section in the comparison report summary view.
+ */
+interface ComparisonReportSummarySection {
+    /** The text to display for the section header. */
+    headerText: string;
+    /** The summary rows to display in the section. */
+    rows: ComparisonReportSummaryRow[];
+    /**
+     * The initial expanded state of the section.  If undefined, defaults to 'expanded-if-diffs',
+     * meaning the section will be initially expanded only if any rows have differences, otherwise
+     * it will be initially collapsed.
+     */
+    initialState?: 'collapsed' | 'expanded' | 'expanded-if-diffs';
+}
+/**
+ * Describes an item (box) in the comparison report detail view.
+ */
+interface ComparisonReportDetailItem {
+    /** The title of the item. */
+    title: string;
+    /** The subtitle of the item (if any). */
+    subtitle?: string;
+    /** The scenario for the item. */
+    scenario: ComparisonScenario;
+    /** The test summary for the item. */
+    testSummary: ComparisonTestSummary;
+}
+/**
+ * Describes a row in the comparison report detail view.
+ */
+interface ComparisonReportDetailRow {
+    /** The title of the row. */
+    title: string;
+    /** The subtitle of the row (if any). */
+    subtitle?: string;
+    /** The score for the row (the meaning of the value depends on the chosen statistical method). */
+    score: number;
+    /** The items in this row (one item per box). */
+    items: ComparisonReportDetailItem[];
+}
+interface ComparisonReportOptions {
+    /**
+     * An optional function that allows for customizing the order and grouping of
+     * sections and rows in the "comparisons by scenario" summary view.
+     *
+     * @param summaries The comparison summaries, one summary per scenario.
+     * @returns The sections to display in the "comparisons by scenario" summary view.
+     */
+    summarySectionsForComparisonsByScenario?: (summaries: ComparisonGroupSummariesByCategory) => ComparisonReportSummarySection[];
+    /**
+     * An optional function that allows for customizing the order and grouping of
+     * sections and rows in the "comparisons by dataset" summary view.
+     *
+     * @param summaries The comparison summaries, one summary per dataset.
+     * @returns The sections to display in the "comparisons by dataset" summary view.
+     */
+    summarySectionsForComparisonsByDataset?: (summaries: ComparisonGroupSummariesByCategory) => ComparisonReportSummarySection[];
+    /**
+     * An optional function that allows for customizing the order of rows and boxes
+     * in the detail view for a scenario.
+     *
+     * @param rows The original rows to be displayed in the detail view for a scenario.
+     * @returns The customized rows to display in the detail view for a scenario.
+     */
+    detailRowsForScenario?: (rows: ComparisonReportDetailRow[]) => ComparisonReportDetailRow[];
+    /**
+     * An optional function that allows for customizing the order of rows and boxes
+     * in the detail view for a dataset.
+     *
+     * @param rows The original rows to be displayed in the detail view for a dataset.
+     * @returns The customized rows to display in the detail view for a dataset.
+     */
+    detailRowsForDataset?: (rows: ComparisonReportDetailRow[]) => ComparisonReportDetailRow[];
+}
+interface ComparisonOptions {
+    /** The left-side ("baseline") bundle being compared. */
+    baseline: NamedBundle;
+    /**
+     * The array of thresholds used to color differences, e.g., [1, 5, 10] will use
+     * buckets of 0%, 0-1%, 1-5%, 5-10%, and >10%.
+     */
+    thresholds: number[];
+    /**
+     * The requested comparison scenario and view specifications.  These can be
+     * specified in YAML or JSON files, or using `Spec` objects.
+     */
+    specs: (ComparisonSpecs | ComparisonSpecsSource)[];
+    /** Optional configuration for the datasets that are compared for different scenarios. */
+    datasets?: ComparisonDatasetOptions;
+    /** Options for customizing the comparison report. */
+    report?: ComparisonReportOptions;
+}
+interface ComparisonConfig {
+    /** The loaded left-side ("baseline") bundle being compared. */
+    bundleL: LoadedBundle;
+    /** The loaded right-side ("current") bundle being compared. */
+    bundleR: LoadedBundle;
+    /**
+     * The array of thresholds used to color differences, e.g., [1, 5, 10] will use
+     * buckets of 0%, 0-1%, 1-5%, 5-10%, and >10%.
+     */
+    thresholds: number[];
+    /** The set of resolved scenarios that will be compared. */
+    scenarios: ComparisonScenarios;
+    /** The set of resolved datasets that will be compared. */
+    datasets: ComparisonDatasets;
+    /** The set of resolved view groups. */
+    viewGroups: ComparisonViewGroup[];
+    /** Options for customizing the comparison report. */
+    reportOptions?: ComparisonReportOptions;
+}
+
+type ComparisonDataRequestKey = string;
+/**
+ * Coordinates loading of data in parallel from two models.
+ */
+declare class ComparisonDataCoordinator {
+    readonly bundleModelL: BundleModel;
+    readonly bundleModelR: BundleModel;
+    private readonly taskQueue;
+    constructor(bundleModelL: BundleModel, bundleModelR: BundleModel);
+    private processDatasetRequest;
+    private processGraphDataRequest;
+    requestDatasetMaps(requestKey: ComparisonDataRequestKey, scenarioSpecL: ScenarioSpec, scenarioSpecR: ScenarioSpec, datasetKeys: DatasetKey[], onResponse: (datasetMapL?: DatasetMap, datasetMapR?: DatasetMap) => void): void;
+    requestGraphData(requestKey: ComparisonDataRequestKey, scenarioSpecL: ScenarioSpec, scenarioSpecR: ScenarioSpec, graphId: BundleGraphId, onResponse: (graphDataL?: BundleGraphData, graphDataR?: BundleGraphData) => void): void;
+    cancelRequest(key: ComparisonDataRequestKey): void;
+}
+
+type GraphInclusion = 'neither' | 'left-only' | 'right-only' | 'both';
+interface GraphComparisonMetadataReport {
+    /** The key for the metadata field. */
+    key: string;
+    /** The value of the metadata field in the left bundle. */
+    valueL?: string;
+    /** The value of the metadata field in the right bundle. */
+    valueR?: string;
+}
+interface GraphComparisonDatasetReport {
+    /** The dataset key. */
+    datasetKey: DatasetKey;
+    /** The max diff for this dataset. */
+    maxDiff?: number;
+}
+interface GraphComparisonReport {
+    /** Indicates which bundles the graph is defined in. */
+    inclusion: GraphInclusion;
+    /** The metadata fields with differences. */
+    metadataReports: GraphComparisonMetadataReport[];
+    /** The datasets with differences. */
+    datasetReports: GraphComparisonDatasetReport[];
+}
+/**
+ * Comparison the metadata and datasets for the given graphs.
+ *
+ * @param graphL The graph defined in the left bundle.
+ * @param graphR The graph defined in the right bundle.
+ * @param scenarioKey The key of the scenario used for comparing datasets.
+ * @param testSummaries The set of test summaries from a previous comparison run.
+ */
+declare function diffGraphs(graphL: BundleGraphSpec | undefined, graphR: BundleGraphSpec | undefined, scenarioKey: ComparisonScenarioKey, testSummaries: ComparisonTestSummary[]): GraphComparisonReport;
+
+/**
+ * Convert a full `ComparisonReport` to a simplified `ComparisonSummary` that includes
+ * the minimum set of fields needed to keep the file smaller when there are many
+ * reported differences.  This only includes comparison results for which there
+ * is a non-zero `maxDiff` value.
+ *
+ * @param comparisonReport The full comparison report.
+ * @return The terse summary.
+ */
+declare function comparisonSummaryFromReport(comparisonReport: ComparisonReport): ComparisonSummary;
+
+/**
+ * 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.
@@ -1269,4 +1537,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, ComparisonScenarioWithDistinctInputsSpec, 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, DatasetGroupName, DatasetKey, DatasetMap, DatasetsResult, DiffPoint, DiffReport, DiffValidity, Dimension, GraphComparisonDatasetReport, GraphComparisonMetadataReport, GraphComparisonReport, GraphInclusion, ImplVar, InputAliasName, InputGroupName, 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 ComparisonReportDetailItem, type ComparisonReportDetailRow, type ComparisonReportOptions, type ComparisonReportSummaryRow, type ComparisonReportSummarySection, 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 };