@sdeverywhere/check-core 0.1.2 → 0.1.3

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. */
@@ -868,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 {
@@ -883,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,
@@ -896,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. */
@@ -1148,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.
@@ -1269,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, 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 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 };