{ "schema_version": "0.1", "source_manifest": "plugins/clara/modules/reporting-engine/catalog/png_gallery_manifest.json", "purpose": "Selection-oriented rebuild of the PNG gallery manifest. Artifacts remain examples; capability records carry chart-selection semantics.", "counts": { "source_items": 73, "artifacts": 73, "capabilities": 48, "analysis_tasks": 9, "generated_manifest_capabilities": 48, "generated_manifest_capabilities_without_gallery_examples": 0 }, "coverage_gaps": { "generated_manifest_capabilities_without_gallery_examples": [], "gallery_capabilities_without_generated_manifest_records": [] }, "analysis_tasks": { "cohort_and_population": { "label": "Cohort and population", "description": "Compare stable populations, new/lost cohorts, or retention/churn-style contribution.", "analysis_task_id": "cohort_and_population", "capability_ids": [ "mix.cohort_lost_stacked_column", "mix.cohort_since_stacked_column", "mix.like_for_like_column", "mix.like_for_like_stacked_column" ], "treatments": { "lost_cohort_contribution": { "selection_emphasis": "lost_cohort_contribution", "capability_ids": [ "mix.cohort_lost_stacked_column" ], "best_when": "The reader needs to see contribution by lost or last-active cohort.", "avoid_when": "Avoid for simple time trend or non-cohort composition." }, "since_cohort_contribution": { "selection_emphasis": "since_cohort_contribution", "capability_ids": [ "mix.cohort_since_stacked_column" ], "best_when": "The reader needs to see contribution by first-active cohort over periods.", "avoid_when": "Avoid for simple time trend or non-cohort composition." }, "same_population_total_change": { "selection_emphasis": "same_population_total_change", "capability_ids": [ "mix.like_for_like_column" ], "best_when": "The reader needs total change on a stable like-for-like population.", "avoid_when": "Avoid when population churn or mix composition is the main finding." }, "same_population_composition_change": { "selection_emphasis": "same_population_composition_change", "capability_ids": [ "mix.like_for_like_stacked_column" ], "best_when": "The reader needs like-for-like total movement and composition together.", "avoid_when": "Avoid when the population is not stable or exact detail is required." } } }, "composition_and_mix": { "label": "Composition and mix", "description": "Show part-to-whole structure, nested categories, mix shift, or two-dimensional composition.", "analysis_task_id": "composition_and_mix", "capability_ids": [ "mix.area", "mix.barmekko", "mix.like_for_like_stacked_column", "mix.marimekko", "mix.stacked_bar", "mix.stacked_column", "mix.stacked_pareto" ], "treatments": { "trend_with_cumulative_or_share_area": { "selection_emphasis": "trend_with_cumulative_or_share_area", "capability_ids": [ "mix.area" ], "best_when": "The reader needs a time-series area view for absolute contribution or share over periods.", "avoid_when": "Avoid when precise line trajectory or side-by-side period gaps are clearer." }, "width_metric_times_height_metric": { "selection_emphasis": "width_metric_times_height_metric", "capability_ids": [ "mix.barmekko" ], "best_when": "The reader needs variable-width categories where width is an additive quantity, area is an additive value, and height is their derived ratio.", "avoid_when": "Avoid without a meaningful additive width denominator, when area is not additive, or when the derived ratio encoding would be hard to read." }, "same_population_composition_change": { "selection_emphasis": "same_population_composition_change", "capability_ids": [ "mix.like_for_like_stacked_column" ], "best_when": "The reader needs like-for-like total movement and composition together.", "avoid_when": "Avoid when the population is not stable or exact detail is required." }, "two_dimension_share_and_size": { "selection_emphasis": "two_dimension_share_and_size", "capability_ids": [ "mix.marimekko" ], "best_when": "The reader needs to see composition across two categorical dimensions where both width and height carry meaning.", "avoid_when": "Avoid when categories are too many, exact comparison matters, or the question is a simple ranking." }, "composition_within_ranked_totals": { "selection_emphasis": "composition_within_ranked_totals", "capability_ids": [ "mix.stacked_bar" ], "best_when": "The reader needs both total size and component composition across categories.", "avoid_when": "Avoid when exact component comparison or time trend is more important than composition." }, "composition_change_over_periods": { "selection_emphasis": "composition_change_over_periods", "capability_ids": [ "mix.stacked_column" ], "best_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "avoid_when": "Avoid when exact values or simple trend shape matters more than composition." }, "concentration_with_component_breakdown": { "selection_emphasis": "concentration_with_component_breakdown", "capability_ids": [ "mix.stacked_pareto" ], "best_when": "The reader needs Pareto concentration plus stacked composition by another dimension or class.", "avoid_when": "Avoid when a plain Pareto or plain stacked bar would be easier to read." } } }, "distribution": { "label": "Distribution", "description": "Show shape, spread, density, cumulative share, or individual observations for a metric.", "analysis_task_id": "distribution", "capability_ids": [ "distribution.boxplot", "distribution.ecdf", "distribution.histogram", "distribution.kernel_density", "distribution.stripplot" ], "treatments": { "spread_and_outliers_summary": { "selection_emphasis": "spread_and_outliers_summary", "capability_ids": [ "distribution.boxplot" ], "best_when": "The reader needs median, quartiles, spread, and outliers, especially across groups.", "avoid_when": "Avoid when distribution shape details or individual observations matter." }, "cumulative_distribution_and_percentiles": { "selection_emphasis": "cumulative_distribution_and_percentiles", "capability_ids": [ "distribution.ecdf" ], "best_when": "The reader needs percentile thresholds or cumulative share below/above values.", "avoid_when": "Avoid when frequency bins or individual observations are easier for the reader." }, "frequency_shape": { "selection_emphasis": "frequency_shape", "capability_ids": [ "distribution.histogram" ], "best_when": "The reader needs to see bins, skew, modal ranges, or rough frequency shape for one metric.", "avoid_when": "Avoid when exact percentile comparison or individual points are needed." }, "smoothed_distribution_shape": { "selection_emphasis": "smoothed_distribution_shape", "capability_ids": [ "distribution.kernel_density" ], "best_when": "The reader needs a smoothed view of distribution shape across one or more groups.", "avoid_when": "Avoid when sample size is small or exact bins/observations are important." }, "individual_observations": { "selection_emphasis": "individual_observations", "capability_ids": [ "distribution.stripplot" ], "best_when": "The reader needs to see individual observations, density, and outliers without summarizing them away.", "avoid_when": "Avoid with too many points or when an aggregate distribution shape is enough." } } }, "evidence_and_reporting_tables": { "label": "Evidence and reporting tables", "description": "Provide exact values, statement rows, funnel stages, attribute evidence, product support, or visibility detail.", "analysis_task_id": "evidence_and_reporting_tables", "capability_ids": [ "attributes.attribute_bridge_table", "attributes.attribute_bundle_comparison_table", "attributes.product_signal_evidence_table", "attributes.rank_weighted_visibility_table", "funnel.stage_table", "period_comparison.comparison_table", "statement.pnl_table" ], "treatments": { "current_vs_emerging_signal_alignment": { "selection_emphasis": "current_vs_emerging_signal_alignment", "capability_ids": [ "attributes.attribute_bridge_table" ], "best_when": "The reader needs to compare current winners with emerging signals and see alignment or divergence.", "avoid_when": "Avoid when only one cohort layer exists." }, "bundle_share_and_index_evidence": { "selection_emphasis": "bundle_share_and_index_evidence", "capability_ids": [ "attributes.attribute_bundle_comparison_table" ], "best_when": "The reader needs exact bundle evidence for current winners or emerging signals.", "avoid_when": "Avoid for product-level validation or shelf visibility decomposition." }, "product_level_grounding": { "selection_emphasis": "product_level_grounding", "capability_ids": [ "attributes.product_signal_evidence_table" ], "best_when": "The reader needs product-level support for selected bundles or standout examples.", "avoid_when": "Avoid for ranking category-wide signal prevalence." }, "rank_weighted_visibility": { "selection_emphasis": "rank_weighted_visibility", "capability_ids": [ "attributes.rank_weighted_visibility_table" ], "best_when": "The reader needs visibility, incremental lane contribution, or alpha robustness evidence.", "avoid_when": "Avoid as demand, sales, or causality evidence." }, "stage_counts_and_conversion": { "selection_emphasis": "stage_counts_and_conversion", "capability_ids": [ "funnel.stage_table" ], "best_when": "The reader needs exact stage counts, conversion rates, and drop-offs.", "avoid_when": "Avoid when a visual shape is more important than exact stage evidence." }, "summary_exact_values": { "selection_emphasis": "summary_exact_values", "capability_ids": [ "period_comparison.comparison_table" ], "best_when": "The reader needs compact exact AC/PY totals and deltas by comparison row.", "avoid_when": "Avoid when the message depends on the period path or monthly sequencing." }, "structured_statement_values": { "selection_emphasis": "structured_statement_values", "capability_ids": [ "statement.pnl_table" ], "best_when": "The reader needs a P&L-style table with business rows and comparison columns.", "avoid_when": "Avoid for exploratory charting or relationship analysis." } } }, "metric_relationship": { "label": "Metric relationship and secondary metrics", "description": "Show relationships, outliers, or secondary metric markers across observations.", "analysis_task_id": "metric_relationship", "capability_ids": [ "mix.column_overlay", "mix.stacked_bar_overlay", "scatter.bubble", "scatter.scatter" ], "treatments": { "total_plus_related_marker": { "selection_emphasis": "total_plus_related_marker", "capability_ids": [ "mix.column_overlay" ], "best_when": "The reader needs total metric movement with a related marker shown in the same compact view.", "avoid_when": "Avoid when the relationship between metrics is the main analytical object." }, "primary_rank_plus_secondary_marker": { "selection_emphasis": "primary_rank_plus_secondary_marker", "capability_ids": [ "mix.stacked_bar_overlay" ], "best_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "avoid_when": "Avoid when the secondary metric deserves a full relationship plot or when composition is the point." }, "two_metric_relationship_plus_size": { "selection_emphasis": "two_metric_relationship_plus_size", "capability_ids": [ "scatter.bubble" ], "best_when": "The reader needs x/y relationship plus magnitude encoded by bubble size.", "avoid_when": "Avoid when bubble size would obscure the relationship or when period movement is the question." }, "relationship_between_two_metrics": { "selection_emphasis": "relationship_between_two_metrics", "capability_ids": [ "scatter.scatter" ], "best_when": "The reader needs to see association, clusters, quadrants, or outliers between two metrics.", "avoid_when": "Avoid for time trends, one-dimensional ranking, or exact tables." } } }, "ranking_and_comparison": { "label": "Ranking and comparison", "description": "Compare categories, entities, or periods by value, gap, rank, or compact summary.", "analysis_task_id": "ranking_and_comparison", "capability_ids": [ "mix.bar", "mix.multitier_bar", "mix.pareto", "period_comparison.comparison_table", "period_comparison.dot" ], "treatments": { "ranked_single_metric_comparison": { "selection_emphasis": "ranked_single_metric_comparison", "capability_ids": [ "mix.bar" ], "best_when": "The reader needs a sorted comparison of one additive metric across items for one selected scope or period.", "avoid_when": "Avoid when composition, hierarchy, time movement, or a second metric relationship is the point." }, "dimension_period_values_and_delta": { "selection_emphasis": "dimension_period_values_and_delta", "capability_ids": [ "mix.multitier_bar" ], "best_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "avoid_when": "Avoid when the question is categorical hierarchy, composition, single-period ranking, or continuous trend shape." }, "ranked_contribution_and_cumulative_share": { "selection_emphasis": "ranked_contribution_and_cumulative_share", "capability_ids": [ "mix.pareto" ], "best_when": "The reader needs to identify the few categories that explain most of the metric.", "avoid_when": "Avoid when component composition, period movement, or nested hierarchy is the main message." }, "summary_exact_values": { "selection_emphasis": "summary_exact_values", "capability_ids": [ "period_comparison.comparison_table" ], "best_when": "The reader needs compact exact AC/PY totals and deltas by comparison row.", "avoid_when": "Avoid when the message depends on the period path or monthly sequencing." }, "gap_between_two_values": { "selection_emphasis": "gap_between_two_values", "capability_ids": [ "period_comparison.dot" ], "best_when": "The reader needs a low-clutter comparison of two values across categories, panels, or periods.", "avoid_when": "Avoid when the month-by-month path or additive reconciliation matters." } } }, "set_overlap": { "label": "Set overlap", "description": "Show intersections across sets or segments.", "analysis_task_id": "set_overlap", "capability_ids": [ "set_overlap.upset", "set_overlap.upset_small_multiples", "set_overlap.venn" ], "treatments": { "many_set_intersections": { "selection_emphasis": "many_set_intersections", "capability_ids": [ "set_overlap.upset" ], "best_when": "The reader needs to compare intersections across more than two sets.", "avoid_when": "Avoid when only two or three simple sets need a familiar Venn view." }, "intersection_patterns_across_panels": { "selection_emphasis": "intersection_patterns_across_panels", "capability_ids": [ "set_overlap.upset_small_multiples" ], "best_when": "The reader needs to compare overlap structures across panels or segments.", "avoid_when": "Avoid when one aggregate overlap view is enough." }, "simple_two_or_three_set_overlap": { "selection_emphasis": "simple_two_or_three_set_overlap", "capability_ids": [ "set_overlap.venn" ], "best_when": "The reader needs an intuitive overlap picture for two or three sets.", "avoid_when": "Avoid with more than three sets or many intersections." } } }, "time_and_period_movement": { "label": "Time and period movement", "description": "Understand movement across ordered periods, current-vs-baseline period windows, or period-based summaries.", "analysis_task_id": "time_and_period_movement", "capability_ids": [ "mix.area", "mix.column", "mix.multitier_bar", "mix.stacked_column", "mix.timeline", "period_comparison.by_period", "period_comparison.dot", "period_comparison.horizontal_waterfall", "period_comparison.multitier_column", "period_comparison.slope", "period_comparison.time_series_table", "period_comparison.trend" ], "treatments": { "trend_with_cumulative_or_share_area": { "selection_emphasis": "trend_with_cumulative_or_share_area", "capability_ids": [ "mix.area" ], "best_when": "The reader needs a time-series area view for absolute contribution or share over periods.", "avoid_when": "Avoid when precise line trajectory or side-by-side period gaps are clearer." }, "total_metric_by_period_or_scope": { "selection_emphasis": "total_metric_by_period_or_scope", "capability_ids": [ "mix.column" ], "best_when": "The reader needs a compact total metric column view across selected periods or scopes.", "avoid_when": "Avoid when component composition, relationship, or detailed period path is needed." }, "dimension_period_values_and_delta": { "selection_emphasis": "dimension_period_values_and_delta", "capability_ids": [ "mix.multitier_bar" ], "best_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "avoid_when": "Avoid when the question is categorical hierarchy, composition, single-period ranking, or continuous trend shape." }, "composition_change_over_periods": { "selection_emphasis": "composition_change_over_periods", "capability_ids": [ "mix.stacked_column" ], "best_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "avoid_when": "Avoid when exact values or simple trend shape matters more than composition." }, "single_metric_trend_shape": { "selection_emphasis": "single_metric_trend_shape", "capability_ids": [ "mix.timeline" ], "best_when": "The reader needs the trend path of the primary mix metric across ordered periods.", "avoid_when": "Avoid when composition, hierarchy, or AC/PY period comparison is the main message." }, "period_by_period_gap": { "selection_emphasis": "period_by_period_gap", "capability_ids": [ "period_comparison.by_period" ], "best_when": "The reader needs weekly-average current and baseline values across overlapping 52-, 26-, 13- and 4-week recency windows.", "avoid_when": "Do not use for individual calendar-month totals or monthly gaps; use multitier_column for side-by-side monthly values or trend for their trajectory. Recency windows overlap and are not additive." }, "gap_between_two_values": { "selection_emphasis": "gap_between_two_values", "capability_ids": [ "period_comparison.dot" ], "best_when": "The reader needs a low-clutter comparison of two values across categories, panels, or periods.", "avoid_when": "Avoid when the month-by-month path or additive reconciliation matters." }, "additive_reconciliation": { "selection_emphasis": "additive_reconciliation", "capability_ids": [ "period_comparison.horizontal_waterfall" ], "best_when": "The reader needs to see how period variances add from previous total to current total.", "avoid_when": "Avoid when values are non-additive or the message is trend shape rather than reconciliation." }, "compact_side_by_side_period_comparison": { "selection_emphasis": "compact_side_by_side_period_comparison", "capability_ids": [ "period_comparison.multitier_column" ], "best_when": "The reader needs a compact executive AC/PY period comparison with clear column contrast.", "avoid_when": "Avoid when line shape, exact values, or total bridge reconciliation is the main message." }, "endpoint_direction_and_relative_change": { "selection_emphasis": "endpoint_direction_and_relative_change", "capability_ids": [ "period_comparison.slope" ], "best_when": "The reader needs direction and magnitude of change between two endpoints, especially across multiple comparable items.", "avoid_when": "Avoid when intermediate months, exact values, or additive bridge components are essential." }, "exact_values": { "selection_emphasis": "exact_values", "capability_ids": [ "period_comparison.time_series_table" ], "best_when": "The report needs citeable period values, deltas, and percent deltas rather than a primarily visual reading.", "avoid_when": "Avoid as the only visual when the reader must quickly perceive shape, gap, or reconciliation." }, "trajectory_shape": { "selection_emphasis": "trajectory_shape", "capability_ids": [ "period_comparison.trend" ], "best_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "avoid_when": "Avoid when exact values, total reconciliation, or a two-endpoint before/after comparison is the main message." } } }, "variance_and_bridge": { "label": "Variance and bridge", "description": "Reconcile movement through additive drivers, root-cause components, or price-volume-mix decompositions.", "analysis_task_id": "variance_and_bridge", "capability_ids": [ "period_comparison.horizontal_waterfall", "variance.exploded_variance_bridge", "variance.price_volume_mix", "variance.root_cause_component_bridge", "variance.root_cause_exploded_bridge", "variance.root_cause_total_bridge", "variance.scenario_bridge", "variance.total_by_dimension_bridge" ], "treatments": { "additive_reconciliation": { "selection_emphasis": "additive_reconciliation", "capability_ids": [ "period_comparison.horizontal_waterfall" ], "best_when": "The reader needs to see how period variances add from previous total to current total.", "avoid_when": "Avoid when values are non-additive or the message is trend shape rather than reconciliation." }, "parent_bridge_with_child_drilldowns": { "selection_emphasis": "parent_bridge_with_child_drilldowns", "capability_ids": [ "variance.exploded_variance_bridge" ], "best_when": "Use when the question names one parent grouping dimension and one fixed second decomposition dimension to explain selected parent-row variance moves in the same visual.", "avoid_when": "Avoid when only one dimension is requested, when the second dimension is not meaningful within each parent member, when the task is a variable mixed-dimension root-cause ordering, when PVM mechanics are required, or when exact tabular detail is the deliverable." }, "pvm_decomposition_comparison": { "selection_emphasis": "pvm_decomposition_comparison", "capability_ids": [ "variance.price_volume_mix" ], "best_when": "Use only when the business question explicitly asks how value movement decomposes into price, volume, and mix effects, and the dataset has compatible value, units/volume, and price or derived price semantics.", "avoid_when": "Avoid for generic variance explanations, one-dimension splits, root-cause ordering, or any dataset without compatible value, volume, and rate semantics at the same grain." }, "component_level_root_cause": { "selection_emphasis": "component_level_root_cause", "capability_ids": [ "variance.root_cause_component_bridge" ], "best_when": "Use when the question asks which price, units, and mix component-by-dimension combinations explain movement, rather than which dimensions explain the total variance.", "avoid_when": "Avoid when units/volume is unavailable, when fewer than two candidate driver dimensions exist, when the report needs the total-variance root-cause sequence, or when a simple PVM ladder is sufficient." }, "root_cause_path_with_nested_drilldowns": { "selection_emphasis": "root_cause_path_with_nested_drilldowns", "capability_ids": [ "variance.root_cause_exploded_bridge" ], "best_when": "Use when the question asks for a variable mixed-dimension root-cause variance path and also asks to explain selected root-cause drivers with nested root-cause bridge drilldowns.", "avoid_when": "Avoid when the question names a fixed parent dimension and fixed child decomposition dimension; use variance.exploded_variance_bridge instead. Avoid when only a one-level root-cause path is needed, or when exact tabular detail is the deliverable." }, "root_cause_total_movement": { "selection_emphasis": "root_cause_total_movement", "capability_ids": [ "variance.root_cause_total_bridge" ], "best_when": "Use when the question asks for the ordered root-cause sequence behind the total movement across available dimensions, and the output should show which driver path explains the overall delta.", "avoid_when": "Avoid for a simple total bridge, a one-dimension split, a component-only root-cause question, or PVM decomposition." }, "scenario_reconciliation": { "selection_emphasis": "scenario_reconciliation", "capability_ids": [ "variance.scenario_bridge" ], "best_when": "Use for the plain bridge from one baseline total to one current total when the message is the additive reconciliation itself, not a ranked dimension split, root-cause path, or PVM mechanics.", "avoid_when": "Avoid when the question names a dimension to split by, asks for nested drilldowns, asks why via root-cause ordering, asks for price/volume/mix, or when trend shape is the message." }, "total_delta_split_by_dimension": { "selection_emphasis": "total_delta_split_by_dimension", "capability_ids": [ "variance.total_by_dimension_bridge" ], "best_when": "Use when the question explicitly asks how the total delta is distributed across members of one named dimension, such as category, retailer, region, brand, or channel.", "avoid_when": "Avoid when the reader needs the generic total bridge, a nested parent/child drilldown, an ordered root-cause path across multiple dimensions, or price-volume-mix mechanics." } } } }, "capabilities": { "attributes.attribute_bridge_table": { "family": "attributes", "visual_grammar": "attribute_bridge_table", "analysis_task_ids": [ "evidence_and_reporting_tables" ], "selection_tags": [ "attribute_signal_bridge" ], "selection_emphasis": "current_vs_emerging_signal_alignment", "best_when": "The reader needs to compare current winners with emerging signals and see alignment or divergence.", "avoid_when": "Avoid when only one cohort layer exists.", "axis_roles": { "rows": "signal_bundle", "columns": "current_and_emerging_evidence" }, "period_semantics": { "role": "none", "supports_period_axis": false, "supports_period_filter": false, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [] }, "display_metric_roles": [ "current_signal_metric", "emerging_signal_metric", "alignment_metric" ], "metric_requirements": { "source_metric_roles": [], "derived_metric_roles": [ { "role": "current_signal_metric", "produced_from": [ "attribute_evidence_package", "current_cohort" ], "derivation": "package-derived current winner signal" }, { "role": "emerging_signal_metric", "produced_from": [ "attribute_evidence_package", "emerging_cohort" ], "derivation": "package-derived emerging signal" }, { "role": "alignment_metric", "produced_from": [ "current_signal_metric", "emerging_signal_metric" ], "derivation": "package-defined alignment or divergence between current and emerging signals" } ], "minimum_source_metric_count": 0, "metric_selection_notes": [ "The bridge table requires a reviewed signal package with current and emerging cohorts; raw categorical columns are not enough." ] }, "dimension_roles": [ "signal_bundle", "cohort_layer" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "attributes.attribute_bundle_comparison_table", "attributes.product_signal_evidence_table", "attributes.rank_weighted_visibility_table" ], "capability_id": "attributes.attribute_bridge_table", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "attributes / attribute_bridge_table" ], "example_count": 1, "primary_decision_cue": "Question asks how current attribute signals align with or differ from emerging signals.", "requires_question_focus": [ "attribute_signal_alignment", "current_vs_emerging" ], "reject_decision_cues": [ "asks for product rows", "asks for simple rank visibility", "asks for numeric time trend" ], "forbidden_question_focus": [ "product_level_evidence", "rank_weighted_visibility", "time_trend" ], "period_scope_contract": { "role": "none", "status": "not_applicable", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": false, "accepted_scope_controls": [], "explicit_all_data_allowed": false, "unscoped_default": "not_applicable", "selector_warning": "" }, "render_contract": { "schema_version": "0.1", "chart_options": [], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "attribute_bridge_table" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "none", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": false, "scope_contract": { "role": "none", "status": "not_applicable", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": false, "accepted_scope_controls": [], "explicit_all_data_allowed": false, "unscoped_default": "not_applicable", "selector_warning": "" } }, "metrics": { "minimum_source_metric_count": 0, "source_metric_roles": [], "derived_metric_roles": [ { "role": "current_signal_metric", "produced_from": [ "attribute_evidence_package", "current_cohort" ], "derivation": "package-derived current winner signal" }, { "role": "emerging_signal_metric", "produced_from": [ "attribute_evidence_package", "emerging_cohort" ], "derivation": "package-derived emerging signal" }, { "role": "alignment_metric", "produced_from": [ "current_signal_metric", "emerging_signal_metric" ], "derivation": "package-defined alignment or divergence between current and emerging signals" } ], "display_metric_roles": [ "current_signal_metric", "emerging_signal_metric", "alignment_metric" ], "metric_selection_notes": [ "The bridge table requires a reviewed signal package with current and emerging cohorts; raw categorical columns are not enough." ] }, "dimensions": { "minimum_count": 0, "required_roles": [ "signal_bundle", "cohort_layer" ], "optional_roles": [], "role_requirements": { "signal_bundle": { "resolution_type": "semantic_or_package_role", "requires_profile_roles": [ "attribute_evidence_package" ], "output_role": "current or emerging signal bundle", "notes": "Requires a reviewed signal/package layer.", "role": "signal_bundle", "required": true }, "cohort_layer": { "resolution_type": "semantic_or_package_role", "requires_profile_roles": [ "attribute_evidence_package" ], "output_role": "current/emerging cohort layer", "notes": "Requires a reviewed package layer that defines the cohorts.", "role": "cohort_layer", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "rows": "signal_bundle", "columns": "current_and_emerging_evidence" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs to compare current winners with emerging signals and see alignment or divergence.", "reject_when": "Avoid when only one cohort layer exists.", "tie_breakers": [ { "against": "attributes.attribute_bundle_comparison_table", "choose_this_when": "The reader needs to compare current winners with emerging signals and see alignment or divergence.", "choose_other_when": "The reader needs exact bundle evidence for current winners or emerging signals.", "distinguishing_emphasis": { "this": "current_vs_emerging_signal_alignment", "other": "bundle_share_and_index_evidence" } }, { "against": "attributes.product_signal_evidence_table", "choose_this_when": "The reader needs to compare current winners with emerging signals and see alignment or divergence.", "choose_other_when": "The reader needs product-level support for selected bundles or standout examples.", "distinguishing_emphasis": { "this": "current_vs_emerging_signal_alignment", "other": "product_level_grounding" } }, { "against": "attributes.rank_weighted_visibility_table", "choose_this_when": "The reader needs to compare current winners with emerging signals and see alignment or divergence.", "choose_other_when": "The reader needs visibility, incremental lane contribution, or alpha robustness evidence.", "distinguishing_emphasis": { "this": "current_vs_emerging_signal_alignment", "other": "rank_weighted_visibility" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `attributes.attribute_bridge_table` only when the task is one of ['evidence_and_reporting_tables'] and the required emphasis is `current_vs_emerging_signal_alignment`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "attributes.attribute_bridge_table", "plugin_sources": [ "attribute-tables" ], "artifact_labels": [ "attributes / attribute_bridge_table" ], "output_forms": [ "table_html" ], "required_role_contracts": [ { "kind": "dimension", "role": "signal_bundle", "required": true, "status": "mapped", "mapping_kind": "package_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "artifact_contract_parameter", "target": "package_dir", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "cohort_layer", "required": true, "status": "mapped", "mapping_kind": "package_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "artifact_contract_parameter", "target": "package_dir", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "attributes / attribute_bridge_table", "plugin_source": "attribute-tables", "output_form": "table_html", "selector_level": "base_capability", "layout_variant": "table", "encoding_variant": "table", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.attributes", "legacy_plugin_source": "attribute-tables", "component_name": "attribute-reporting", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_attribute_table_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": {} } }, "selection_examples": { "positive_questions": [ "How do current winning attribute bundles align or diverge from emerging signals?" ], "negative_questions": [ { "question": "Show exact share, delta, and index evidence for selected attribute bundles.", "why_not": "This asks for `bundle_share_and_index_evidence`, not `current_vs_emerging_signal_alignment`.", "better_capability_id": "attributes.attribute_bundle_comparison_table" }, { "question": "Which products provide evidence for the selected attribute signal?", "why_not": "This asks for `product_level_grounding`, not `current_vs_emerging_signal_alignment`.", "better_capability_id": "attributes.product_signal_evidence_table" }, { "question": "Which attribute bundles have rank-weighted visibility evidence?", "why_not": "This asks for `rank_weighted_visibility`, not `current_vs_emerging_signal_alignment`.", "better_capability_id": "attributes.rank_weighted_visibility_table" }, { "question": "What is the stage conversion funnel?", "why_not": "This asks for `stage_counts_and_conversion`, not `current_vs_emerging_signal_alignment`.", "better_capability_id": "funnel.stage_table" }, { "question": "Give exact current, prior-year, delta, and percent-delta sales values.", "why_not": "This asks for `summary_exact_values`, not `current_vs_emerging_signal_alignment`.", "better_capability_id": "period_comparison.comparison_table" } ], "ambiguous_questions": [ { "question": "Show the supporting evidence table.", "candidate_capability_ids": [ "attributes.attribute_bridge_table", "attributes.attribute_bundle_comparison_table", "attributes.product_signal_evidence_table", "attributes.rank_weighted_visibility_table", "funnel.stage_table" ], "disambiguation_needed": "Clarify whether the intended focus is `current_vs_emerging_signal_alignment`, `bundle_share_and_index_evidence`, `product_level_grounding`, `rank_weighted_visibility`, `stage_counts_and_conversion`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "attributes.attribute_bundle_comparison_table": { "family": "attributes", "visual_grammar": "attribute_evidence_table", "analysis_task_ids": [ "evidence_and_reporting_tables" ], "selection_tags": [ "attribute_bundle_evidence" ], "selection_emphasis": "bundle_share_and_index_evidence", "best_when": "The reader needs exact bundle evidence for current winners or emerging signals.", "avoid_when": "Avoid for product-level validation or shelf visibility decomposition.", "axis_roles": { "rows": "attribute_bundle", "columns": "focus_baseline_delta_index" }, "period_semantics": { "role": "none", "supports_period_axis": false, "supports_period_filter": false, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [] }, "display_metric_roles": [ "focus_share", "baseline_share", "delta_metric", "index_metric" ], "metric_requirements": { "source_metric_roles": [], "derived_metric_roles": [ { "role": "focus_share", "produced_from": [ "attribute_evidence_package", "focus_cohort" ], "derivation": "package-derived share for the selected focus cohort" }, { "role": "baseline_share", "produced_from": [ "attribute_evidence_package", "baseline_cohort" ], "derivation": "package-derived share for the baseline cohort" }, { "role": "delta_metric", "produced_from": [ "focus_share", "baseline_share" ], "derivation": "focus_share - baseline_share" }, { "role": "index_metric", "produced_from": [ "focus_share", "baseline_share" ], "derivation": "focus_share / baseline_share when baseline is non-zero" } ], "minimum_source_metric_count": 0, "metric_selection_notes": [ "Attribute evidence tables are rendered from a reviewed attribute package; they do not accept arbitrary raw dataset metrics." ] }, "dimension_roles": [ "attribute_bundle" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "attributes.attribute_bridge_table", "attributes.product_signal_evidence_table", "attributes.rank_weighted_visibility_table" ], "capability_id": "attributes.attribute_bundle_comparison_table", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "attributes / attribute_bundle_comparison_table" ], "example_count": 1, "primary_decision_cue": "Question asks for exact attribute bundle shares, deltas, or index evidence.", "requires_question_focus": [ "attribute_bundle_metrics", "share_delta_index" ], "reject_decision_cues": [ "asks for product examples", "asks for bridge-style signal movement", "asks for charted trend" ], "forbidden_question_focus": [ "product_level_evidence", "attribute_bridge", "time_trend" ], "period_scope_contract": { "role": "none", "status": "not_applicable", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": false, "accepted_scope_controls": [], "explicit_all_data_allowed": false, "unscoped_default": "not_applicable", "selector_warning": "" }, "render_contract": { "schema_version": "0.1", "chart_options": [], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "attribute_bundle_comparison_table" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "none", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": false, "scope_contract": { "role": "none", "status": "not_applicable", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": false, "accepted_scope_controls": [], "explicit_all_data_allowed": false, "unscoped_default": "not_applicable", "selector_warning": "" } }, "metrics": { "minimum_source_metric_count": 0, "source_metric_roles": [], "derived_metric_roles": [ { "role": "focus_share", "produced_from": [ "attribute_evidence_package", "focus_cohort" ], "derivation": "package-derived share for the selected focus cohort" }, { "role": "baseline_share", "produced_from": [ "attribute_evidence_package", "baseline_cohort" ], "derivation": "package-derived share for the baseline cohort" }, { "role": "delta_metric", "produced_from": [ "focus_share", "baseline_share" ], "derivation": "focus_share - baseline_share" }, { "role": "index_metric", "produced_from": [ "focus_share", "baseline_share" ], "derivation": "focus_share / baseline_share when baseline is non-zero" } ], "display_metric_roles": [ "focus_share", "baseline_share", "delta_metric", "index_metric" ], "metric_selection_notes": [ "Attribute evidence tables are rendered from a reviewed attribute package; they do not accept arbitrary raw dataset metrics." ] }, "dimensions": { "minimum_count": 0, "required_roles": [ "attribute_bundle" ], "optional_roles": [], "role_requirements": { "attribute_bundle": { "resolution_type": "semantic_or_package_role", "requires_profile_roles": [ "attribute_evidence_package" ], "output_role": "reviewed attribute bundle", "notes": "Requires a reviewed attribute/package layer, not just raw categorical columns.", "role": "attribute_bundle", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "rows": "attribute_bundle", "columns": "focus_baseline_delta_index" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs exact bundle evidence for current winners or emerging signals.", "reject_when": "Avoid for product-level validation or shelf visibility decomposition.", "tie_breakers": [ { "against": "attributes.attribute_bridge_table", "choose_this_when": "The reader needs exact bundle evidence for current winners or emerging signals.", "choose_other_when": "The reader needs to compare current winners with emerging signals and see alignment or divergence.", "distinguishing_emphasis": { "this": "bundle_share_and_index_evidence", "other": "current_vs_emerging_signal_alignment" } }, { "against": "attributes.product_signal_evidence_table", "choose_this_when": "The reader needs exact bundle evidence for current winners or emerging signals.", "choose_other_when": "The reader needs product-level support for selected bundles or standout examples.", "distinguishing_emphasis": { "this": "bundle_share_and_index_evidence", "other": "product_level_grounding" } }, { "against": "attributes.rank_weighted_visibility_table", "choose_this_when": "The reader needs exact bundle evidence for current winners or emerging signals.", "choose_other_when": "The reader needs visibility, incremental lane contribution, or alpha robustness evidence.", "distinguishing_emphasis": { "this": "bundle_share_and_index_evidence", "other": "rank_weighted_visibility" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `attributes.attribute_bundle_comparison_table` only when the task is one of ['evidence_and_reporting_tables'] and the required emphasis is `bundle_share_and_index_evidence`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "attributes.attribute_bundle_comparison_table", "plugin_sources": [ "attribute-tables" ], "artifact_labels": [ "attributes / attribute_bundle_comparison_table" ], "output_forms": [ "table_html" ], "required_role_contracts": [ { "kind": "dimension", "role": "attribute_bundle", "required": true, "status": "mapped", "mapping_kind": "package_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "artifact_contract_parameter", "target": "package_dir", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "attributes / attribute_bundle_comparison_table", "plugin_source": "attribute-tables", "output_form": "table_html", "selector_level": "base_capability", "layout_variant": "table", "encoding_variant": "table", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.attributes", "legacy_plugin_source": "attribute-tables", "component_name": "attribute-reporting", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_attribute_table_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": {} } }, "selection_examples": { "positive_questions": [ "Show exact share, delta, and index evidence for selected attribute bundles." ], "negative_questions": [ { "question": "How do current winning attribute bundles align or diverge from emerging signals?", "why_not": "This asks for `current_vs_emerging_signal_alignment`, not `bundle_share_and_index_evidence`.", "better_capability_id": "attributes.attribute_bridge_table" }, { "question": "Which products provide evidence for the selected attribute signal?", "why_not": "This asks for `product_level_grounding`, not `bundle_share_and_index_evidence`.", "better_capability_id": "attributes.product_signal_evidence_table" }, { "question": "Which attribute bundles have rank-weighted visibility evidence?", "why_not": "This asks for `rank_weighted_visibility`, not `bundle_share_and_index_evidence`.", "better_capability_id": "attributes.rank_weighted_visibility_table" }, { "question": "What is the stage conversion funnel?", "why_not": "This asks for `stage_counts_and_conversion`, not `bundle_share_and_index_evidence`.", "better_capability_id": "funnel.stage_table" }, { "question": "Give exact current, prior-year, delta, and percent-delta sales values.", "why_not": "This asks for `summary_exact_values`, not `bundle_share_and_index_evidence`.", "better_capability_id": "period_comparison.comparison_table" } ], "ambiguous_questions": [ { "question": "Show the supporting evidence table.", "candidate_capability_ids": [ "attributes.attribute_bundle_comparison_table", "attributes.attribute_bridge_table", "attributes.product_signal_evidence_table", "attributes.rank_weighted_visibility_table", "funnel.stage_table" ], "disambiguation_needed": "Clarify whether the intended focus is `bundle_share_and_index_evidence`, `current_vs_emerging_signal_alignment`, `product_level_grounding`, `rank_weighted_visibility`, `stage_counts_and_conversion`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "attributes.product_signal_evidence_table": { "family": "attributes", "visual_grammar": "product_evidence_table", "analysis_task_ids": [ "evidence_and_reporting_tables" ], "selection_tags": [ "product_signal_validation" ], "selection_emphasis": "product_level_grounding", "best_when": "The reader needs product-level support for selected bundles or standout examples.", "avoid_when": "Avoid for ranking category-wide signal prevalence.", "axis_roles": { "rows": "product", "columns": "signal_and_validation_fields" }, "period_semantics": { "role": "none", "supports_period_axis": false, "supports_period_filter": false, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [] }, "display_metric_roles": [ "product_signal_score", "validation_metric" ], "metric_requirements": { "source_metric_roles": [], "derived_metric_roles": [ { "role": "product_signal_score", "produced_from": [ "attribute_evidence_package", "product" ], "derivation": "package-derived product support score for the selected signal" }, { "role": "validation_metric", "produced_from": [ "attribute_evidence_package", "product" ], "derivation": "package-derived validation evidence from PDP, review, or consistency fields" } ], "minimum_source_metric_count": 0, "metric_selection_notes": [ "Product signal evidence requires a reviewed product/signal package; a raw product dimension does not produce these fields by itself." ] }, "dimension_roles": [ "product", "signal_bundle" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "attributes.attribute_bridge_table", "attributes.attribute_bundle_comparison_table", "attributes.rank_weighted_visibility_table" ], "capability_id": "attributes.product_signal_evidence_table", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "attributes / product_signal_evidence_table" ], "example_count": 1, "primary_decision_cue": "Question asks which products support a selected signal or attribute bundle.", "requires_question_focus": [ "product_level_evidence", "signal_grounding" ], "reject_decision_cues": [ "asks for aggregate bundle index", "asks for ranked visibility only", "asks for variance bridge" ], "forbidden_question_focus": [ "aggregate_attribute_index", "rank_weighted_visibility", "variance_bridge" ], "period_scope_contract": { "role": "none", "status": "not_applicable", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": false, "accepted_scope_controls": [], "explicit_all_data_allowed": false, "unscoped_default": "not_applicable", "selector_warning": "" }, "render_contract": { "schema_version": "0.1", "chart_options": [], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "product_signal_evidence_table" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "none", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": false, "scope_contract": { "role": "none", "status": "not_applicable", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": false, "accepted_scope_controls": [], "explicit_all_data_allowed": false, "unscoped_default": "not_applicable", "selector_warning": "" } }, "metrics": { "minimum_source_metric_count": 0, "source_metric_roles": [], "derived_metric_roles": [ { "role": "product_signal_score", "produced_from": [ "attribute_evidence_package", "product" ], "derivation": "package-derived product support score for the selected signal" }, { "role": "validation_metric", "produced_from": [ "attribute_evidence_package", "product" ], "derivation": "package-derived validation evidence from PDP, review, or consistency fields" } ], "display_metric_roles": [ "product_signal_score", "validation_metric" ], "metric_selection_notes": [ "Product signal evidence requires a reviewed product/signal package; a raw product dimension does not produce these fields by itself." ] }, "dimensions": { "minimum_count": 1, "required_roles": [ "product", "signal_bundle" ], "optional_roles": [], "role_requirements": { "product": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "product", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "product", "required": true }, "signal_bundle": { "resolution_type": "semantic_or_package_role", "requires_profile_roles": [ "attribute_evidence_package" ], "output_role": "current or emerging signal bundle", "notes": "Requires a reviewed signal/package layer.", "role": "signal_bundle", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "rows": "product", "columns": "signal_and_validation_fields" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs product-level support for selected bundles or standout examples.", "reject_when": "Avoid for ranking category-wide signal prevalence.", "tie_breakers": [ { "against": "attributes.attribute_bridge_table", "choose_this_when": "The reader needs product-level support for selected bundles or standout examples.", "choose_other_when": "The reader needs to compare current winners with emerging signals and see alignment or divergence.", "distinguishing_emphasis": { "this": "product_level_grounding", "other": "current_vs_emerging_signal_alignment" } }, { "against": "attributes.attribute_bundle_comparison_table", "choose_this_when": "The reader needs product-level support for selected bundles or standout examples.", "choose_other_when": "The reader needs exact bundle evidence for current winners or emerging signals.", "distinguishing_emphasis": { "this": "product_level_grounding", "other": "bundle_share_and_index_evidence" } }, { "against": "attributes.rank_weighted_visibility_table", "choose_this_when": "The reader needs product-level support for selected bundles or standout examples.", "choose_other_when": "The reader needs visibility, incremental lane contribution, or alpha robustness evidence.", "distinguishing_emphasis": { "this": "product_level_grounding", "other": "rank_weighted_visibility" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `attributes.product_signal_evidence_table` only when the task is one of ['evidence_and_reporting_tables'] and the required emphasis is `product_level_grounding`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "attributes.product_signal_evidence_table", "plugin_sources": [ "attribute-tables" ], "artifact_labels": [ "attributes / product_signal_evidence_table" ], "output_forms": [ "table_html" ], "required_role_contracts": [ { "kind": "dimension", "role": "product", "required": true, "status": "mapped", "mapping_kind": "package_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "artifact_contract_parameter", "target": "package_dir", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "signal_bundle", "required": true, "status": "mapped", "mapping_kind": "package_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "artifact_contract_parameter", "target": "package_dir", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "attributes / product_signal_evidence_table", "plugin_source": "attribute-tables", "output_form": "table_html", "selector_level": "base_capability", "layout_variant": "table", "encoding_variant": "table", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.attributes", "legacy_plugin_source": "attribute-tables", "component_name": "attribute-reporting", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_attribute_table_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": {} } }, "selection_examples": { "positive_questions": [ "Which products provide evidence for the selected attribute signal?" ], "negative_questions": [ { "question": "How do current winning attribute bundles align or diverge from emerging signals?", "why_not": "This asks for `current_vs_emerging_signal_alignment`, not `product_level_grounding`.", "better_capability_id": "attributes.attribute_bridge_table" }, { "question": "Show exact share, delta, and index evidence for selected attribute bundles.", "why_not": "This asks for `bundle_share_and_index_evidence`, not `product_level_grounding`.", "better_capability_id": "attributes.attribute_bundle_comparison_table" }, { "question": "Which attribute bundles have rank-weighted visibility evidence?", "why_not": "This asks for `rank_weighted_visibility`, not `product_level_grounding`.", "better_capability_id": "attributes.rank_weighted_visibility_table" }, { "question": "What is the stage conversion funnel?", "why_not": "This asks for `stage_counts_and_conversion`, not `product_level_grounding`.", "better_capability_id": "funnel.stage_table" }, { "question": "Give exact current, prior-year, delta, and percent-delta sales values.", "why_not": "This asks for `summary_exact_values`, not `product_level_grounding`.", "better_capability_id": "period_comparison.comparison_table" } ], "ambiguous_questions": [ { "question": "Show the supporting evidence table.", "candidate_capability_ids": [ "attributes.product_signal_evidence_table", "attributes.attribute_bridge_table", "attributes.attribute_bundle_comparison_table", "attributes.rank_weighted_visibility_table", "funnel.stage_table" ], "disambiguation_needed": "Clarify whether the intended focus is `product_level_grounding`, `current_vs_emerging_signal_alignment`, `bundle_share_and_index_evidence`, `rank_weighted_visibility`, `stage_counts_and_conversion`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "attributes.rank_weighted_visibility_table": { "family": "attributes", "visual_grammar": "visibility_evidence_table", "analysis_task_ids": [ "evidence_and_reporting_tables" ], "selection_tags": [ "shelf_visibility_evidence" ], "selection_emphasis": "rank_weighted_visibility", "best_when": "The reader needs visibility, incremental lane contribution, or alpha robustness evidence.", "avoid_when": "Avoid as demand, sales, or causality evidence.", "axis_roles": { "rows": "rank_or_lane", "columns": "visibility_metrics" }, "period_semantics": { "role": "none", "supports_period_axis": false, "supports_period_filter": false, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [] }, "display_metric_roles": [ "gross_weight", "incremental_weight", "cumulative_weight", "robustness_metric" ], "metric_requirements": { "source_metric_roles": [], "derived_metric_roles": [ { "role": "gross_weight", "produced_from": [ "attribute_evidence_package", "rank_or_lane" ], "derivation": "package-derived gross rank-weighted visibility" }, { "role": "incremental_weight", "produced_from": [ "attribute_evidence_package", "rank_or_lane" ], "derivation": "package-derived incremental rank-weighted visibility" }, { "role": "cumulative_weight", "produced_from": [ "attribute_evidence_package", "rank_or_lane" ], "derivation": "package-derived cumulative rank-weighted visibility" }, { "role": "robustness_metric", "produced_from": [ "attribute_evidence_package" ], "derivation": "package-derived robustness across visibility assumptions" } ], "minimum_source_metric_count": 0, "metric_selection_notes": [ "Rank-weighted visibility is a package-derived evidence table; rank/lane candidates alone do not create the visibility metrics." ] }, "dimension_roles": [ "rank_or_lane" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "attributes.attribute_bridge_table", "attributes.attribute_bundle_comparison_table", "attributes.product_signal_evidence_table" ], "capability_id": "attributes.rank_weighted_visibility_table", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "attributes / rank_weighted_visibility_table" ], "example_count": 1, "primary_decision_cue": "Question asks which attributes have rank-weighted visibility evidence.", "requires_question_focus": [ "rank_weighted_visibility", "attribute_ranking" ], "reject_decision_cues": [ "asks for product rows", "asks for exact bundle share table", "asks for time movement" ], "forbidden_question_focus": [ "product_level_evidence", "bundle_share_index", "time_trend" ], "period_scope_contract": { "role": "none", "status": "not_applicable", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": false, "accepted_scope_controls": [], "explicit_all_data_allowed": false, "unscoped_default": "not_applicable", "selector_warning": "" }, "render_contract": { "schema_version": "0.1", "chart_options": [], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "rank_weighted_visibility_table" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "none", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": false, "scope_contract": { "role": "none", "status": "not_applicable", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": false, "accepted_scope_controls": [], "explicit_all_data_allowed": false, "unscoped_default": "not_applicable", "selector_warning": "" } }, "metrics": { "minimum_source_metric_count": 0, "source_metric_roles": [], "derived_metric_roles": [ { "role": "gross_weight", "produced_from": [ "attribute_evidence_package", "rank_or_lane" ], "derivation": "package-derived gross rank-weighted visibility" }, { "role": "incremental_weight", "produced_from": [ "attribute_evidence_package", "rank_or_lane" ], "derivation": "package-derived incremental rank-weighted visibility" }, { "role": "cumulative_weight", "produced_from": [ "attribute_evidence_package", "rank_or_lane" ], "derivation": "package-derived cumulative rank-weighted visibility" }, { "role": "robustness_metric", "produced_from": [ "attribute_evidence_package" ], "derivation": "package-derived robustness across visibility assumptions" } ], "display_metric_roles": [ "gross_weight", "incremental_weight", "cumulative_weight", "robustness_metric" ], "metric_selection_notes": [ "Rank-weighted visibility is a package-derived evidence table; rank/lane candidates alone do not create the visibility metrics." ] }, "dimensions": { "minimum_count": 1, "required_roles": [ "rank_or_lane" ], "optional_roles": [], "role_requirements": { "rank_or_lane": { "resolution_type": "direct_rank_or_lane", "requires_profile_roles": [ "rank_or_lane" ], "output_role": "rank, lane, bucket, class, or band", "notes": "Mechanically detectable candidates still require semantic review for visibility claims.", "role": "rank_or_lane", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "rows": "rank_or_lane", "columns": "visibility_metrics" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs visibility, incremental lane contribution, or alpha robustness evidence.", "reject_when": "Avoid as demand, sales, or causality evidence.", "tie_breakers": [ { "against": "attributes.attribute_bridge_table", "choose_this_when": "The reader needs visibility, incremental lane contribution, or alpha robustness evidence.", "choose_other_when": "The reader needs to compare current winners with emerging signals and see alignment or divergence.", "distinguishing_emphasis": { "this": "rank_weighted_visibility", "other": "current_vs_emerging_signal_alignment" } }, { "against": "attributes.attribute_bundle_comparison_table", "choose_this_when": "The reader needs visibility, incremental lane contribution, or alpha robustness evidence.", "choose_other_when": "The reader needs exact bundle evidence for current winners or emerging signals.", "distinguishing_emphasis": { "this": "rank_weighted_visibility", "other": "bundle_share_and_index_evidence" } }, { "against": "attributes.product_signal_evidence_table", "choose_this_when": "The reader needs visibility, incremental lane contribution, or alpha robustness evidence.", "choose_other_when": "The reader needs product-level support for selected bundles or standout examples.", "distinguishing_emphasis": { "this": "rank_weighted_visibility", "other": "product_level_grounding" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `attributes.rank_weighted_visibility_table` only when the task is one of ['evidence_and_reporting_tables'] and the required emphasis is `rank_weighted_visibility`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "attributes.rank_weighted_visibility_table", "plugin_sources": [ "attribute-tables" ], "artifact_labels": [ "attributes / rank_weighted_visibility_table" ], "output_forms": [ "table_html" ], "required_role_contracts": [ { "kind": "dimension", "role": "rank_or_lane", "required": true, "status": "mapped", "mapping_kind": "package_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "artifact_contract_parameter", "target": "package_dir", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "attributes / rank_weighted_visibility_table", "plugin_source": "attribute-tables", "output_form": "table_html", "selector_level": "base_capability", "layout_variant": "table", "encoding_variant": "table", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.attributes", "legacy_plugin_source": "attribute-tables", "component_name": "attribute-reporting", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_attribute_table_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": {} } }, "selection_examples": { "positive_questions": [ "Which attribute bundles have rank-weighted visibility evidence?" ], "negative_questions": [ { "question": "How do current winning attribute bundles align or diverge from emerging signals?", "why_not": "This asks for `current_vs_emerging_signal_alignment`, not `rank_weighted_visibility`.", "better_capability_id": "attributes.attribute_bridge_table" }, { "question": "Show exact share, delta, and index evidence for selected attribute bundles.", "why_not": "This asks for `bundle_share_and_index_evidence`, not `rank_weighted_visibility`.", "better_capability_id": "attributes.attribute_bundle_comparison_table" }, { "question": "Which products provide evidence for the selected attribute signal?", "why_not": "This asks for `product_level_grounding`, not `rank_weighted_visibility`.", "better_capability_id": "attributes.product_signal_evidence_table" }, { "question": "What is the stage conversion funnel?", "why_not": "This asks for `stage_counts_and_conversion`, not `rank_weighted_visibility`.", "better_capability_id": "funnel.stage_table" }, { "question": "Give exact current, prior-year, delta, and percent-delta sales values.", "why_not": "This asks for `summary_exact_values`, not `rank_weighted_visibility`.", "better_capability_id": "period_comparison.comparison_table" } ], "ambiguous_questions": [ { "question": "Show the supporting evidence table.", "candidate_capability_ids": [ "attributes.rank_weighted_visibility_table", "attributes.attribute_bridge_table", "attributes.attribute_bundle_comparison_table", "attributes.product_signal_evidence_table", "funnel.stage_table" ], "disambiguation_needed": "Clarify whether the intended focus is `rank_weighted_visibility`, `current_vs_emerging_signal_alignment`, `bundle_share_and_index_evidence`, `product_level_grounding`, `stage_counts_and_conversion`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "distribution.boxplot": { "family": "distribution", "visual_grammar": "boxplot", "analysis_task_ids": [ "distribution" ], "selection_tags": [ "distribution_compare_groups" ], "selection_emphasis": "spread_and_outliers_summary", "best_when": "The reader needs median, quartiles, spread, and outliers, especially across groups.", "avoid_when": "Avoid when distribution shape details or individual observations matter.", "axis_roles": { "x": "group_optional", "y": "metric_distribution" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "distribution_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "none_observation_level_or_explicit_grouping" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 3, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "distribution.stripplot", "distribution.histogram", "distribution.ecdf", "distribution.kernel_density" ], "capability_id": "distribution.boxplot", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "distribution / boxplot", "distribution / boxplot_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for spread, quartiles, or outliers in numeric observations.", "requires_question_focus": [ "distribution_spread", "outliers" ], "reject_decision_cues": [ "asks for every observation", "asks for smoothed shape", "asks for cumulative percentile" ], "forbidden_question_focus": [ "individual_observations", "smoothed_density", "cumulative_distribution" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "boxplot" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "boxplot" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "distribution_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "none_observation_level_or_explicit_grouping" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 0, "required_roles": [], "optional_roles": [], "role_requirements": {}, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 3, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "group_optional", "y": "metric_distribution" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs median, quartiles, spread, and outliers, especially across groups.", "reject_when": "Avoid when distribution shape details or individual observations matter.", "tie_breakers": [ { "against": "distribution.stripplot", "choose_this_when": "The reader needs median, quartiles, spread, and outliers, especially across groups.", "choose_other_when": "The reader needs to see individual observations, density, and outliers without summarizing them away.", "distinguishing_emphasis": { "this": "spread_and_outliers_summary", "other": "individual_observations" } }, { "against": "distribution.histogram", "choose_this_when": "The reader needs median, quartiles, spread, and outliers, especially across groups.", "choose_other_when": "The reader needs to see bins, skew, modal ranges, or rough frequency shape for one metric.", "distinguishing_emphasis": { "this": "spread_and_outliers_summary", "other": "frequency_shape" } }, { "against": "distribution.ecdf", "choose_this_when": "The reader needs median, quartiles, spread, and outliers, especially across groups.", "choose_other_when": "The reader needs percentile thresholds or cumulative share below/above values.", "distinguishing_emphasis": { "this": "spread_and_outliers_summary", "other": "cumulative_distribution_and_percentiles" } }, { "against": "distribution.kernel_density", "choose_this_when": "The reader needs median, quartiles, spread, and outliers, especially across groups.", "choose_other_when": "The reader needs a smoothed view of distribution shape across one or more groups.", "distinguishing_emphasis": { "this": "spread_and_outliers_summary", "other": "smoothed_distribution_shape" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `distribution.boxplot` only when the task is one of ['distribution'] and the required emphasis is `spread_and_outliers_summary`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "distribution.boxplot", "plugin_sources": [ "distribution-analysis" ], "artifact_labels": [ "distribution / boxplot", "distribution / boxplot_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "metric", "role": "distribution_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.selected_periods", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true } } ], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "distribution / boxplot_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "distribution / boxplot", "plugin_source": "distribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "boxplot", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "distribution / boxplot_small_multiples", "plugin_source": "distribution-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "boxplot", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.distribution", "legacy_plugin_source": "distribution-analysis", "component_name": "distribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "verified_by": [ "plugins/distribution-analysis/scripts/distribution_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Summarize spread and outliers in monthly sales observations." ], "negative_questions": [ { "question": "Show individual monthly sales observations and outliers.", "why_not": "This asks for `individual_observations`, not `spread_and_outliers_summary`.", "better_capability_id": "distribution.stripplot" }, { "question": "What is the distribution of monthly sales observations?", "why_not": "This asks for `frequency_shape`, not `spread_and_outliers_summary`.", "better_capability_id": "distribution.histogram" }, { "question": "Show cumulative share of sales observations below each threshold.", "why_not": "This asks for `cumulative_distribution_and_percentiles`, not `spread_and_outliers_summary`.", "better_capability_id": "distribution.ecdf" }, { "question": "Show smoothed sales-distribution shape.", "why_not": "This asks for `smoothed_distribution_shape`, not `spread_and_outliers_summary`.", "better_capability_id": "distribution.kernel_density" } ], "ambiguous_questions": [ { "question": "Show how the metric is distributed.", "candidate_capability_ids": [ "distribution.boxplot", "distribution.stripplot", "distribution.histogram", "distribution.ecdf", "distribution.kernel_density" ], "disambiguation_needed": "Clarify whether the intended focus is `spread_and_outliers_summary`, `individual_observations`, `frequency_shape`, `cumulative_distribution_and_percentiles`, `smoothed_distribution_shape`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "distribution.ecdf": { "family": "distribution", "visual_grammar": "ecdf", "analysis_task_ids": [ "distribution" ], "selection_tags": [ "distribution_cumulative" ], "selection_emphasis": "cumulative_distribution_and_percentiles", "best_when": "The reader needs percentile thresholds or cumulative share below/above values.", "avoid_when": "Avoid when frequency bins or individual observations are easier for the reader.", "axis_roles": { "x": "metric", "y": "cumulative_share" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "distribution_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "none_observation_level_or_explicit_grouping" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 3, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "distribution.histogram", "distribution.boxplot", "distribution.stripplot", "distribution.kernel_density" ], "capability_id": "distribution.ecdf", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "distribution / ecdf", "distribution / ecdf_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for cumulative share below thresholds or percentile reading.", "requires_question_focus": [ "cumulative_distribution", "percentile_threshold" ], "reject_decision_cues": [ "asks for bins", "asks for outlier summary", "asks for individual observations" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "individual_observations" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "ecdf" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "ecdf" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "distribution_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "none_observation_level_or_explicit_grouping" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 0, "required_roles": [], "optional_roles": [], "role_requirements": {}, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 3, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "metric", "y": "cumulative_share" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs percentile thresholds or cumulative share below/above values.", "reject_when": "Avoid when frequency bins or individual observations are easier for the reader.", "tie_breakers": [ { "against": "distribution.histogram", "choose_this_when": "The reader needs percentile thresholds or cumulative share below/above values.", "choose_other_when": "The reader needs to see bins, skew, modal ranges, or rough frequency shape for one metric.", "distinguishing_emphasis": { "this": "cumulative_distribution_and_percentiles", "other": "frequency_shape" } }, { "against": "distribution.boxplot", "choose_this_when": "The reader needs percentile thresholds or cumulative share below/above values.", "choose_other_when": "The reader needs median, quartiles, spread, and outliers, especially across groups.", "distinguishing_emphasis": { "this": "cumulative_distribution_and_percentiles", "other": "spread_and_outliers_summary" } }, { "against": "distribution.stripplot", "choose_this_when": "The reader needs percentile thresholds or cumulative share below/above values.", "choose_other_when": "The reader needs to see individual observations, density, and outliers without summarizing them away.", "distinguishing_emphasis": { "this": "cumulative_distribution_and_percentiles", "other": "individual_observations" } }, { "against": "distribution.kernel_density", "choose_this_when": "The reader needs percentile thresholds or cumulative share below/above values.", "choose_other_when": "The reader needs a smoothed view of distribution shape across one or more groups.", "distinguishing_emphasis": { "this": "cumulative_distribution_and_percentiles", "other": "smoothed_distribution_shape" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `distribution.ecdf` only when the task is one of ['distribution'] and the required emphasis is `cumulative_distribution_and_percentiles`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "distribution.ecdf", "plugin_sources": [ "distribution-analysis" ], "artifact_labels": [ "distribution / ecdf", "distribution / ecdf_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "metric", "role": "distribution_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.selected_periods", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true } } ], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "distribution / ecdf_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "distribution / ecdf", "plugin_source": "distribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "ecdf", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "distribution / ecdf_small_multiples", "plugin_source": "distribution-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "ecdf", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.distribution", "legacy_plugin_source": "distribution-analysis", "component_name": "distribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "verified_by": [ "plugins/distribution-analysis/scripts/distribution_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show cumulative share of sales observations below each threshold." ], "negative_questions": [ { "question": "What is the distribution of monthly sales observations?", "why_not": "This asks for `frequency_shape`, not `cumulative_distribution_and_percentiles`.", "better_capability_id": "distribution.histogram" }, { "question": "Summarize spread and outliers in monthly sales observations.", "why_not": "This asks for `spread_and_outliers_summary`, not `cumulative_distribution_and_percentiles`.", "better_capability_id": "distribution.boxplot" }, { "question": "Show individual monthly sales observations and outliers.", "why_not": "This asks for `individual_observations`, not `cumulative_distribution_and_percentiles`.", "better_capability_id": "distribution.stripplot" }, { "question": "Show smoothed sales-distribution shape.", "why_not": "This asks for `smoothed_distribution_shape`, not `cumulative_distribution_and_percentiles`.", "better_capability_id": "distribution.kernel_density" } ], "ambiguous_questions": [ { "question": "Show how the metric is distributed.", "candidate_capability_ids": [ "distribution.ecdf", "distribution.histogram", "distribution.boxplot", "distribution.stripplot", "distribution.kernel_density" ], "disambiguation_needed": "Clarify whether the intended focus is `cumulative_distribution_and_percentiles`, `frequency_shape`, `spread_and_outliers_summary`, `individual_observations`, `smoothed_distribution_shape`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "distribution.histogram": { "family": "distribution", "visual_grammar": "histogram", "analysis_task_ids": [ "distribution" ], "selection_tags": [ "distribution_shape" ], "selection_emphasis": "frequency_shape", "best_when": "The reader needs to see bins, skew, modal ranges, or rough frequency shape for one metric.", "avoid_when": "Avoid when exact percentile comparison or individual points are needed.", "axis_roles": { "x": "metric_bins", "y": "count_or_frequency" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "distribution_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "none_observation_level_or_explicit_grouping" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 3, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "distribution.boxplot", "distribution.kernel_density", "distribution.stripplot", "distribution.ecdf" ], "capability_id": "distribution.histogram", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "distribution / histogram", "distribution / histogram_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for frequency distribution shape using binned observations.", "requires_question_focus": [ "frequency_bins", "distribution_shape" ], "reject_decision_cues": [ "asks for exact points", "asks for percentile threshold", "asks for smoothed density" ], "forbidden_question_focus": [ "individual_observations", "cumulative_distribution", "smoothed_density" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "histogram" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "histogram" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "distribution_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "none_observation_level_or_explicit_grouping" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 0, "required_roles": [], "optional_roles": [], "role_requirements": {}, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 3, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "metric_bins", "y": "count_or_frequency" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs to see bins, skew, modal ranges, or rough frequency shape for one metric.", "reject_when": "Avoid when exact percentile comparison or individual points are needed.", "tie_breakers": [ { "against": "distribution.boxplot", "choose_this_when": "The reader needs to see bins, skew, modal ranges, or rough frequency shape for one metric.", "choose_other_when": "The reader needs median, quartiles, spread, and outliers, especially across groups.", "distinguishing_emphasis": { "this": "frequency_shape", "other": "spread_and_outliers_summary" } }, { "against": "distribution.kernel_density", "choose_this_when": "The reader needs to see bins, skew, modal ranges, or rough frequency shape for one metric.", "choose_other_when": "The reader needs a smoothed view of distribution shape across one or more groups.", "distinguishing_emphasis": { "this": "frequency_shape", "other": "smoothed_distribution_shape" } }, { "against": "distribution.stripplot", "choose_this_when": "The reader needs to see bins, skew, modal ranges, or rough frequency shape for one metric.", "choose_other_when": "The reader needs to see individual observations, density, and outliers without summarizing them away.", "distinguishing_emphasis": { "this": "frequency_shape", "other": "individual_observations" } }, { "against": "distribution.ecdf", "choose_this_when": "The reader needs to see bins, skew, modal ranges, or rough frequency shape for one metric.", "choose_other_when": "The reader needs percentile thresholds or cumulative share below/above values.", "distinguishing_emphasis": { "this": "frequency_shape", "other": "cumulative_distribution_and_percentiles" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `distribution.histogram` only when the task is one of ['distribution'] and the required emphasis is `frequency_shape`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "distribution.histogram", "plugin_sources": [ "distribution-analysis" ], "artifact_labels": [ "distribution / histogram", "distribution / histogram_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "metric", "role": "distribution_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.selected_periods", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true } } ], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "distribution / histogram_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "distribution / histogram", "plugin_source": "distribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "histogram", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "distribution / histogram_small_multiples", "plugin_source": "distribution-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "histogram", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.distribution", "legacy_plugin_source": "distribution-analysis", "component_name": "distribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "verified_by": [ "plugins/distribution-analysis/scripts/distribution_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "What is the distribution of monthly sales observations?" ], "negative_questions": [ { "question": "Summarize spread and outliers in monthly sales observations.", "why_not": "This asks for `spread_and_outliers_summary`, not `frequency_shape`.", "better_capability_id": "distribution.boxplot" }, { "question": "Show smoothed sales-distribution shape.", "why_not": "This asks for `smoothed_distribution_shape`, not `frequency_shape`.", "better_capability_id": "distribution.kernel_density" }, { "question": "Show individual monthly sales observations and outliers.", "why_not": "This asks for `individual_observations`, not `frequency_shape`.", "better_capability_id": "distribution.stripplot" }, { "question": "Show cumulative share of sales observations below each threshold.", "why_not": "This asks for `cumulative_distribution_and_percentiles`, not `frequency_shape`.", "better_capability_id": "distribution.ecdf" } ], "ambiguous_questions": [ { "question": "Show how the metric is distributed.", "candidate_capability_ids": [ "distribution.histogram", "distribution.boxplot", "distribution.kernel_density", "distribution.stripplot", "distribution.ecdf" ], "disambiguation_needed": "Clarify whether the intended focus is `frequency_shape`, `spread_and_outliers_summary`, `smoothed_distribution_shape`, `individual_observations`, `cumulative_distribution_and_percentiles`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "distribution.kernel_density": { "family": "distribution", "visual_grammar": "density_curve", "analysis_task_ids": [ "distribution" ], "selection_tags": [ "distribution_shape" ], "selection_emphasis": "smoothed_distribution_shape", "best_when": "The reader needs a smoothed view of distribution shape across one or more groups.", "avoid_when": "Avoid when sample size is small or exact bins/observations are important.", "axis_roles": { "x": "metric", "y": "estimated_density" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "distribution_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "none_observation_level_or_explicit_grouping" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 3, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "distribution.histogram", "distribution.ecdf", "distribution.boxplot", "distribution.stripplot" ], "capability_id": "distribution.kernel_density", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "distribution / kernel_density", "distribution / kernel_density_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for smoothed distribution shape rather than bins or points.", "requires_question_focus": [ "smoothed_density", "distribution_shape" ], "reject_decision_cues": [ "asks for exact counts by bin", "asks for outlier markers", "asks for cumulative thresholds" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "cumulative_distribution" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "kernel_density" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "kernel_density" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "distribution_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "none_observation_level_or_explicit_grouping" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 0, "required_roles": [], "optional_roles": [], "role_requirements": {}, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 3, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "metric", "y": "estimated_density" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs a smoothed view of distribution shape across one or more groups.", "reject_when": "Avoid when sample size is small or exact bins/observations are important.", "tie_breakers": [ { "against": "distribution.histogram", "choose_this_when": "The reader needs a smoothed view of distribution shape across one or more groups.", "choose_other_when": "The reader needs to see bins, skew, modal ranges, or rough frequency shape for one metric.", "distinguishing_emphasis": { "this": "smoothed_distribution_shape", "other": "frequency_shape" } }, { "against": "distribution.ecdf", "choose_this_when": "The reader needs a smoothed view of distribution shape across one or more groups.", "choose_other_when": "The reader needs percentile thresholds or cumulative share below/above values.", "distinguishing_emphasis": { "this": "smoothed_distribution_shape", "other": "cumulative_distribution_and_percentiles" } }, { "against": "distribution.boxplot", "choose_this_when": "The reader needs a smoothed view of distribution shape across one or more groups.", "choose_other_when": "The reader needs median, quartiles, spread, and outliers, especially across groups.", "distinguishing_emphasis": { "this": "smoothed_distribution_shape", "other": "spread_and_outliers_summary" } }, { "against": "distribution.stripplot", "choose_this_when": "The reader needs a smoothed view of distribution shape across one or more groups.", "choose_other_when": "The reader needs to see individual observations, density, and outliers without summarizing them away.", "distinguishing_emphasis": { "this": "smoothed_distribution_shape", "other": "individual_observations" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `distribution.kernel_density` only when the task is one of ['distribution'] and the required emphasis is `smoothed_distribution_shape`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "distribution.kernel_density", "plugin_sources": [ "distribution-analysis" ], "artifact_labels": [ "distribution / kernel_density", "distribution / kernel_density_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "metric", "role": "distribution_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.selected_periods", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true } } ], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "distribution / kernel_density_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "distribution / kernel_density", "plugin_source": "distribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "density", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "distribution / kernel_density_small_multiples", "plugin_source": "distribution-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "density", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.distribution", "legacy_plugin_source": "distribution-analysis", "component_name": "distribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "verified_by": [ "plugins/distribution-analysis/scripts/distribution_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show smoothed sales-distribution shape." ], "negative_questions": [ { "question": "What is the distribution of monthly sales observations?", "why_not": "This asks for `frequency_shape`, not `smoothed_distribution_shape`.", "better_capability_id": "distribution.histogram" }, { "question": "Show cumulative share of sales observations below each threshold.", "why_not": "This asks for `cumulative_distribution_and_percentiles`, not `smoothed_distribution_shape`.", "better_capability_id": "distribution.ecdf" }, { "question": "Summarize spread and outliers in monthly sales observations.", "why_not": "This asks for `spread_and_outliers_summary`, not `smoothed_distribution_shape`.", "better_capability_id": "distribution.boxplot" }, { "question": "Show individual monthly sales observations and outliers.", "why_not": "This asks for `individual_observations`, not `smoothed_distribution_shape`.", "better_capability_id": "distribution.stripplot" } ], "ambiguous_questions": [ { "question": "Show how the metric is distributed.", "candidate_capability_ids": [ "distribution.kernel_density", "distribution.histogram", "distribution.ecdf", "distribution.boxplot", "distribution.stripplot" ], "disambiguation_needed": "Clarify whether the intended focus is `smoothed_distribution_shape`, `frequency_shape`, `cumulative_distribution_and_percentiles`, `spread_and_outliers_summary`, `individual_observations`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "distribution.stripplot": { "family": "distribution", "visual_grammar": "stripplot", "analysis_task_ids": [ "distribution" ], "selection_tags": [ "distribution_points" ], "selection_emphasis": "individual_observations", "best_when": "The reader needs to see individual observations, density, and outliers without summarizing them away.", "avoid_when": "Avoid with too many points or when an aggregate distribution shape is enough.", "axis_roles": { "x": "group_optional", "y": "metric_points" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "distribution_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "none_observation_level_or_explicit_grouping" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 3, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "distribution.boxplot", "distribution.histogram", "distribution.ecdf", "distribution.kernel_density" ], "capability_id": "distribution.stripplot", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "distribution / stripplot", "distribution / stripplot_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks to see individual numeric observations and point-level outliers.", "requires_question_focus": [ "individual_observations", "point_outliers" ], "reject_decision_cues": [ "asks for binned frequency", "asks for quartile summary", "asks for smoothed shape" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "smoothed_density" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "stripplot" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "stripplot" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "distribution_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "none_observation_level_or_explicit_grouping" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 0, "required_roles": [], "optional_roles": [], "role_requirements": {}, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 3, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "group_optional", "y": "metric_points" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs to see individual observations, density, and outliers without summarizing them away.", "reject_when": "Avoid with too many points or when an aggregate distribution shape is enough.", "tie_breakers": [ { "against": "distribution.boxplot", "choose_this_when": "The reader needs to see individual observations, density, and outliers without summarizing them away.", "choose_other_when": "The reader needs median, quartiles, spread, and outliers, especially across groups.", "distinguishing_emphasis": { "this": "individual_observations", "other": "spread_and_outliers_summary" } }, { "against": "distribution.histogram", "choose_this_when": "The reader needs to see individual observations, density, and outliers without summarizing them away.", "choose_other_when": "The reader needs to see bins, skew, modal ranges, or rough frequency shape for one metric.", "distinguishing_emphasis": { "this": "individual_observations", "other": "frequency_shape" } }, { "against": "distribution.ecdf", "choose_this_when": "The reader needs to see individual observations, density, and outliers without summarizing them away.", "choose_other_when": "The reader needs percentile thresholds or cumulative share below/above values.", "distinguishing_emphasis": { "this": "individual_observations", "other": "cumulative_distribution_and_percentiles" } }, { "against": "distribution.kernel_density", "choose_this_when": "The reader needs to see individual observations, density, and outliers without summarizing them away.", "choose_other_when": "The reader needs a smoothed view of distribution shape across one or more groups.", "distinguishing_emphasis": { "this": "individual_observations", "other": "smoothed_distribution_shape" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `distribution.stripplot` only when the task is one of ['distribution'] and the required emphasis is `individual_observations`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "distribution.stripplot", "plugin_sources": [ "distribution-analysis" ], "artifact_labels": [ "distribution / stripplot", "distribution / stripplot_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "metric", "role": "distribution_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.selected_periods", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "explicit_all_data_allowed": true } } ], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "distribution / stripplot_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "distribution / stripplot", "plugin_source": "distribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "stripplot", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "distribution / stripplot_small_multiples", "plugin_source": "distribution-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "stripplot", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.distribution", "legacy_plugin_source": "distribution-analysis", "component_name": "distribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.selected_periods", "options.period_type", "options.period_grain", "options.fiscal_start_month", "options.rolling_window_months", "filters", "options.filters" ], "verified_by": [ "plugins/distribution-analysis/scripts/distribution_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show individual monthly sales observations and outliers." ], "negative_questions": [ { "question": "Summarize spread and outliers in monthly sales observations.", "why_not": "This asks for `spread_and_outliers_summary`, not `individual_observations`.", "better_capability_id": "distribution.boxplot" }, { "question": "What is the distribution of monthly sales observations?", "why_not": "This asks for `frequency_shape`, not `individual_observations`.", "better_capability_id": "distribution.histogram" }, { "question": "Show cumulative share of sales observations below each threshold.", "why_not": "This asks for `cumulative_distribution_and_percentiles`, not `individual_observations`.", "better_capability_id": "distribution.ecdf" }, { "question": "Show smoothed sales-distribution shape.", "why_not": "This asks for `smoothed_distribution_shape`, not `individual_observations`.", "better_capability_id": "distribution.kernel_density" } ], "ambiguous_questions": [ { "question": "Show how the metric is distributed.", "candidate_capability_ids": [ "distribution.stripplot", "distribution.boxplot", "distribution.histogram", "distribution.ecdf", "distribution.kernel_density" ], "disambiguation_needed": "Clarify whether the intended focus is `individual_observations`, `spread_and_outliers_summary`, `frequency_shape`, `cumulative_distribution_and_percentiles`, `smoothed_distribution_shape`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "funnel.stage_table": { "family": "funnel", "visual_grammar": "funnel_stage_table", "analysis_task_ids": [ "evidence_and_reporting_tables" ], "selection_tags": [ "funnel_conversion" ], "selection_emphasis": "stage_counts_and_conversion", "best_when": "The reader needs exact stage counts, conversion rates, and drop-offs.", "avoid_when": "Avoid when a visual shape is more important than exact stage evidence.", "axis_roles": { "rows": "ordered_stage", "columns": "count_and_conversion" }, "period_semantics": { "role": "none", "supports_period_axis": false, "supports_period_filter": false, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [] }, "display_metric_roles": [ "stage_start_count", "stage_pass_count", "dropoff_count", "conversion_rate" ], "metric_requirements": { "source_metric_roles": [ { "role": "stage_start_count", "required": true, "accepted_metric_classes": [ "additive_count" ], "aggregation": "sum_or_count" }, { "role": "stage_pass_count", "required": true, "accepted_metric_classes": [ "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [ { "role": "dropoff_count", "produced_from": [ "stage_start_count", "stage_pass_count" ], "derivation": "stage_start_count - stage_pass_count" }, { "role": "conversion_rate", "produced_from": [ "stage_start_count", "stage_pass_count" ], "derivation": "stage_pass_count / stage_start_count when start is non-zero" } ], "minimum_source_metric_count": 2, "metric_selection_notes": [ "Funnel tables require ordered stages and stage count columns; dropoff and conversion can be derived." ] }, "dimension_roles": [ "ordered_stage" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [], "capability_id": "funnel.stage_table", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "funnel / funnel_stage_table" ], "example_count": 1, "primary_decision_cue": "Question asks for ordered funnel stage counts or conversion rates.", "requires_question_focus": [ "funnel_stages", "conversion_rates" ], "reject_decision_cues": [ "asks for distribution", "asks for period trend", "asks for set overlap" ], "forbidden_question_focus": [ "distribution_shape", "time_trend", "set_overlap" ], "period_scope_contract": { "role": "none", "status": "not_applicable", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": false, "accepted_scope_controls": [], "explicit_all_data_allowed": false, "unscoped_default": "not_applicable", "selector_warning": "" }, "render_contract": { "schema_version": "0.1", "chart_options": [], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "funnel_stage_table" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "none", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": false, "scope_contract": { "role": "none", "status": "not_applicable", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": false, "accepted_scope_controls": [], "explicit_all_data_allowed": false, "unscoped_default": "not_applicable", "selector_warning": "" } }, "metrics": { "minimum_source_metric_count": 2, "source_metric_roles": [ { "role": "stage_start_count", "required": true, "accepted_metric_classes": [ "additive_count" ], "aggregation": "sum_or_count" }, { "role": "stage_pass_count", "required": true, "accepted_metric_classes": [ "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [ { "role": "dropoff_count", "produced_from": [ "stage_start_count", "stage_pass_count" ], "derivation": "stage_start_count - stage_pass_count" }, { "role": "conversion_rate", "produced_from": [ "stage_start_count", "stage_pass_count" ], "derivation": "stage_pass_count / stage_start_count when start is non-zero" } ], "display_metric_roles": [ "stage_start_count", "stage_pass_count", "dropoff_count", "conversion_rate" ], "metric_selection_notes": [ "Funnel tables require ordered stages and stage count columns; dropoff and conversion can be derived." ] }, "dimensions": { "minimum_count": 1, "required_roles": [ "ordered_stage" ], "optional_roles": [], "role_requirements": { "ordered_stage": { "resolution_type": "schema_role", "requires_profile_roles": [ "ordered_stage" ], "output_role": "ordered funnel stage", "notes": "Requires an explicit ordered funnel stage column or stage table.", "role": "ordered_stage", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "rows": "ordered_stage", "columns": "count_and_conversion" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs exact stage counts, conversion rates, and drop-offs.", "reject_when": "Avoid when a visual shape is more important than exact stage evidence.", "tie_breakers": [], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `funnel.stage_table` only when the task is one of ['evidence_and_reporting_tables'] and the required emphasis is `stage_counts_and_conversion`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "funnel.stage_table", "plugin_sources": [ "funnel-analysis" ], "artifact_labels": [ "funnel / funnel_stage_table" ], "output_forms": [ "table_html" ], "required_role_contracts": [ { "kind": "metric", "role": "stage_start_count", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "stage_table_mappings.start_count_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "metric", "role": "stage_pass_count", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "stage_table_mappings.pass_count_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "ordered_stage", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "stage_table_mappings.stage_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "funnel / funnel_stage_table", "plugin_source": "funnel-analysis", "output_form": "table_html", "selector_level": "base_capability", "layout_variant": "table", "encoding_variant": "table", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.funnel", "legacy_plugin_source": "funnel-analysis", "component_name": "funnel-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": {} } }, "selection_examples": { "positive_questions": [ "What is the stage conversion funnel?" ], "negative_questions": [ { "question": "How do current winning attribute bundles align or diverge from emerging signals?", "why_not": "This asks for `current_vs_emerging_signal_alignment`, not `stage_counts_and_conversion`.", "better_capability_id": "attributes.attribute_bridge_table" }, { "question": "Show exact share, delta, and index evidence for selected attribute bundles.", "why_not": "This asks for `bundle_share_and_index_evidence`, not `stage_counts_and_conversion`.", "better_capability_id": "attributes.attribute_bundle_comparison_table" }, { "question": "Which products provide evidence for the selected attribute signal?", "why_not": "This asks for `product_level_grounding`, not `stage_counts_and_conversion`.", "better_capability_id": "attributes.product_signal_evidence_table" }, { "question": "Which attribute bundles have rank-weighted visibility evidence?", "why_not": "This asks for `rank_weighted_visibility`, not `stage_counts_and_conversion`.", "better_capability_id": "attributes.rank_weighted_visibility_table" }, { "question": "Give exact current, prior-year, delta, and percent-delta sales values.", "why_not": "This asks for `summary_exact_values`, not `stage_counts_and_conversion`.", "better_capability_id": "period_comparison.comparison_table" } ], "ambiguous_questions": [ { "question": "Show the supporting evidence table.", "candidate_capability_ids": [ "funnel.stage_table", "attributes.attribute_bridge_table", "attributes.attribute_bundle_comparison_table", "attributes.product_signal_evidence_table", "attributes.rank_weighted_visibility_table" ], "disambiguation_needed": "Clarify whether the intended focus is `stage_counts_and_conversion`, `current_vs_emerging_signal_alignment`, `bundle_share_and_index_evidence`, `product_level_grounding`, `rank_weighted_visibility`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.area": { "family": "mix", "visual_grammar": "area_time_series", "analysis_task_ids": [ "time_and_period_movement", "composition_and_mix" ], "selection_tags": [ "composition_over_periods", "mix_metric_trend" ], "selection_emphasis": "trend_with_cumulative_or_share_area", "best_when": "The reader needs a time-series area view for absolute contribution or share over periods.", "avoid_when": "Avoid when precise line trajectory or side-by-side period gaps are clearer.", "axis_roles": { "x": "ordered_period", "y": "metric_or_share", "fill": "component_optional" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": false, "minimum_distinct_values": 1, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [ "optional_component_dimension" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "mix.timeline", "mix.stacked_column", "period_comparison.trend" ], "capability_id": "mix.area", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_comparison / area_absolute", "mix_comparison / area_share" ], "example_count": 2, "primary_decision_cue": "Question asks for contribution or share as an area trend across ordered periods.", "requires_question_focus": [ "area_trend", "contribution_or_share_over_time" ], "reject_decision_cues": [ "asks for precise line trajectory", "asks for AC/PY gap", "asks for exact period table" ], "forbidden_question_focus": [ "single_line_trend", "period_gap", "exact_period_values" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 1, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "area_absolute", "area_share" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "area_absolute", "area_share" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": false, "minimum_distinct_values": 1, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 1, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 0, "required_roles": [], "optional_roles": [ "optional_component_dimension" ], "role_requirements": { "optional_component_dimension": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "component_dimension", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "optional_component_dimension", "required": false } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "ordered_period", "y": "metric_or_share", "fill": "component_optional" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs a time-series area view for absolute contribution or share over periods.", "reject_when": "Avoid when precise line trajectory or side-by-side period gaps are clearer.", "tie_breakers": [ { "against": "mix.timeline", "choose_this_when": "The reader needs a time-series area view for absolute contribution or share over periods.", "choose_other_when": "The reader needs the trend path of the primary mix metric across ordered periods.", "distinguishing_emphasis": { "this": "trend_with_cumulative_or_share_area", "other": "single_metric_trend_shape" } }, { "against": "mix.stacked_column", "choose_this_when": "The reader needs a time-series area view for absolute contribution or share over periods.", "choose_other_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "distinguishing_emphasis": { "this": "trend_with_cumulative_or_share_area", "other": "composition_change_over_periods" } }, { "against": "period_comparison.trend", "choose_this_when": "The reader needs a time-series area view for absolute contribution or share over periods.", "choose_other_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "distinguishing_emphasis": { "this": "trend_with_cumulative_or_share_area", "other": "trajectory_shape" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.area` only when the task is one of ['time_and_period_movement', 'composition_and_mix'] and the required emphasis is `trend_with_cumulative_or_share_area`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.area", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_comparison / area_absolute", "mix_comparison / area_share" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "dimension", "role": "optional_component_dimension", "required": false, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "mix_comparison / area_absolute", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "area", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "mix_comparison / area_share", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "area", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show sales contribution as an area trend across months." ], "negative_questions": [ { "question": "Show the single sales trend across months without AC/PY comparison.", "why_not": "This asks for `single_metric_trend_shape`, not `trend_with_cumulative_or_share_area`.", "better_capability_id": "mix.timeline" }, { "question": "Show recent monthly sales mix by category.", "why_not": "This asks for `composition_change_over_periods`, not `trend_with_cumulative_or_share_area`.", "better_capability_id": "mix.stacked_column" }, { "question": "How did monthly cosmetics sales evolve versus previous year?", "why_not": "This asks for `trajectory_shape`, not `trend_with_cumulative_or_share_area`.", "better_capability_id": "period_comparison.trend" }, { "question": "Show total sales by month as compact columns.", "why_not": "This asks for `total_metric_by_period_or_scope`, not `trend_with_cumulative_or_share_area`.", "better_capability_id": "mix.column" }, { "question": "Show category sales in two periods and the difference, split into retailer panels.", "why_not": "This asks for `dimension_period_values_and_delta`, not `trend_with_cumulative_or_share_area`.", "better_capability_id": "mix.multitier_bar" } ], "ambiguous_questions": [ { "question": "How did sales change over time?", "candidate_capability_ids": [ "mix.area", "mix.timeline", "mix.stacked_column", "period_comparison.trend", "mix.column" ], "disambiguation_needed": "Clarify whether the intended focus is `trend_with_cumulative_or_share_area`, `single_metric_trend_shape`, `composition_change_over_periods`, `trajectory_shape`, `total_metric_by_period_or_scope`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.bar": { "family": "mix", "visual_grammar": "ranked_bar", "analysis_task_ids": [ "ranking_and_comparison" ], "selection_tags": [ "rank_category_values", "snapshot_comparison" ], "selection_emphasis": "ranked_single_metric_comparison", "best_when": "The reader needs a sorted comparison of one additive metric across items for one selected scope or period.", "avoid_when": "Avoid when composition, hierarchy, time movement, or a second metric relationship is the point.", "axis_roles": { "x": "metric", "y": "category" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [ "category" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "mix.stacked_bar", "mix.stacked_bar_overlay", "mix.multitier_bar", "mix.pareto", "scatter.scatter" ], "capability_id": "mix.bar", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_comparison / bar", "mix_comparison / bar_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks to rank categories by one selected metric in a scope.", "requires_question_focus": [ "single_metric_rank", "category_comparison" ], "reject_decision_cues": [ "asks for composition within bars", "asks for period delta", "asks for cumulative Pareto share" ], "forbidden_question_focus": [ "composition", "period_delta", "pareto_concentration" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "bar" ], "variant_chart_options": [ "bar_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "bar" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 1, "required_roles": [ "category" ], "optional_roles": [], "role_requirements": { "category": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "category", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "category", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "metric", "y": "category" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs a sorted comparison of one additive metric across items for one selected scope or period.", "reject_when": "Avoid when composition, hierarchy, time movement, or a second metric relationship is the point.", "tie_breakers": [ { "against": "mix.stacked_bar", "choose_this_when": "The reader needs a sorted comparison of one additive metric across items for one selected scope or period.", "choose_other_when": "The reader needs both total size and component composition across categories.", "distinguishing_emphasis": { "this": "ranked_single_metric_comparison", "other": "composition_within_ranked_totals" } }, { "against": "mix.stacked_bar_overlay", "choose_this_when": "The reader needs a sorted comparison of one additive metric across items for one selected scope or period.", "choose_other_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "distinguishing_emphasis": { "this": "ranked_single_metric_comparison", "other": "primary_rank_plus_secondary_marker" } }, { "against": "mix.multitier_bar", "choose_this_when": "The reader needs a sorted comparison of one additive metric across items for one selected scope or period.", "choose_other_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "distinguishing_emphasis": { "this": "ranked_single_metric_comparison", "other": "dimension_period_values_and_delta" } }, { "against": "mix.pareto", "choose_this_when": "The reader needs a sorted comparison of one additive metric across items for one selected scope or period.", "choose_other_when": "The reader needs to identify the few categories that explain most of the metric.", "distinguishing_emphasis": { "this": "ranked_single_metric_comparison", "other": "ranked_contribution_and_cumulative_share" } }, { "against": "scatter.scatter", "choose_this_when": "The reader needs a sorted comparison of one additive metric across items for one selected scope or period.", "choose_other_when": "The reader needs to see association, clusters, quadrants, or outliers between two metrics.", "distinguishing_emphasis": { "this": "ranked_single_metric_comparison", "other": "relationship_between_two_metrics" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.bar` only when the task is one of ['ranking_and_comparison'] and the required emphasis is `ranked_single_metric_comparison`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.bar", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_comparison / bar", "mix_comparison / bar_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "category", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } } ], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "mix_comparison / bar_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "mix_comparison / bar", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "bar", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "mix_comparison / bar_small_multiples", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "bar", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Rank categories by sales for a selected scope." ], "negative_questions": [ { "question": "Show sales totals and composition by retailer within categories.", "why_not": "This asks for `composition_within_ranked_totals`, not `ranked_single_metric_comparison`.", "better_capability_id": "mix.stacked_bar" }, { "question": "Rank category sales while overlaying sales-share context.", "why_not": "This asks for `primary_rank_plus_secondary_marker`, not `ranked_single_metric_comparison`.", "better_capability_id": "mix.stacked_bar_overlay" }, { "question": "Show category sales in two periods and the difference, split into retailer panels.", "why_not": "This asks for `dimension_period_values_and_delta`, not `ranked_single_metric_comparison`.", "better_capability_id": "mix.multitier_bar" }, { "question": "Find the few categories that explain most sales.", "why_not": "This asks for `ranked_contribution_and_cumulative_share`, not `ranked_single_metric_comparison`.", "better_capability_id": "mix.pareto" }, { "question": "Do units and sales share relate without size encoding?", "why_not": "This asks for `relationship_between_two_metrics`, not `ranked_single_metric_comparison`.", "better_capability_id": "scatter.scatter" } ], "ambiguous_questions": [ { "question": "Compare categories by sales.", "candidate_capability_ids": [ "mix.bar", "mix.stacked_bar", "mix.stacked_bar_overlay", "mix.multitier_bar", "mix.pareto" ], "disambiguation_needed": "Clarify whether the intended focus is `ranked_single_metric_comparison`, `composition_within_ranked_totals`, `primary_rank_plus_secondary_marker`, `dimension_period_values_and_delta`, `ranked_contribution_and_cumulative_share`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.barmekko": { "family": "mix", "visual_grammar": "barmekko", "analysis_task_ids": [ "composition_and_mix" ], "selection_tags": [ "two_metric_composition", "price_volume_mix_view" ], "selection_emphasis": "width_metric_times_height_metric", "best_when": "The reader needs variable-width categories where width is an additive quantity, area is an additive value, and height is their derived ratio.", "avoid_when": "Avoid without a meaningful additive width denominator, when area is not additive, or when the derived ratio encoding would be hard to read.", "axis_roles": { "x_width": "width_metric", "y_height": "height_metric", "area": "combined_metric" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "width_metric", "height_metric", "area_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "area_metric", "required": true, "accepted_metric_classes": [ "additive_value" ], "aggregation": "sum" }, { "role": "width_metric", "required": true, "accepted_metric_classes": [ "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [ { "role": "height_metric", "produced_from": [ "area_metric", "width_metric" ], "derivation": "area_metric divided by width_metric" } ], "minimum_source_metric_count": 2, "metric_selection_notes": [ "The plugin uses an additive value as area, an additive width metric such as units, and derives height as area divided by width." ] }, "dimension_roles": [ "width_category", "height_category" ], "dimension_contract": { "required_roles": [ "width_category", "height_category" ], "distinct_dimensions_required": true, "requires_non_bijective_dimension_pair": true, "pair_behavior": "The two dimensions must form an observed cross-classification or hierarchy with more than a one-to-one alias relationship." }, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "mix.marimekko", "scatter.bubble", "mix.stacked_bar_overlay" ], "capability_id": "mix.barmekko", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_current / barmekko", "mix_current / barmekko_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for variable-width composition where width and height are separate metrics.", "requires_question_focus": [ "variable_width_composition", "width_and_height_metrics" ], "reject_decision_cues": [ "asks for two-dimension share only", "asks for bubble relationship", "asks for simple ranked bars" ], "forbidden_question_focus": [ "two_dimension_share", "metric_relationship", "single_metric_rank" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "barmekko" ], "variant_chart_options": [ "barmekko_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "barmekko" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 2, "source_metric_roles": [ { "role": "area_metric", "required": true, "accepted_metric_classes": [ "additive_value" ], "aggregation": "sum" }, { "role": "width_metric", "required": true, "accepted_metric_classes": [ "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [ { "role": "height_metric", "produced_from": [ "area_metric", "width_metric" ], "derivation": "area_metric divided by width_metric" } ], "display_metric_roles": [ "width_metric", "height_metric", "area_metric" ], "metric_selection_notes": [ "The plugin uses an additive value as area, an additive width metric such as units, and derives height as area divided by width." ] }, "dimensions": { "minimum_count": 2, "required_roles": [ "width_category", "height_category" ], "optional_roles": [], "role_requirements": { "width_category": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "width_category", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "width_category", "required": true }, "height_category": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "height_category", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "height_category", "required": true } }, "dimension_contract": { "required_roles": [ "width_category", "height_category" ], "distinct_dimensions_required": true, "requires_non_bijective_dimension_pair": true, "pair_behavior": "The two dimensions must form an observed cross-classification or hierarchy with more than a one-to-one alias relationship." } }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x_width": "width_metric", "y_height": "height_metric", "area": "combined_metric" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs variable-width categories where width is an additive quantity, area is an additive value, and height is their derived ratio.", "reject_when": "Avoid without a meaningful additive width denominator, when area is not additive, or when the derived ratio encoding would be hard to read.", "tie_breakers": [ { "against": "mix.marimekko", "choose_this_when": "The reader needs variable-width categories where width is an additive quantity, area is an additive value, and height is their derived ratio.", "choose_other_when": "The reader needs to see composition across two categorical dimensions where both width and height carry meaning.", "distinguishing_emphasis": { "this": "width_metric_times_height_metric", "other": "two_dimension_share_and_size" } }, { "against": "scatter.bubble", "choose_this_when": "The reader needs variable-width categories where width is an additive quantity, area is an additive value, and height is their derived ratio.", "choose_other_when": "The reader needs x/y relationship plus magnitude encoded by bubble size.", "distinguishing_emphasis": { "this": "width_metric_times_height_metric", "other": "two_metric_relationship_plus_size" } }, { "against": "mix.stacked_bar_overlay", "choose_this_when": "The reader needs variable-width categories where width is an additive quantity, area is an additive value, and height is their derived ratio.", "choose_other_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "distinguishing_emphasis": { "this": "width_metric_times_height_metric", "other": "primary_rank_plus_secondary_marker" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.barmekko` only when the task is one of ['composition_and_mix'] and the required emphasis is `width_metric_times_height_metric`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.barmekko", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_current / barmekko", "mix_current / barmekko_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "metric", "role": "area_metric", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "metric", "role": "width_metric", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.width_metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "width_category", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "height_category", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } } ], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "mix_current / barmekko_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "mix_current / barmekko", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "variable_width", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "mix_current / barmekko_small_multiples", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "variable_width", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show category width and retailer height as a variable-width composition." ], "negative_questions": [ { "question": "Show sales composition across category and retailer.", "why_not": "This asks for `two_dimension_share_and_size`, not `width_metric_times_height_metric`.", "better_capability_id": "mix.marimekko" }, { "question": "Do units and sales share relate, weighted by sales?", "why_not": "This asks for `two_metric_relationship_plus_size`, not `width_metric_times_height_metric`.", "better_capability_id": "scatter.bubble" }, { "question": "Rank category sales while overlaying sales-share context.", "why_not": "This asks for `primary_rank_plus_secondary_marker`, not `width_metric_times_height_metric`.", "better_capability_id": "mix.stacked_bar_overlay" }, { "question": "Show sales contribution as an area trend across months.", "why_not": "This asks for `trend_with_cumulative_or_share_area`, not `width_metric_times_height_metric`.", "better_capability_id": "mix.area" }, { "question": "How did same-product sales mix by category change across the selected months?", "why_not": "This asks for `same_population_composition_change`, not `width_metric_times_height_metric`.", "better_capability_id": "mix.like_for_like_stacked_column" } ], "ambiguous_questions": [ { "question": "Show sales mix and composition.", "candidate_capability_ids": [ "mix.barmekko", "mix.marimekko", "scatter.bubble", "mix.stacked_bar_overlay", "mix.area" ], "disambiguation_needed": "Clarify whether the intended focus is `width_metric_times_height_metric`, `two_dimension_share_and_size`, `two_metric_relationship_plus_size`, `primary_rank_plus_secondary_marker`, `trend_with_cumulative_or_share_area`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.cohort_lost_stacked_column": { "family": "mix", "visual_grammar": "cohort_stacked_column", "analysis_task_ids": [ "cohort_and_population" ], "selection_tags": [ "cohort_contribution", "loss_or_churn" ], "selection_emphasis": "lost_cohort_contribution", "best_when": "The reader needs to see contribution by lost or last-active cohort.", "avoid_when": "Avoid for simple time trend or non-cohort composition.", "axis_roles": { "x": "period", "y": "metric_total", "stack": "lost_or_last_active_cohort" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [ "lost_or_last_active_cohort" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "mix.cohort_since_stacked_column", "mix.like_for_like_column", "mix.stacked_column" ], "capability_id": "mix.cohort_lost_stacked_column", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_cohort / cohort_lost_stacked_column" ], "example_count": 1, "primary_decision_cue": "Question asks how much contribution comes from entities by last active or lost cohort.", "requires_question_focus": [ "lost_cohort", "entity_population_change" ], "reject_decision_cues": [ "asks for first active cohort", "asks for same-population change", "asks for general composition" ], "forbidden_question_focus": [ "since_cohort", "like_for_like_population", "composition_only" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "cohort_lost_stacked_column" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "cohort_lost_stacked_column" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 0, "required_roles": [ "lost_or_last_active_cohort" ], "optional_roles": [], "role_requirements": { "lost_or_last_active_cohort": { "resolution_type": "derived_from_entity_period", "requires_profile_roles": [ "period", "entity_key" ], "output_role": "last active period or lost cohort for each entity", "notes": "Requires a stable entity column and ordered periods.", "role": "lost_or_last_active_cohort", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "period", "y": "metric_total", "stack": "lost_or_last_active_cohort" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs to see contribution by lost or last-active cohort.", "reject_when": "Avoid for simple time trend or non-cohort composition.", "tie_breakers": [ { "against": "mix.cohort_since_stacked_column", "choose_this_when": "The reader needs to see contribution by lost or last-active cohort.", "choose_other_when": "The reader needs to see contribution by first-active cohort over periods.", "distinguishing_emphasis": { "this": "lost_cohort_contribution", "other": "since_cohort_contribution" } }, { "against": "mix.like_for_like_column", "choose_this_when": "The reader needs to see contribution by lost or last-active cohort.", "choose_other_when": "The reader needs total change on a stable like-for-like population.", "distinguishing_emphasis": { "this": "lost_cohort_contribution", "other": "same_population_total_change" } }, { "against": "mix.stacked_column", "choose_this_when": "The reader needs to see contribution by lost or last-active cohort.", "choose_other_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "distinguishing_emphasis": { "this": "lost_cohort_contribution", "other": "composition_change_over_periods" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.cohort_lost_stacked_column` only when the task is one of ['cohort_and_population'] and the required emphasis is `lost_cohort_contribution`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.cohort_lost_stacked_column", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_cohort / cohort_lost_stacked_column" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "lost_or_last_active_cohort", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.derived_dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "mix_cohort / cohort_lost_stacked_column", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "cohort", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "How much sales contribution comes from products by last active month?" ], "negative_questions": [ { "question": "How much sales contribution comes from products by first active month?", "why_not": "This asks for `since_cohort_contribution`, not `lost_cohort_contribution`.", "better_capability_id": "mix.cohort_since_stacked_column" }, { "question": "How did sales change for the same products active in both selected months?", "why_not": "This asks for `same_population_total_change`, not `lost_cohort_contribution`.", "better_capability_id": "mix.like_for_like_column" }, { "question": "Show recent monthly sales mix by category.", "why_not": "This asks for `composition_change_over_periods`, not `lost_cohort_contribution`.", "better_capability_id": "mix.stacked_column" }, { "question": "How did same-product sales mix by category change across the selected months?", "why_not": "This asks for `same_population_composition_change`, not `lost_cohort_contribution`.", "better_capability_id": "mix.like_for_like_stacked_column" } ], "ambiguous_questions": [ { "question": "How did the population change across periods?", "candidate_capability_ids": [ "mix.cohort_lost_stacked_column", "mix.cohort_since_stacked_column", "mix.like_for_like_column", "mix.stacked_column", "mix.like_for_like_stacked_column" ], "disambiguation_needed": "Clarify whether the intended focus is `lost_cohort_contribution`, `since_cohort_contribution`, `same_population_total_change`, `composition_change_over_periods`, `same_population_composition_change`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.cohort_since_stacked_column": { "family": "mix", "visual_grammar": "cohort_stacked_column", "analysis_task_ids": [ "cohort_and_population" ], "selection_tags": [ "cohort_contribution", "retention_or_newness" ], "selection_emphasis": "since_cohort_contribution", "best_when": "The reader needs to see contribution by first-active cohort over periods.", "avoid_when": "Avoid for simple time trend or non-cohort composition.", "axis_roles": { "x": "period", "y": "metric_total", "stack": "first_active_cohort" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [ "first_active_cohort" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "mix.cohort_lost_stacked_column", "mix.like_for_like_column", "mix.stacked_column" ], "capability_id": "mix.cohort_since_stacked_column", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_cohort / cohort_since_stacked_column" ], "example_count": 1, "primary_decision_cue": "Question asks how much contribution comes from entities by first active or since cohort.", "requires_question_focus": [ "since_cohort", "entity_population_change" ], "reject_decision_cues": [ "asks for lost cohort", "asks for same-population change", "asks for period gap" ], "forbidden_question_focus": [ "lost_cohort", "like_for_like_population", "period_gap" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "cohort_since_stacked_column" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "cohort_since_stacked_column" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 0, "required_roles": [ "first_active_cohort" ], "optional_roles": [], "role_requirements": { "first_active_cohort": { "resolution_type": "derived_from_entity_period", "requires_profile_roles": [ "period", "entity_key" ], "output_role": "first active period for each entity", "notes": "Requires a stable entity column and ordered periods.", "role": "first_active_cohort", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "period", "y": "metric_total", "stack": "first_active_cohort" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs to see contribution by first-active cohort over periods.", "reject_when": "Avoid for simple time trend or non-cohort composition.", "tie_breakers": [ { "against": "mix.cohort_lost_stacked_column", "choose_this_when": "The reader needs to see contribution by first-active cohort over periods.", "choose_other_when": "The reader needs to see contribution by lost or last-active cohort.", "distinguishing_emphasis": { "this": "since_cohort_contribution", "other": "lost_cohort_contribution" } }, { "against": "mix.like_for_like_column", "choose_this_when": "The reader needs to see contribution by first-active cohort over periods.", "choose_other_when": "The reader needs total change on a stable like-for-like population.", "distinguishing_emphasis": { "this": "since_cohort_contribution", "other": "same_population_total_change" } }, { "against": "mix.stacked_column", "choose_this_when": "The reader needs to see contribution by first-active cohort over periods.", "choose_other_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "distinguishing_emphasis": { "this": "since_cohort_contribution", "other": "composition_change_over_periods" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.cohort_since_stacked_column` only when the task is one of ['cohort_and_population'] and the required emphasis is `since_cohort_contribution`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.cohort_since_stacked_column", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_cohort / cohort_since_stacked_column" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "first_active_cohort", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.derived_dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "mix_cohort / cohort_since_stacked_column", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "cohort", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "How much sales contribution comes from products by first active month?" ], "negative_questions": [ { "question": "How much sales contribution comes from products by last active month?", "why_not": "This asks for `lost_cohort_contribution`, not `since_cohort_contribution`.", "better_capability_id": "mix.cohort_lost_stacked_column" }, { "question": "How did sales change for the same products active in both selected months?", "why_not": "This asks for `same_population_total_change`, not `since_cohort_contribution`.", "better_capability_id": "mix.like_for_like_column" }, { "question": "Show recent monthly sales mix by category.", "why_not": "This asks for `composition_change_over_periods`, not `since_cohort_contribution`.", "better_capability_id": "mix.stacked_column" }, { "question": "How did same-product sales mix by category change across the selected months?", "why_not": "This asks for `same_population_composition_change`, not `since_cohort_contribution`.", "better_capability_id": "mix.like_for_like_stacked_column" } ], "ambiguous_questions": [ { "question": "How did the population change across periods?", "candidate_capability_ids": [ "mix.cohort_since_stacked_column", "mix.cohort_lost_stacked_column", "mix.like_for_like_column", "mix.stacked_column", "mix.like_for_like_stacked_column" ], "disambiguation_needed": "Clarify whether the intended focus is `since_cohort_contribution`, `lost_cohort_contribution`, `same_population_total_change`, `composition_change_over_periods`, `same_population_composition_change`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.column": { "family": "mix", "visual_grammar": "total_column", "analysis_task_ids": [ "time_and_period_movement" ], "selection_tags": [ "total_over_periods", "period_summary" ], "selection_emphasis": "total_metric_by_period_or_scope", "best_when": "The reader needs a compact total metric column view across selected periods or scopes.", "avoid_when": "Avoid when component composition, relationship, or detailed period path is needed.", "axis_roles": { "x": "period_or_total_scope", "y": "metric" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": false, "minimum_distinct_values": 1, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "mix.column_overlay", "period_comparison.trend", "mix.like_for_like_column", "mix.stacked_column", "mix.timeline" ], "capability_id": "mix.column", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_comparison / mix_comparison_column_total / column_total" ], "example_count": 1, "primary_decision_cue": "Question asks for total metric columns by period or selected scope without composition.", "requires_question_focus": [ "total_metric", "column_summary" ], "reject_decision_cues": [ "asks for component mix", "asks for line trajectory", "asks for related marker metric" ], "forbidden_question_focus": [ "composition", "single_line_trend", "secondary_metric_marker" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 1, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "column_total" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "column_total" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": false, "minimum_distinct_values": 1, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 1, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 0, "required_roles": [], "optional_roles": [], "role_requirements": {}, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "period_or_total_scope", "y": "metric" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs a compact total metric column view across selected periods or scopes.", "reject_when": "Avoid when component composition, relationship, or detailed period path is needed.", "tie_breakers": [ { "against": "mix.column_overlay", "choose_this_when": "The reader needs a compact total metric column view across selected periods or scopes.", "choose_other_when": "The reader needs total metric movement with a related marker shown in the same compact view.", "distinguishing_emphasis": { "this": "total_metric_by_period_or_scope", "other": "total_plus_related_marker" } }, { "against": "period_comparison.trend", "choose_this_when": "The reader needs a compact total metric column view across selected periods or scopes.", "choose_other_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "distinguishing_emphasis": { "this": "total_metric_by_period_or_scope", "other": "trajectory_shape" } }, { "against": "mix.like_for_like_column", "choose_this_when": "The reader needs a compact total metric column view across selected periods or scopes.", "choose_other_when": "The reader needs total change on a stable like-for-like population.", "distinguishing_emphasis": { "this": "total_metric_by_period_or_scope", "other": "same_population_total_change" } }, { "against": "mix.stacked_column", "choose_this_when": "The reader needs a compact total metric column view across selected periods or scopes.", "choose_other_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "distinguishing_emphasis": { "this": "total_metric_by_period_or_scope", "other": "composition_change_over_periods" } }, { "against": "mix.timeline", "choose_this_when": "The reader needs a compact total metric column view across selected periods or scopes.", "choose_other_when": "The reader needs the trend path of the primary mix metric across ordered periods.", "distinguishing_emphasis": { "this": "total_metric_by_period_or_scope", "other": "single_metric_trend_shape" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.column` only when the task is one of ['time_and_period_movement'] and the required emphasis is `total_metric_by_period_or_scope`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.column", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_comparison / mix_comparison_column_total / column_total" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "mix_comparison / mix_comparison_column_total / column_total", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "column", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show total sales by month as compact columns." ], "negative_questions": [ { "question": "Show total monthly sales with sales-share marker context.", "why_not": "This asks for `total_plus_related_marker`, not `total_metric_by_period_or_scope`.", "better_capability_id": "mix.column_overlay" }, { "question": "How did monthly cosmetics sales evolve versus previous year?", "why_not": "This asks for `trajectory_shape`, not `total_metric_by_period_or_scope`.", "better_capability_id": "period_comparison.trend" }, { "question": "How did sales change for the same products active in both selected months?", "why_not": "This asks for `same_population_total_change`, not `total_metric_by_period_or_scope`.", "better_capability_id": "mix.like_for_like_column" }, { "question": "Show recent monthly sales mix by category.", "why_not": "This asks for `composition_change_over_periods`, not `total_metric_by_period_or_scope`.", "better_capability_id": "mix.stacked_column" }, { "question": "Show the single sales trend across months without AC/PY comparison.", "why_not": "This asks for `single_metric_trend_shape`, not `total_metric_by_period_or_scope`.", "better_capability_id": "mix.timeline" } ], "ambiguous_questions": [ { "question": "How did sales change over time?", "candidate_capability_ids": [ "mix.column", "mix.column_overlay", "period_comparison.trend", "mix.like_for_like_column", "mix.stacked_column" ], "disambiguation_needed": "Clarify whether the intended focus is `total_metric_by_period_or_scope`, `total_plus_related_marker`, `trajectory_shape`, `same_population_total_change`, `composition_change_over_periods`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.column_overlay": { "family": "mix", "visual_grammar": "total_column_with_related_metric", "analysis_task_ids": [ "metric_relationship" ], "selection_tags": [ "total_with_secondary_metric", "period_summary" ], "selection_emphasis": "total_plus_related_marker", "best_when": "The reader needs total metric movement with a related marker shown in the same compact view.", "avoid_when": "Avoid when the relationship between metrics is the main analytical object.", "axis_roles": { "x": "period_or_total_scope", "y": "primary_metric", "marker": "related_metric" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": false, "minimum_distinct_values": 1, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric", "related_marker_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" }, { "role": "related_marker_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [], "minimum_source_metric_count": 2, "metric_selection_notes": [] }, "dimension_roles": [], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "mix.column", "mix.stacked_bar_overlay", "scatter.scatter" ], "capability_id": "mix.column_overlay", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_comparison / mix_comparison_column_total / column_total_with_overlay" ], "example_count": 1, "primary_decision_cue": "Question asks for total columns with a secondary related metric marker.", "requires_question_focus": [ "total_metric", "secondary_metric_marker" ], "reject_decision_cues": [ "asks for ranked categories with marker", "asks for two-metric scatter", "asks for plain total" ], "forbidden_question_focus": [ "rank_plus_marker", "scatter_relationship", "plain_total" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 1, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "column_total_with_overlay" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "column_total_with_overlay" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": false, "minimum_distinct_values": 1, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 1, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 2, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" }, { "role": "related_marker_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric", "related_marker_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 0, "required_roles": [], "optional_roles": [], "role_requirements": {}, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "period_or_total_scope", "y": "primary_metric", "marker": "related_metric" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs total metric movement with a related marker shown in the same compact view.", "reject_when": "Avoid when the relationship between metrics is the main analytical object.", "tie_breakers": [ { "against": "mix.column", "choose_this_when": "The reader needs total metric movement with a related marker shown in the same compact view.", "choose_other_when": "The reader needs a compact total metric column view across selected periods or scopes.", "distinguishing_emphasis": { "this": "total_plus_related_marker", "other": "total_metric_by_period_or_scope" } }, { "against": "mix.stacked_bar_overlay", "choose_this_when": "The reader needs total metric movement with a related marker shown in the same compact view.", "choose_other_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "distinguishing_emphasis": { "this": "total_plus_related_marker", "other": "primary_rank_plus_secondary_marker" } }, { "against": "scatter.scatter", "choose_this_when": "The reader needs total metric movement with a related marker shown in the same compact view.", "choose_other_when": "The reader needs to see association, clusters, quadrants, or outliers between two metrics.", "distinguishing_emphasis": { "this": "total_plus_related_marker", "other": "relationship_between_two_metrics" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.column_overlay` only when the task is one of ['metric_relationship'] and the required emphasis is `total_plus_related_marker`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.column_overlay", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_comparison / mix_comparison_column_total / column_total_with_overlay" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "metric", "role": "related_marker_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.related_marker_metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [ { "kind": "variant", "role": "related_marker_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.related_marker_metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "mix_comparison / mix_comparison_column_total / column_total_with_overlay" } ], "artifact_invocation_contracts": [ { "artifact_label": "mix_comparison / mix_comparison_column_total / column_total_with_overlay", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "capability_choice", "layout_variant": "single", "encoding_variant": "overlay", "variant_changes_capability_selection": true, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "related_marker_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.related_marker_metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show total monthly sales with sales-share marker context." ], "negative_questions": [ { "question": "Show total sales by month as compact columns.", "why_not": "This asks for `total_metric_by_period_or_scope`, not `total_plus_related_marker`.", "better_capability_id": "mix.column" }, { "question": "Rank category sales while overlaying sales-share context.", "why_not": "This asks for `primary_rank_plus_secondary_marker`, not `total_plus_related_marker`.", "better_capability_id": "mix.stacked_bar_overlay" }, { "question": "Do units and sales share relate without size encoding?", "why_not": "This asks for `relationship_between_two_metrics`, not `total_plus_related_marker`.", "better_capability_id": "scatter.scatter" }, { "question": "Do units and sales share relate, weighted by sales?", "why_not": "This asks for `two_metric_relationship_plus_size`, not `total_plus_related_marker`.", "better_capability_id": "scatter.bubble" } ], "ambiguous_questions": [ { "question": "Show the relationship between metrics.", "candidate_capability_ids": [ "mix.column_overlay", "mix.column", "mix.stacked_bar_overlay", "scatter.scatter", "scatter.bubble" ], "disambiguation_needed": "Clarify whether the intended focus is `total_plus_related_marker`, `total_metric_by_period_or_scope`, `primary_rank_plus_secondary_marker`, `relationship_between_two_metrics`, `two_metric_relationship_plus_size`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.like_for_like_column": { "family": "mix", "visual_grammar": "like_for_like_total_column", "analysis_task_ids": [ "cohort_and_population" ], "selection_tags": [ "like_for_like_comparison" ], "selection_emphasis": "same_population_total_change", "best_when": "The reader needs total change on a stable like-for-like population.", "avoid_when": "Avoid when population churn or mix composition is the main finding.", "axis_roles": { "x": "comparison_period", "y": "metric" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [ "stable_population_flag" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "mix.column", "mix.like_for_like_stacked_column", "mix.cohort_since_stacked_column", "mix.cohort_lost_stacked_column" ], "capability_id": "mix.like_for_like_column", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_like_for_like / like_for_like_column_total" ], "example_count": 1, "primary_decision_cue": "Question asks for total change among the same entities present in both periods.", "requires_question_focus": [ "like_for_like_population", "total_change" ], "reject_decision_cues": [ "asks for composition change", "asks for new or lost cohorts", "asks for all-population total" ], "forbidden_question_focus": [ "like_for_like_composition", "cohort_change", "all_population_total" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "like_for_like_column_total" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "like_for_like_column_total" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 0, "required_roles": [ "stable_population_flag" ], "optional_roles": [], "role_requirements": { "stable_population_flag": { "resolution_type": "derived_from_entity_period", "requires_profile_roles": [ "period", "entity_key" ], "output_role": "boolean flag for entities present in both selected periods", "notes": "Requires a stable entity column plus two period windows.", "role": "stable_population_flag", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "comparison_period", "y": "metric" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs total change on a stable like-for-like population.", "reject_when": "Avoid when population churn or mix composition is the main finding.", "tie_breakers": [ { "against": "mix.column", "choose_this_when": "The reader needs total change on a stable like-for-like population.", "choose_other_when": "The reader needs a compact total metric column view across selected periods or scopes.", "distinguishing_emphasis": { "this": "same_population_total_change", "other": "total_metric_by_period_or_scope" } }, { "against": "mix.like_for_like_stacked_column", "choose_this_when": "The reader needs total change on a stable like-for-like population.", "choose_other_when": "The reader needs like-for-like total movement and composition together.", "distinguishing_emphasis": { "this": "same_population_total_change", "other": "same_population_composition_change" } }, { "against": "mix.cohort_since_stacked_column", "choose_this_when": "The reader needs total change on a stable like-for-like population.", "choose_other_when": "The reader needs to see contribution by first-active cohort over periods.", "distinguishing_emphasis": { "this": "same_population_total_change", "other": "since_cohort_contribution" } }, { "against": "mix.cohort_lost_stacked_column", "choose_this_when": "The reader needs total change on a stable like-for-like population.", "choose_other_when": "The reader needs to see contribution by lost or last-active cohort.", "distinguishing_emphasis": { "this": "same_population_total_change", "other": "lost_cohort_contribution" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.like_for_like_column` only when the task is one of ['cohort_and_population'] and the required emphasis is `same_population_total_change`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.like_for_like_column", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_like_for_like / like_for_like_column_total" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "stable_population_flag", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.like_for_like", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "mix_like_for_like / like_for_like_column_total", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "like_for_like", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "How did sales change for the same products active in both selected months?" ], "negative_questions": [ { "question": "Show total sales by month as compact columns.", "why_not": "This asks for `total_metric_by_period_or_scope`, not `same_population_total_change`.", "better_capability_id": "mix.column" }, { "question": "How did same-product sales mix by category change across the selected months?", "why_not": "This asks for `same_population_composition_change`, not `same_population_total_change`.", "better_capability_id": "mix.like_for_like_stacked_column" }, { "question": "How much sales contribution comes from products by first active month?", "why_not": "This asks for `since_cohort_contribution`, not `same_population_total_change`.", "better_capability_id": "mix.cohort_since_stacked_column" }, { "question": "How much sales contribution comes from products by last active month?", "why_not": "This asks for `lost_cohort_contribution`, not `same_population_total_change`.", "better_capability_id": "mix.cohort_lost_stacked_column" } ], "ambiguous_questions": [ { "question": "How did the population change across periods?", "candidate_capability_ids": [ "mix.like_for_like_column", "mix.column", "mix.like_for_like_stacked_column", "mix.cohort_since_stacked_column", "mix.cohort_lost_stacked_column" ], "disambiguation_needed": "Clarify whether the intended focus is `same_population_total_change`, `total_metric_by_period_or_scope`, `same_population_composition_change`, `since_cohort_contribution`, `lost_cohort_contribution`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.like_for_like_stacked_column": { "family": "mix", "visual_grammar": "like_for_like_stacked_column", "analysis_task_ids": [ "composition_and_mix", "cohort_and_population" ], "selection_tags": [ "like_for_like_comparison", "mix_shift" ], "selection_emphasis": "same_population_composition_change", "best_when": "The reader needs like-for-like total movement and composition together.", "avoid_when": "Avoid when the population is not stable or exact detail is required.", "axis_roles": { "x": "comparison_period", "y": "metric_total", "stack": "component_dimension" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [ "stable_population_flag", "component_dimension" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "mix.like_for_like_column", "mix.stacked_column" ], "capability_id": "mix.like_for_like_stacked_column", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_like_for_like / like_for_like_stacked_column" ], "example_count": 1, "primary_decision_cue": "Question asks for mix change among the same entities present in both periods.", "requires_question_focus": [ "like_for_like_population", "composition_change" ], "reject_decision_cues": [ "asks for total-only change", "asks for lost/since cohorts", "asks for simple stacked composition" ], "forbidden_question_focus": [ "like_for_like_total", "cohort_change", "all_population_composition" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "like_for_like_stacked_column" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "like_for_like_stacked_column" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 1, "required_roles": [ "stable_population_flag", "component_dimension" ], "optional_roles": [], "role_requirements": { "stable_population_flag": { "resolution_type": "derived_from_entity_period", "requires_profile_roles": [ "period", "entity_key" ], "output_role": "boolean flag for entities present in both selected periods", "notes": "Requires a stable entity column plus two period windows.", "role": "stable_population_flag", "required": true }, "component_dimension": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "component_dimension", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "component_dimension", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "comparison_period", "y": "metric_total", "stack": "component_dimension" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs like-for-like total movement and composition together.", "reject_when": "Avoid when the population is not stable or exact detail is required.", "tie_breakers": [ { "against": "mix.like_for_like_column", "choose_this_when": "The reader needs like-for-like total movement and composition together.", "choose_other_when": "The reader needs total change on a stable like-for-like population.", "distinguishing_emphasis": { "this": "same_population_composition_change", "other": "same_population_total_change" } }, { "against": "mix.stacked_column", "choose_this_when": "The reader needs like-for-like total movement and composition together.", "choose_other_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "distinguishing_emphasis": { "this": "same_population_composition_change", "other": "composition_change_over_periods" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.like_for_like_stacked_column` only when the task is one of ['composition_and_mix', 'cohort_and_population'] and the required emphasis is `same_population_composition_change`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.like_for_like_stacked_column", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_like_for_like / like_for_like_stacked_column" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "stable_population_flag", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.like_for_like", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "component_dimension", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "mix_like_for_like / like_for_like_stacked_column", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "like_for_like", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "How did same-product sales mix by category change across the selected months?" ], "negative_questions": [ { "question": "How did sales change for the same products active in both selected months?", "why_not": "This asks for `same_population_total_change`, not `same_population_composition_change`.", "better_capability_id": "mix.like_for_like_column" }, { "question": "Show recent monthly sales mix by category.", "why_not": "This asks for `composition_change_over_periods`, not `same_population_composition_change`.", "better_capability_id": "mix.stacked_column" }, { "question": "Show sales contribution as an area trend across months.", "why_not": "This asks for `trend_with_cumulative_or_share_area`, not `same_population_composition_change`.", "better_capability_id": "mix.area" }, { "question": "Show category width and retailer height as a variable-width composition.", "why_not": "This asks for `width_metric_times_height_metric`, not `same_population_composition_change`.", "better_capability_id": "mix.barmekko" }, { "question": "Show sales composition across category and retailer.", "why_not": "This asks for `two_dimension_share_and_size`, not `same_population_composition_change`.", "better_capability_id": "mix.marimekko" } ], "ambiguous_questions": [ { "question": "Show sales mix and composition.", "candidate_capability_ids": [ "mix.like_for_like_stacked_column", "mix.like_for_like_column", "mix.stacked_column", "mix.area", "mix.barmekko" ], "disambiguation_needed": "Clarify whether the intended focus is `same_population_composition_change`, `same_population_total_change`, `composition_change_over_periods`, `trend_with_cumulative_or_share_area`, `width_metric_times_height_metric`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.marimekko": { "family": "mix", "visual_grammar": "marimekko", "analysis_task_ids": [ "composition_and_mix" ], "selection_tags": [ "two_dimension_composition", "mix_structure" ], "selection_emphasis": "two_dimension_share_and_size", "best_when": "The reader needs to see composition across two categorical dimensions where both width and height carry meaning.", "avoid_when": "Avoid when categories are too many, exact comparison matters, or the question is a simple ranking.", "axis_roles": { "x_width": "category_share_or_size", "y_stack": "second_category_share", "area": "metric" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [ "width_category", "stack_category", "optional_panel" ], "dimension_contract": { "required_roles": [ "width_category", "stack_category" ], "distinct_dimensions_required": true, "requires_non_bijective_dimension_pair": true, "pair_behavior": "The two dimensions must form an observed cross-classification or hierarchy with more than a one-to-one alias relationship." }, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "mix.barmekko", "mix.stacked_bar", "mix.stacked_pareto", "mix.multitier_bar" ], "capability_id": "mix.marimekko", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_current / marimekko", "mix_current / marimekko_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for composition across two categorical dimensions using segment share and size.", "requires_question_focus": [ "two_dimension_share", "composition_size" ], "reject_decision_cues": [ "asks for separate width and height metrics", "asks for ranked bars", "asks for period variance" ], "forbidden_question_focus": [ "width_height_metrics", "single_metric_rank", "period_variance" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "marimekko" ], "variant_chart_options": [ "marimekko_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "marimekko" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 2, "required_roles": [ "width_category", "stack_category" ], "optional_roles": [ "optional_panel" ], "role_requirements": { "width_category": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "width_category", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "width_category", "required": true }, "stack_category": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "stack_category", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "stack_category", "required": true }, "optional_panel": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "panel", "notes": "Fallback direct dimension role; review this role if it becomes selection-critical.", "role": "optional_panel", "required": false } }, "dimension_contract": { "required_roles": [ "width_category", "stack_category" ], "distinct_dimensions_required": true, "requires_non_bijective_dimension_pair": true, "pair_behavior": "The two dimensions must form an observed cross-classification or hierarchy with more than a one-to-one alias relationship." } }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x_width": "category_share_or_size", "y_stack": "second_category_share", "area": "metric" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs to see composition across two categorical dimensions where both width and height carry meaning.", "reject_when": "Avoid when categories are too many, exact comparison matters, or the question is a simple ranking.", "tie_breakers": [ { "against": "mix.barmekko", "choose_this_when": "The reader needs to see composition across two categorical dimensions where both width and height carry meaning.", "choose_other_when": "The reader needs variable-width categories where width is an additive quantity, area is an additive value, and height is their derived ratio.", "distinguishing_emphasis": { "this": "two_dimension_share_and_size", "other": "width_metric_times_height_metric" } }, { "against": "mix.stacked_bar", "choose_this_when": "The reader needs to see composition across two categorical dimensions where both width and height carry meaning.", "choose_other_when": "The reader needs both total size and component composition across categories.", "distinguishing_emphasis": { "this": "two_dimension_share_and_size", "other": "composition_within_ranked_totals" } }, { "against": "mix.stacked_pareto", "choose_this_when": "The reader needs to see composition across two categorical dimensions where both width and height carry meaning.", "choose_other_when": "The reader needs Pareto concentration plus stacked composition by another dimension or class.", "distinguishing_emphasis": { "this": "two_dimension_share_and_size", "other": "concentration_with_component_breakdown" } }, { "against": "mix.multitier_bar", "choose_this_when": "The reader needs to see composition across two categorical dimensions where both width and height carry meaning.", "choose_other_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "distinguishing_emphasis": { "this": "two_dimension_share_and_size", "other": "dimension_period_values_and_delta" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.marimekko` only when the task is one of ['composition_and_mix'] and the required emphasis is `two_dimension_share_and_size`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.marimekko", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_current / marimekko", "mix_current / marimekko_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "width_category", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "stack_category", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "dimension", "role": "optional_panel", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "mix_current / marimekko_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "mix_current / marimekko", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "variable_width", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "mix_current / marimekko_small_multiples", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "variable_width", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show sales composition across category and retailer." ], "negative_questions": [ { "question": "Show category width and retailer height as a variable-width composition.", "why_not": "This asks for `width_metric_times_height_metric`, not `two_dimension_share_and_size`.", "better_capability_id": "mix.barmekko" }, { "question": "Show sales totals and composition by retailer within categories.", "why_not": "This asks for `composition_within_ranked_totals`, not `two_dimension_share_and_size`.", "better_capability_id": "mix.stacked_bar" }, { "question": "Show concentration and component composition together.", "why_not": "This asks for `concentration_with_component_breakdown`, not `two_dimension_share_and_size`.", "better_capability_id": "mix.stacked_pareto" }, { "question": "Show category sales in two periods and the difference, split into retailer panels.", "why_not": "This asks for `dimension_period_values_and_delta`, not `two_dimension_share_and_size`.", "better_capability_id": "mix.multitier_bar" }, { "question": "Show sales contribution as an area trend across months.", "why_not": "This asks for `trend_with_cumulative_or_share_area`, not `two_dimension_share_and_size`.", "better_capability_id": "mix.area" } ], "ambiguous_questions": [ { "question": "Show sales mix and composition.", "candidate_capability_ids": [ "mix.marimekko", "mix.barmekko", "mix.stacked_bar", "mix.stacked_pareto", "mix.multitier_bar" ], "disambiguation_needed": "Clarify whether the intended focus is `two_dimension_share_and_size`, `width_metric_times_height_metric`, `composition_within_ranked_totals`, `concentration_with_component_breakdown`, `dimension_period_values_and_delta`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.multitier_bar": { "family": "mix", "visual_grammar": "period_comparison_multitier_bar", "analysis_task_ids": [ "time_and_period_movement", "ranking_and_comparison" ], "selection_tags": [ "period_movement", "ranked_gap_comparison", "two_point_gap" ], "selection_emphasis": "dimension_period_values_and_delta", "best_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "avoid_when": "Avoid when the question is categorical hierarchy, composition, single-period ranking, or continuous trend shape.", "axis_roles": { "x": "baseline_current_and_delta_metrics", "y": "dimension_member", "panel": "optional_second_dimension" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "baseline_period_metric", "current_period_metric", "delta_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" } ], "minimum_source_metric_count": 1, "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimension_roles": [ "dimension_member", "optional_panel" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "period_comparison.dot", "period_comparison.slope", "period_comparison.multitier_column", "mix.bar", "mix.marimekko", "mix.stacked_bar" ], "capability_id": "mix.multitier_bar", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_comparison / multitier_bar", "mix_comparison / multitier_bar_dimension_panels", "mix_comparison / multitier_bar_two_dimension" ], "example_count": 3, "primary_decision_cue": "Question asks for one dimension's values in two periods and the delta, optionally by panels.", "requires_question_focus": [ "dimension_period_delta", "current_vs_baseline_values" ], "reject_decision_cues": [ "asks for continuous trend", "asks for composition", "asks for root-cause bridge" ], "forbidden_question_focus": [ "single_line_trend", "composition", "root_cause_variance" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "multitier_bar" ], "variant_chart_options": [ "multitier_bar_dimension_panels", "multitier_bar_two_dimension" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "multitier_bar" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" } ], "display_metric_roles": [ "baseline_period_metric", "current_period_metric", "delta_metric" ], "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimensions": { "minimum_count": 1, "required_roles": [ "dimension_member" ], "optional_roles": [ "optional_panel" ], "role_requirements": { "dimension_member": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "dimension_member", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "dimension_member", "required": true }, "optional_panel": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "panel", "notes": "Fallback direct dimension role; review this role if it becomes selection-critical.", "role": "optional_panel", "required": false } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "baseline_current_and_delta_metrics", "y": "dimension_member", "panel": "optional_second_dimension" } }, "implementation_evidence": { "gallery_example_count": 3, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "reject_when": "Avoid when the question is categorical hierarchy, composition, single-period ranking, or continuous trend shape.", "tie_breakers": [ { "against": "period_comparison.dot", "choose_this_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "choose_other_when": "The reader needs a low-clutter comparison of two values across categories, panels, or periods.", "distinguishing_emphasis": { "this": "dimension_period_values_and_delta", "other": "gap_between_two_values" } }, { "against": "period_comparison.slope", "choose_this_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "choose_other_when": "The reader needs direction and magnitude of change between two endpoints, especially across multiple comparable items.", "distinguishing_emphasis": { "this": "dimension_period_values_and_delta", "other": "endpoint_direction_and_relative_change" } }, { "against": "period_comparison.multitier_column", "choose_this_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "choose_other_when": "The reader needs a compact executive AC/PY period comparison with clear column contrast.", "distinguishing_emphasis": { "this": "dimension_period_values_and_delta", "other": "compact_side_by_side_period_comparison" } }, { "against": "mix.bar", "choose_this_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "choose_other_when": "The reader needs a sorted comparison of one additive metric across items for one selected scope or period.", "distinguishing_emphasis": { "this": "dimension_period_values_and_delta", "other": "ranked_single_metric_comparison" } }, { "against": "mix.marimekko", "choose_this_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "choose_other_when": "The reader needs to see composition across two categorical dimensions where both width and height carry meaning.", "distinguishing_emphasis": { "this": "dimension_period_values_and_delta", "other": "two_dimension_share_and_size" } }, { "against": "mix.stacked_bar", "choose_this_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "choose_other_when": "The reader needs both total size and component composition across categories.", "distinguishing_emphasis": { "this": "dimension_period_values_and_delta", "other": "composition_within_ranked_totals" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.multitier_bar` only when the task is one of ['time_and_period_movement', 'ranking_and_comparison'] and the required emphasis is `dimension_period_values_and_delta`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.multitier_bar", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_comparison / multitier_bar", "mix_comparison / multitier_bar_dimension_panels", "mix_comparison / multitier_bar_two_dimension" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "comparison_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "dimension_member", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "dimension", "role": "optional_panel", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "mix_comparison / multitier_bar_dimension_panels" }, { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "mix_comparison / multitier_bar_two_dimension" } ], "artifact_invocation_contracts": [ { "artifact_label": "mix_comparison / multitier_bar", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "multitier", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "mix_comparison / multitier_bar_dimension_panels", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "panelled", "encoding_variant": "multitier", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] }, { "artifact_label": "mix_comparison / multitier_bar_two_dimension", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "panelled", "encoding_variant": "multitier", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 3, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show category sales in two periods and the difference, split into retailer panels." ], "negative_questions": [ { "question": "Compare AC/PY sales gaps across categories with low clutter.", "why_not": "This asks for `gap_between_two_values`, not `dimension_period_values_and_delta`.", "better_capability_id": "period_comparison.dot" }, { "question": "Show endpoint direction and magnitude of category sales changes.", "why_not": "This asks for `endpoint_direction_and_relative_change`, not `dimension_period_values_and_delta`.", "better_capability_id": "period_comparison.slope" }, { "question": "Show compact AC/PY monthly sales columns.", "why_not": "This asks for `compact_side_by_side_period_comparison`, not `dimension_period_values_and_delta`.", "better_capability_id": "period_comparison.multitier_column" }, { "question": "Rank categories by sales for a selected scope.", "why_not": "This asks for `ranked_single_metric_comparison`, not `dimension_period_values_and_delta`.", "better_capability_id": "mix.bar" }, { "question": "Show sales composition across category and retailer.", "why_not": "This asks for `two_dimension_share_and_size`, not `dimension_period_values_and_delta`.", "better_capability_id": "mix.marimekko" } ], "ambiguous_questions": [ { "question": "How did sales change over time?", "candidate_capability_ids": [ "mix.multitier_bar", "period_comparison.dot", "period_comparison.slope", "period_comparison.multitier_column", "mix.bar" ], "disambiguation_needed": "Clarify whether the intended focus is `dimension_period_values_and_delta`, `gap_between_two_values`, `endpoint_direction_and_relative_change`, `compact_side_by_side_period_comparison`, `ranked_single_metric_comparison`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.pareto": { "family": "mix", "visual_grammar": "pareto", "analysis_task_ids": [ "ranking_and_comparison" ], "selection_tags": [ "concentration", "rank_category_values" ], "selection_emphasis": "ranked_contribution_and_cumulative_share", "best_when": "The reader needs to identify the few categories that explain most of the metric.", "avoid_when": "Avoid when component composition, period movement, or nested hierarchy is the main message.", "axis_roles": { "x": "ranked_category", "y": "metric", "line": "cumulative_share_optional" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [ "category" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "mix.bar", "mix.stacked_pareto" ], "capability_id": "mix.pareto", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_current / pareto" ], "example_count": 1, "primary_decision_cue": "Question asks which few items explain most of the total using cumulative share.", "requires_question_focus": [ "pareto_concentration", "cumulative_share" ], "reject_decision_cues": [ "asks for component breakdown", "asks for simple ranking only", "asks for time trend" ], "forbidden_question_focus": [ "component_breakdown", "single_metric_rank", "time_trend" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "pareto" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "pareto" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 1, "required_roles": [ "category" ], "optional_roles": [], "role_requirements": { "category": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "category", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "category", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "ranked_category", "y": "metric", "line": "cumulative_share_optional" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs to identify the few categories that explain most of the metric.", "reject_when": "Avoid when component composition, period movement, or nested hierarchy is the main message.", "tie_breakers": [ { "against": "mix.bar", "choose_this_when": "The reader needs to identify the few categories that explain most of the metric.", "choose_other_when": "The reader needs a sorted comparison of one additive metric across items for one selected scope or period.", "distinguishing_emphasis": { "this": "ranked_contribution_and_cumulative_share", "other": "ranked_single_metric_comparison" } }, { "against": "mix.stacked_pareto", "choose_this_when": "The reader needs to identify the few categories that explain most of the metric.", "choose_other_when": "The reader needs Pareto concentration plus stacked composition by another dimension or class.", "distinguishing_emphasis": { "this": "ranked_contribution_and_cumulative_share", "other": "concentration_with_component_breakdown" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.pareto` only when the task is one of ['ranking_and_comparison'] and the required emphasis is `ranked_contribution_and_cumulative_share`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.pareto", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_current / pareto" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "category", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } } ], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "mix_current / pareto", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "pareto", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Find the few categories that explain most sales." ], "negative_questions": [ { "question": "Rank categories by sales for a selected scope.", "why_not": "This asks for `ranked_single_metric_comparison`, not `ranked_contribution_and_cumulative_share`.", "better_capability_id": "mix.bar" }, { "question": "Show concentration and component composition together.", "why_not": "This asks for `concentration_with_component_breakdown`, not `ranked_contribution_and_cumulative_share`.", "better_capability_id": "mix.stacked_pareto" }, { "question": "Show category sales in two periods and the difference, split into retailer panels.", "why_not": "This asks for `dimension_period_values_and_delta`, not `ranked_contribution_and_cumulative_share`.", "better_capability_id": "mix.multitier_bar" }, { "question": "Give exact current, prior-year, delta, and percent-delta sales values.", "why_not": "This asks for `summary_exact_values`, not `ranked_contribution_and_cumulative_share`.", "better_capability_id": "period_comparison.comparison_table" }, { "question": "Compare AC/PY sales gaps across categories with low clutter.", "why_not": "This asks for `gap_between_two_values`, not `ranked_contribution_and_cumulative_share`.", "better_capability_id": "period_comparison.dot" } ], "ambiguous_questions": [ { "question": "Compare categories by sales.", "candidate_capability_ids": [ "mix.pareto", "mix.bar", "mix.stacked_pareto", "mix.multitier_bar", "period_comparison.comparison_table" ], "disambiguation_needed": "Clarify whether the intended focus is `ranked_contribution_and_cumulative_share`, `ranked_single_metric_comparison`, `concentration_with_component_breakdown`, `dimension_period_values_and_delta`, `summary_exact_values`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.stacked_bar": { "family": "mix", "visual_grammar": "stacked_bar", "analysis_task_ids": [ "composition_and_mix" ], "selection_tags": [ "composition", "part_to_whole_by_category" ], "selection_emphasis": "composition_within_ranked_totals", "best_when": "The reader needs both total size and component composition across categories.", "avoid_when": "Avoid when exact component comparison or time trend is more important than composition.", "axis_roles": { "x": "metric_total", "y": "category", "stack": "component_dimension" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [ "category", "component_category" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "mix.bar", "mix.multitier_bar", "mix.stacked_bar_overlay", "mix.marimekko", "mix.stacked_column", "mix.stacked_pareto" ], "capability_id": "mix.stacked_bar", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_current / stacked_bar", "mix_current / stacked_bar_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for composition within ranked category totals.", "requires_question_focus": [ "ranked_composition", "stacked_total" ], "reject_decision_cues": [ "asks for simple rank only", "asks for related marker", "asks for two-period delta" ], "forbidden_question_focus": [ "single_metric_rank", "secondary_metric_marker", "period_delta" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "stacked_bar" ], "variant_chart_options": [ "stacked_bar_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "stacked_bar" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 2, "required_roles": [ "category", "component_category" ], "optional_roles": [], "role_requirements": { "category": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "category", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "category", "required": true }, "component_category": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "component_category", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "component_category", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "metric_total", "y": "category", "stack": "component_dimension" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs both total size and component composition across categories.", "reject_when": "Avoid when exact component comparison or time trend is more important than composition.", "tie_breakers": [ { "against": "mix.bar", "choose_this_when": "The reader needs both total size and component composition across categories.", "choose_other_when": "The reader needs a sorted comparison of one additive metric across items for one selected scope or period.", "distinguishing_emphasis": { "this": "composition_within_ranked_totals", "other": "ranked_single_metric_comparison" } }, { "against": "mix.multitier_bar", "choose_this_when": "The reader needs both total size and component composition across categories.", "choose_other_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "distinguishing_emphasis": { "this": "composition_within_ranked_totals", "other": "dimension_period_values_and_delta" } }, { "against": "mix.stacked_bar_overlay", "choose_this_when": "The reader needs both total size and component composition across categories.", "choose_other_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "distinguishing_emphasis": { "this": "composition_within_ranked_totals", "other": "primary_rank_plus_secondary_marker" } }, { "against": "mix.marimekko", "choose_this_when": "The reader needs both total size and component composition across categories.", "choose_other_when": "The reader needs to see composition across two categorical dimensions where both width and height carry meaning.", "distinguishing_emphasis": { "this": "composition_within_ranked_totals", "other": "two_dimension_share_and_size" } }, { "against": "mix.stacked_column", "choose_this_when": "The reader needs both total size and component composition across categories.", "choose_other_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "distinguishing_emphasis": { "this": "composition_within_ranked_totals", "other": "composition_change_over_periods" } }, { "against": "mix.stacked_pareto", "choose_this_when": "The reader needs both total size and component composition across categories.", "choose_other_when": "The reader needs Pareto concentration plus stacked composition by another dimension or class.", "distinguishing_emphasis": { "this": "composition_within_ranked_totals", "other": "concentration_with_component_breakdown" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.stacked_bar` only when the task is one of ['composition_and_mix'] and the required emphasis is `composition_within_ranked_totals`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.stacked_bar", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_current / stacked_bar", "mix_current / stacked_bar_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "category", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "component_category", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } } ], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "mix_current / stacked_bar_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "mix_current / stacked_bar", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "stacked", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "mix_current / stacked_bar_small_multiples", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "stacked", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show sales totals and composition by retailer within categories." ], "negative_questions": [ { "question": "Rank categories by sales for a selected scope.", "why_not": "This asks for `ranked_single_metric_comparison`, not `composition_within_ranked_totals`.", "better_capability_id": "mix.bar" }, { "question": "Show category sales in two periods and the difference, split into retailer panels.", "why_not": "This asks for `dimension_period_values_and_delta`, not `composition_within_ranked_totals`.", "better_capability_id": "mix.multitier_bar" }, { "question": "Rank category sales while overlaying sales-share context.", "why_not": "This asks for `primary_rank_plus_secondary_marker`, not `composition_within_ranked_totals`.", "better_capability_id": "mix.stacked_bar_overlay" }, { "question": "Show sales composition across category and retailer.", "why_not": "This asks for `two_dimension_share_and_size`, not `composition_within_ranked_totals`.", "better_capability_id": "mix.marimekko" }, { "question": "Show recent monthly sales mix by category.", "why_not": "This asks for `composition_change_over_periods`, not `composition_within_ranked_totals`.", "better_capability_id": "mix.stacked_column" } ], "ambiguous_questions": [ { "question": "Show sales mix and composition.", "candidate_capability_ids": [ "mix.stacked_bar", "mix.bar", "mix.multitier_bar", "mix.stacked_bar_overlay", "mix.marimekko" ], "disambiguation_needed": "Clarify whether the intended focus is `composition_within_ranked_totals`, `ranked_single_metric_comparison`, `dimension_period_values_and_delta`, `primary_rank_plus_secondary_marker`, `two_dimension_share_and_size`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.stacked_bar_overlay": { "family": "mix", "visual_grammar": "bar_with_related_metric_marker", "analysis_task_ids": [ "metric_relationship" ], "selection_tags": [ "rank_with_secondary_metric", "relationship_support" ], "selection_emphasis": "primary_rank_plus_secondary_marker", "best_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "avoid_when": "Avoid when the secondary metric deserves a full relationship plot or when composition is the point.", "axis_roles": { "x": "primary_metric", "y": "category", "marker": "related_metric" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric", "related_marker_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" }, { "role": "related_marker_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [], "minimum_source_metric_count": 2, "metric_selection_notes": [] }, "dimension_roles": [ "category" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "mix.bar", "scatter.scatter", "scatter.bubble", "mix.barmekko", "mix.column_overlay", "mix.stacked_bar" ], "capability_id": "mix.stacked_bar_overlay", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_comparison / related_metrics_bar", "mix_comparison / related_metrics_bar_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks to rank categories by a primary metric while overlaying a secondary marker.", "requires_question_focus": [ "rank_plus_marker", "secondary_metric_marker" ], "reject_decision_cues": [ "asks for total column marker", "asks for scatter relationship", "asks for stacked composition" ], "forbidden_question_focus": [ "total_plus_marker", "scatter_relationship", "composition" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "related_metrics_bar" ], "variant_chart_options": [ "related_metrics_bar_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "related_metrics_bar" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 2, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" }, { "role": "related_marker_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric", "related_marker_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 1, "required_roles": [ "category" ], "optional_roles": [], "role_requirements": { "category": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "category", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "category", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "primary_metric", "y": "category", "marker": "related_metric" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "reject_when": "Avoid when the secondary metric deserves a full relationship plot or when composition is the point.", "tie_breakers": [ { "against": "mix.bar", "choose_this_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "choose_other_when": "The reader needs a sorted comparison of one additive metric across items for one selected scope or period.", "distinguishing_emphasis": { "this": "primary_rank_plus_secondary_marker", "other": "ranked_single_metric_comparison" } }, { "against": "scatter.scatter", "choose_this_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "choose_other_when": "The reader needs to see association, clusters, quadrants, or outliers between two metrics.", "distinguishing_emphasis": { "this": "primary_rank_plus_secondary_marker", "other": "relationship_between_two_metrics" } }, { "against": "scatter.bubble", "choose_this_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "choose_other_when": "The reader needs x/y relationship plus magnitude encoded by bubble size.", "distinguishing_emphasis": { "this": "primary_rank_plus_secondary_marker", "other": "two_metric_relationship_plus_size" } }, { "against": "mix.barmekko", "choose_this_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "choose_other_when": "The reader needs variable-width categories where width is an additive quantity, area is an additive value, and height is their derived ratio.", "distinguishing_emphasis": { "this": "primary_rank_plus_secondary_marker", "other": "width_metric_times_height_metric" } }, { "against": "mix.column_overlay", "choose_this_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "choose_other_when": "The reader needs total metric movement with a related marker shown in the same compact view.", "distinguishing_emphasis": { "this": "primary_rank_plus_secondary_marker", "other": "total_plus_related_marker" } }, { "against": "mix.stacked_bar", "choose_this_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "choose_other_when": "The reader needs both total size and component composition across categories.", "distinguishing_emphasis": { "this": "primary_rank_plus_secondary_marker", "other": "composition_within_ranked_totals" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.stacked_bar_overlay` only when the task is one of ['metric_relationship'] and the required emphasis is `primary_rank_plus_secondary_marker`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.stacked_bar_overlay", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_comparison / related_metrics_bar", "mix_comparison / related_metrics_bar_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "metric", "role": "related_marker_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.related_marker_metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "category", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } } ], "variant_role_contracts": [ { "kind": "variant", "role": "related_marker_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.related_marker_metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "mix_comparison / related_metrics_bar" }, { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "mix_comparison / related_metrics_bar_small_multiples" }, { "kind": "variant", "role": "related_marker_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.related_marker_metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "mix_comparison / related_metrics_bar_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "mix_comparison / related_metrics_bar", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "capability_choice", "layout_variant": "single", "encoding_variant": "overlay", "variant_changes_capability_selection": true, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "related_marker_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.related_marker_metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] }, { "artifact_label": "mix_comparison / related_metrics_bar_small_multiples", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "capability_choice", "layout_variant": "small_multiples", "encoding_variant": "overlay", "variant_changes_capability_selection": true, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "variant", "role": "related_marker_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.related_marker_metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Rank category sales while overlaying sales-share context." ], "negative_questions": [ { "question": "Rank categories by sales for a selected scope.", "why_not": "This asks for `ranked_single_metric_comparison`, not `primary_rank_plus_secondary_marker`.", "better_capability_id": "mix.bar" }, { "question": "Do units and sales share relate without size encoding?", "why_not": "This asks for `relationship_between_two_metrics`, not `primary_rank_plus_secondary_marker`.", "better_capability_id": "scatter.scatter" }, { "question": "Do units and sales share relate, weighted by sales?", "why_not": "This asks for `two_metric_relationship_plus_size`, not `primary_rank_plus_secondary_marker`.", "better_capability_id": "scatter.bubble" }, { "question": "Show category width and retailer height as a variable-width composition.", "why_not": "This asks for `width_metric_times_height_metric`, not `primary_rank_plus_secondary_marker`.", "better_capability_id": "mix.barmekko" }, { "question": "Show total monthly sales with sales-share marker context.", "why_not": "This asks for `total_plus_related_marker`, not `primary_rank_plus_secondary_marker`.", "better_capability_id": "mix.column_overlay" } ], "ambiguous_questions": [ { "question": "Show the relationship between metrics.", "candidate_capability_ids": [ "mix.stacked_bar_overlay", "mix.bar", "scatter.scatter", "scatter.bubble", "mix.barmekko" ], "disambiguation_needed": "Clarify whether the intended focus is `primary_rank_plus_secondary_marker`, `ranked_single_metric_comparison`, `relationship_between_two_metrics`, `two_metric_relationship_plus_size`, `width_metric_times_height_metric`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.stacked_column": { "family": "mix", "visual_grammar": "stacked_column", "analysis_task_ids": [ "time_and_period_movement", "composition_and_mix" ], "selection_tags": [ "composition_over_periods", "mix_shift" ], "selection_emphasis": "composition_change_over_periods", "best_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "avoid_when": "Avoid when exact values or simple trend shape matters more than composition.", "axis_roles": { "x": "period_or_scope", "y": "metric_total", "stack": "component_dimension" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": false, "minimum_distinct_values": 1, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [ "component_dimension" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "period_comparison.trend", "mix.stacked_bar", "mix.column", "mix.area", "mix.cohort_lost_stacked_column", "mix.cohort_since_stacked_column", "mix.like_for_like_stacked_column", "mix.timeline" ], "capability_id": "mix.stacked_column", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_comparison / mix_regular / stacked_column", "mix_comparison / mix_regular / stacked_column_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for total and component composition across periods.", "requires_question_focus": [ "composition_over_time", "stacked_periods" ], "reject_decision_cues": [ "asks for line trajectory", "asks for exact values", "asks for same-population-only mix" ], "forbidden_question_focus": [ "single_line_trend", "exact_period_values", "like_for_like_population" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 1, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "stacked_column" ], "variant_chart_options": [ "stacked_column_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "stacked_column" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": false, "minimum_distinct_values": 1, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 1, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 1, "required_roles": [ "component_dimension" ], "optional_roles": [], "role_requirements": { "component_dimension": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "component_dimension", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "component_dimension", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "period_or_scope", "y": "metric_total", "stack": "component_dimension" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "reject_when": "Avoid when exact values or simple trend shape matters more than composition.", "tie_breakers": [ { "against": "period_comparison.trend", "choose_this_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "choose_other_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "distinguishing_emphasis": { "this": "composition_change_over_periods", "other": "trajectory_shape" } }, { "against": "mix.stacked_bar", "choose_this_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "choose_other_when": "The reader needs both total size and component composition across categories.", "distinguishing_emphasis": { "this": "composition_change_over_periods", "other": "composition_within_ranked_totals" } }, { "against": "mix.column", "choose_this_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "choose_other_when": "The reader needs a compact total metric column view across selected periods or scopes.", "distinguishing_emphasis": { "this": "composition_change_over_periods", "other": "total_metric_by_period_or_scope" } }, { "against": "mix.area", "choose_this_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "choose_other_when": "The reader needs a time-series area view for absolute contribution or share over periods.", "distinguishing_emphasis": { "this": "composition_change_over_periods", "other": "trend_with_cumulative_or_share_area" } }, { "against": "mix.cohort_lost_stacked_column", "choose_this_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "choose_other_when": "The reader needs to see contribution by lost or last-active cohort.", "distinguishing_emphasis": { "this": "composition_change_over_periods", "other": "lost_cohort_contribution" } }, { "against": "mix.cohort_since_stacked_column", "choose_this_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "choose_other_when": "The reader needs to see contribution by first-active cohort over periods.", "distinguishing_emphasis": { "this": "composition_change_over_periods", "other": "since_cohort_contribution" } }, { "against": "mix.like_for_like_stacked_column", "choose_this_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "choose_other_when": "The reader needs like-for-like total movement and composition together.", "distinguishing_emphasis": { "this": "composition_change_over_periods", "other": "same_population_composition_change" } }, { "against": "mix.timeline", "choose_this_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "choose_other_when": "The reader needs the trend path of the primary mix metric across ordered periods.", "distinguishing_emphasis": { "this": "composition_change_over_periods", "other": "single_metric_trend_shape" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.stacked_column` only when the task is one of ['time_and_period_movement', 'composition_and_mix'] and the required emphasis is `composition_change_over_periods`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.stacked_column", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_comparison / mix_regular / stacked_column", "mix_comparison / mix_regular / stacked_column_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "component_dimension", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "mix_comparison / mix_regular / stacked_column_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "mix_comparison / mix_regular / stacked_column", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "stacked", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "mix_comparison / mix_regular / stacked_column_small_multiples", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "stacked", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show recent monthly sales mix by category." ], "negative_questions": [ { "question": "How did monthly cosmetics sales evolve versus previous year?", "why_not": "This asks for `trajectory_shape`, not `composition_change_over_periods`.", "better_capability_id": "period_comparison.trend" }, { "question": "Show sales totals and composition by retailer within categories.", "why_not": "This asks for `composition_within_ranked_totals`, not `composition_change_over_periods`.", "better_capability_id": "mix.stacked_bar" }, { "question": "Show total sales by month as compact columns.", "why_not": "This asks for `total_metric_by_period_or_scope`, not `composition_change_over_periods`.", "better_capability_id": "mix.column" }, { "question": "Show sales contribution as an area trend across months.", "why_not": "This asks for `trend_with_cumulative_or_share_area`, not `composition_change_over_periods`.", "better_capability_id": "mix.area" }, { "question": "How much sales contribution comes from products by last active month?", "why_not": "This asks for `lost_cohort_contribution`, not `composition_change_over_periods`.", "better_capability_id": "mix.cohort_lost_stacked_column" } ], "ambiguous_questions": [ { "question": "How did sales change over time?", "candidate_capability_ids": [ "mix.stacked_column", "period_comparison.trend", "mix.stacked_bar", "mix.column", "mix.area" ], "disambiguation_needed": "Clarify whether the intended focus is `composition_change_over_periods`, `trajectory_shape`, `composition_within_ranked_totals`, `total_metric_by_period_or_scope`, `trend_with_cumulative_or_share_area`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.stacked_pareto": { "family": "mix", "visual_grammar": "stacked_pareto", "analysis_task_ids": [ "composition_and_mix" ], "selection_tags": [ "concentration", "composition" ], "selection_emphasis": "concentration_with_component_breakdown", "best_when": "The reader needs Pareto concentration plus stacked composition by another dimension or class.", "avoid_when": "Avoid when a plain Pareto or plain stacked bar would be easier to read.", "axis_roles": { "x": "ranked_category_or_class", "y": "metric", "stack": "component_dimension" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [ "category", "component_dimension" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "mix.pareto", "mix.stacked_bar", "mix.marimekko" ], "capability_id": "mix.stacked_pareto", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_current / stacked_pareto_abc", "mix_current / stacked_pareto_by_dimension" ], "example_count": 2, "primary_decision_cue": "Question asks for concentration and component breakdown together.", "requires_question_focus": [ "pareto_concentration", "component_breakdown" ], "reject_decision_cues": [ "asks for simple Pareto only", "asks for stacked totals only", "asks for metric relationship" ], "forbidden_question_focus": [ "pareto_only", "stacked_total_only", "metric_relationship" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "stacked_pareto" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "stacked_pareto_abc", "stacked_pareto_by_dimension" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 2, "required_roles": [ "category", "component_dimension" ], "optional_roles": [], "role_requirements": { "category": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "category", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "category", "required": true }, "component_dimension": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "component_dimension", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "component_dimension", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "ranked_category_or_class", "y": "metric", "stack": "component_dimension" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs Pareto concentration plus stacked composition by another dimension or class.", "reject_when": "Avoid when a plain Pareto or plain stacked bar would be easier to read.", "tie_breakers": [ { "against": "mix.pareto", "choose_this_when": "The reader needs Pareto concentration plus stacked composition by another dimension or class.", "choose_other_when": "The reader needs to identify the few categories that explain most of the metric.", "distinguishing_emphasis": { "this": "concentration_with_component_breakdown", "other": "ranked_contribution_and_cumulative_share" } }, { "against": "mix.stacked_bar", "choose_this_when": "The reader needs Pareto concentration plus stacked composition by another dimension or class.", "choose_other_when": "The reader needs both total size and component composition across categories.", "distinguishing_emphasis": { "this": "concentration_with_component_breakdown", "other": "composition_within_ranked_totals" } }, { "against": "mix.marimekko", "choose_this_when": "The reader needs Pareto concentration plus stacked composition by another dimension or class.", "choose_other_when": "The reader needs to see composition across two categorical dimensions where both width and height carry meaning.", "distinguishing_emphasis": { "this": "concentration_with_component_breakdown", "other": "two_dimension_share_and_size" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.stacked_pareto` only when the task is one of ['composition_and_mix'] and the required emphasis is `concentration_with_component_breakdown`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.stacked_pareto", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_current / stacked_pareto_abc", "mix_current / stacked_pareto_by_dimension" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "category", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "component_dimension", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } } ], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "mix_current / stacked_pareto_abc", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "stacked_pareto", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "mix_current / stacked_pareto_by_dimension", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "stacked_pareto", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show concentration and component composition together." ], "negative_questions": [ { "question": "Find the few categories that explain most sales.", "why_not": "This asks for `ranked_contribution_and_cumulative_share`, not `concentration_with_component_breakdown`.", "better_capability_id": "mix.pareto" }, { "question": "Show sales totals and composition by retailer within categories.", "why_not": "This asks for `composition_within_ranked_totals`, not `concentration_with_component_breakdown`.", "better_capability_id": "mix.stacked_bar" }, { "question": "Show sales composition across category and retailer.", "why_not": "This asks for `two_dimension_share_and_size`, not `concentration_with_component_breakdown`.", "better_capability_id": "mix.marimekko" }, { "question": "Show sales contribution as an area trend across months.", "why_not": "This asks for `trend_with_cumulative_or_share_area`, not `concentration_with_component_breakdown`.", "better_capability_id": "mix.area" }, { "question": "Show category width and retailer height as a variable-width composition.", "why_not": "This asks for `width_metric_times_height_metric`, not `concentration_with_component_breakdown`.", "better_capability_id": "mix.barmekko" } ], "ambiguous_questions": [ { "question": "Show sales mix and composition.", "candidate_capability_ids": [ "mix.stacked_pareto", "mix.pareto", "mix.stacked_bar", "mix.marimekko", "mix.area" ], "disambiguation_needed": "Clarify whether the intended focus is `concentration_with_component_breakdown`, `ranked_contribution_and_cumulative_share`, `composition_within_ranked_totals`, `two_dimension_share_and_size`, `trend_with_cumulative_or_share_area`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "mix.timeline": { "family": "mix", "visual_grammar": "line_time_series", "analysis_task_ids": [ "time_and_period_movement" ], "selection_tags": [ "period_movement", "mix_metric_trend" ], "selection_emphasis": "single_metric_trend_shape", "best_when": "The reader needs the trend path of the primary mix metric across ordered periods.", "avoid_when": "Avoid when composition, hierarchy, or AC/PY period comparison is the main message.", "axis_roles": { "x": "ordered_period", "y": "metric" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": false, "minimum_distinct_values": 1, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "primary_additive_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [] }, "dimension_roles": [], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "period_comparison.trend", "mix.column", "mix.area", "mix.stacked_column" ], "capability_id": "mix.timeline", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "mix_comparison / line", "mix_comparison / line_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for one metric's trend path across ordered periods without AC/PY comparison.", "requires_question_focus": [ "single_line_trend", "ordered_periods" ], "reject_decision_cues": [ "asks for AC/PY comparison", "asks for composition over time", "asks for exact period table" ], "forbidden_question_focus": [ "current_vs_baseline", "composition_over_time", "exact_period_values" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 1, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "line" ], "variant_chart_options": [ "line_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "line" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": false, "minimum_distinct_values": 1, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 1, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "primary_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "display_metric_roles": [ "primary_additive_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 0, "required_roles": [], "optional_roles": [], "role_requirements": {}, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "ordered_period", "y": "metric" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs the trend path of the primary mix metric across ordered periods.", "reject_when": "Avoid when composition, hierarchy, or AC/PY period comparison is the main message.", "tie_breakers": [ { "against": "period_comparison.trend", "choose_this_when": "The reader needs the trend path of the primary mix metric across ordered periods.", "choose_other_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "distinguishing_emphasis": { "this": "single_metric_trend_shape", "other": "trajectory_shape" } }, { "against": "mix.column", "choose_this_when": "The reader needs the trend path of the primary mix metric across ordered periods.", "choose_other_when": "The reader needs a compact total metric column view across selected periods or scopes.", "distinguishing_emphasis": { "this": "single_metric_trend_shape", "other": "total_metric_by_period_or_scope" } }, { "against": "mix.area", "choose_this_when": "The reader needs the trend path of the primary mix metric across ordered periods.", "choose_other_when": "The reader needs a time-series area view for absolute contribution or share over periods.", "distinguishing_emphasis": { "this": "single_metric_trend_shape", "other": "trend_with_cumulative_or_share_area" } }, { "against": "mix.stacked_column", "choose_this_when": "The reader needs the trend path of the primary mix metric across ordered periods.", "choose_other_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "distinguishing_emphasis": { "this": "single_metric_trend_shape", "other": "composition_change_over_periods" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `mix.timeline` only when the task is one of ['time_and_period_movement'] and the required emphasis is `single_metric_trend_shape`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "mix.timeline", "plugin_sources": [ "mix-contribution-analysis" ], "artifact_labels": [ "mix_comparison / line", "mix_comparison / line_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_selection", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "primary_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "mix_comparison / line_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "mix_comparison / line", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "line", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "mix_comparison / line_small_multiples", "plugin_source": "mix-contribution-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "line", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.mix", "legacy_plugin_source": "mix-contribution-analysis", "component_name": "mix-contribution-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_selection", "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/mix-contribution-analysis/scripts/mix_core.py", "plugins/mix-contribution-analysis/scripts/legacy_mix_charting.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show the single sales trend across months without AC/PY comparison." ], "negative_questions": [ { "question": "How did monthly cosmetics sales evolve versus previous year?", "why_not": "This asks for `trajectory_shape`, not `single_metric_trend_shape`.", "better_capability_id": "period_comparison.trend" }, { "question": "Show total sales by month as compact columns.", "why_not": "This asks for `total_metric_by_period_or_scope`, not `single_metric_trend_shape`.", "better_capability_id": "mix.column" }, { "question": "Show sales contribution as an area trend across months.", "why_not": "This asks for `trend_with_cumulative_or_share_area`, not `single_metric_trend_shape`.", "better_capability_id": "mix.area" }, { "question": "Show recent monthly sales mix by category.", "why_not": "This asks for `composition_change_over_periods`, not `single_metric_trend_shape`.", "better_capability_id": "mix.stacked_column" }, { "question": "Show category sales in two periods and the difference, split into retailer panels.", "why_not": "This asks for `dimension_period_values_and_delta`, not `single_metric_trend_shape`.", "better_capability_id": "mix.multitier_bar" } ], "ambiguous_questions": [ { "question": "How did sales change over time?", "candidate_capability_ids": [ "mix.timeline", "period_comparison.trend", "mix.column", "mix.area", "mix.stacked_column" ], "disambiguation_needed": "Clarify whether the intended focus is `single_metric_trend_shape`, `trajectory_shape`, `total_metric_by_period_or_scope`, `trend_with_cumulative_or_share_area`, `composition_change_over_periods`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "period_comparison.by_period": { "family": "period_comparison", "visual_grammar": "period_gap_comparison", "analysis_task_ids": [ "time_and_period_movement" ], "selection_tags": [ "period_movement", "period_gap_scan" ], "selection_emphasis": "period_by_period_gap", "best_when": "The reader needs weekly-average current and baseline values across overlapping 52-, 26-, 13- and 4-week recency windows.", "avoid_when": "Do not use for individual calendar-month totals or monthly gaps; use multitier_column for side-by-side monthly values or trend for their trajectory. Recency windows overlap and are not additive.", "axis_roles": { "x": "overlapping_recency_window", "y": "weekly_average_metric", "series": "scenario_or_comparison_period" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "current_period_metric", "baseline_period_metric", "delta_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" } ], "minimum_source_metric_count": 1, "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimension_roles": [ "comparison_series" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "period_comparison.trend", "period_comparison.multitier_column", "period_comparison.time_series_table", "period_comparison.horizontal_waterfall", "period_comparison.dot" ], "capability_id": "period_comparison.by_period", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "period / year_over_year_by_recency_window", "period / year_over_year_by_recency_window_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for weekly-average current-vs-baseline gaps across overlapping recency windows, not individual calendar months.", "requires_question_focus": [ "period_gap", "current_vs_baseline_by_period" ], "reject_decision_cues": [ "asks for individual calendar-month totals", "asks for smooth trajectory", "asks for additive reconciliation", "asks for exact table" ], "forbidden_question_focus": [ "trajectory_shape", "bridge_reconciliation", "exact_period_values" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "year_over_year_by_period" ], "variant_chart_options": [ "year_over_year_by_period_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "year_over_year_by_period" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" } ], "display_metric_roles": [ "current_period_metric", "baseline_period_metric", "delta_metric" ], "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimensions": { "minimum_count": 0, "required_roles": [ "comparison_series" ], "optional_roles": [], "role_requirements": { "comparison_series": { "resolution_type": "derived_from_period_pair", "requires_profile_roles": [ "period" ], "output_role": "series label such as AC/PY, current/baseline, or scenario", "notes": "Derived after choosing the comparison periods; it is not a dataset column.", "role": "comparison_series", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "overlapping_recency_window", "y": "weekly_average_metric", "series": "scenario_or_comparison_period" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs weekly-average current and baseline values across overlapping 52-, 26-, 13- and 4-week recency windows.", "reject_when": "Do not use for individual calendar-month totals or monthly gaps; use multitier_column for side-by-side monthly values or trend for their trajectory. Recency windows overlap and are not additive.", "tie_breakers": [ { "against": "period_comparison.trend", "choose_this_when": "The reader needs weekly-average current and baseline values across overlapping 52-, 26-, 13- and 4-week recency windows.", "choose_other_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "distinguishing_emphasis": { "this": "period_by_period_gap", "other": "trajectory_shape" } }, { "against": "period_comparison.multitier_column", "choose_this_when": "The reader needs weekly-average current and baseline values across overlapping 52-, 26-, 13- and 4-week recency windows.", "choose_other_when": "The reader needs a compact executive AC/PY period comparison with clear column contrast.", "distinguishing_emphasis": { "this": "period_by_period_gap", "other": "compact_side_by_side_period_comparison" } }, { "against": "period_comparison.time_series_table", "choose_this_when": "The reader needs weekly-average current and baseline values across overlapping 52-, 26-, 13- and 4-week recency windows.", "choose_other_when": "The report needs citeable period values, deltas, and percent deltas rather than a primarily visual reading.", "distinguishing_emphasis": { "this": "period_by_period_gap", "other": "exact_values" } }, { "against": "period_comparison.horizontal_waterfall", "choose_this_when": "The reader needs weekly-average current and baseline values across overlapping 52-, 26-, 13- and 4-week recency windows.", "choose_other_when": "The reader needs to see how period variances add from previous total to current total.", "distinguishing_emphasis": { "this": "period_by_period_gap", "other": "additive_reconciliation" } }, { "against": "period_comparison.dot", "choose_this_when": "The reader needs weekly-average current and baseline values across overlapping 52-, 26-, 13- and 4-week recency windows.", "choose_other_when": "The reader needs a low-clutter comparison of two values across categories, panels, or periods.", "distinguishing_emphasis": { "this": "period_by_period_gap", "other": "gap_between_two_values" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `period_comparison.by_period` only when the task is one of ['time_and_period_movement'] and the required emphasis is `period_by_period_gap`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "period_comparison.by_period", "plugin_sources": [ "period-comparison" ], "artifact_labels": [ "period / year_over_year_by_recency_window", "period / year_over_year_by_recency_window_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_days", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "comparison_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "comparison_series", "required": true, "status": "mapped", "mapping_kind": "derived_from_period", "caller_binding_required": false, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null } ], "depends_on_role": "period_axis", "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "period / year_over_year_by_recency_window_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "period / year_over_year_by_recency_window", "plugin_source": "period-comparison", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "period_gap", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "period / year_over_year_by_recency_window_small_multiples", "plugin_source": "period-comparison", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "period_gap", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.period_comparison", "legacy_plugin_source": "period-comparison", "component_name": "period-comparison", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/period-comparison/scripts/period_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "How do weekly-average AC/PY sales gaps differ across overlapping 52-, 26-, 13- and 4-week recency windows?" ], "negative_questions": [ { "question": "How did monthly cosmetics sales evolve versus previous year?", "why_not": "This asks for `trajectory_shape`, not `period_by_period_gap`.", "better_capability_id": "period_comparison.trend" }, { "question": "Show compact AC/PY monthly sales columns.", "why_not": "This asks for `compact_side_by_side_period_comparison`, not `period_by_period_gap`.", "better_capability_id": "period_comparison.multitier_column" }, { "question": "Give citeable monthly AC/PY sales values and variances.", "why_not": "This asks for `exact_values`, not `period_by_period_gap`.", "better_capability_id": "period_comparison.time_series_table" }, { "question": "How do period variances reconcile prior-year sales to current sales?", "why_not": "This asks for `additive_reconciliation`, not `period_by_period_gap`.", "better_capability_id": "period_comparison.horizontal_waterfall" }, { "question": "Compare AC/PY sales gaps across categories with low clutter.", "why_not": "This asks for `gap_between_two_values`, not `period_by_period_gap`.", "better_capability_id": "period_comparison.dot" } ], "ambiguous_questions": [ { "question": "How did sales change over time?", "candidate_capability_ids": [ "period_comparison.by_period", "period_comparison.trend", "period_comparison.multitier_column", "period_comparison.time_series_table", "period_comparison.horizontal_waterfall" ], "disambiguation_needed": "Clarify whether the intended focus is `period_by_period_gap`, `trajectory_shape`, `compact_side_by_side_period_comparison`, `exact_values`, `additive_reconciliation`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "period_comparison.comparison_table": { "family": "period_comparison", "visual_grammar": "comparison_table", "analysis_task_ids": [ "ranking_and_comparison", "evidence_and_reporting_tables" ], "selection_tags": [ "period_comparison_summary", "exact_comparison_values" ], "selection_emphasis": "summary_exact_values", "best_when": "The reader needs compact exact AC/PY totals and deltas by comparison row.", "avoid_when": "Avoid when the message depends on the period path or monthly sequencing.", "axis_roles": { "rows": "comparison_item", "columns": "baseline_current_delta" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "current_period_metric", "baseline_period_metric", "delta_metric", "percent_delta_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" }, { "role": "percent_delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "delta_metric / baseline_period_metric when baseline is non-zero" } ], "minimum_source_metric_count": 1, "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimension_roles": [ "comparison_window" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "period_comparison.time_series_table", "period_comparison.dot" ], "capability_id": "period_comparison.comparison_table", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "period / comparison_table" ], "example_count": 1, "primary_decision_cue": "Question asks for exact summary current, baseline, delta, and percent-delta values.", "requires_question_focus": [ "exact_summary_values", "comparison_table" ], "reject_decision_cues": [ "asks for visual trend", "asks for bridge reconciliation", "asks for distribution" ], "forbidden_question_focus": [ "trajectory_shape", "bridge_reconciliation", "distribution_shape" ], "period_scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "comparison_table" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "comparison_table" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" }, { "role": "percent_delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "delta_metric / baseline_period_metric when baseline is non-zero" } ], "display_metric_roles": [ "current_period_metric", "baseline_period_metric", "delta_metric", "percent_delta_metric" ], "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimensions": { "minimum_count": 0, "required_roles": [ "comparison_window" ], "optional_roles": [], "role_requirements": { "comparison_window": { "resolution_type": "derived_from_period_pair", "requires_profile_roles": [ "period" ], "output_role": "comparison row/window label", "notes": "Derived from selected current and baseline windows.", "role": "comparison_window", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "rows": "comparison_item", "columns": "baseline_current_delta" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs compact exact AC/PY totals and deltas by comparison row.", "reject_when": "Avoid when the message depends on the period path or monthly sequencing.", "tie_breakers": [ { "against": "period_comparison.time_series_table", "choose_this_when": "The reader needs compact exact AC/PY totals and deltas by comparison row.", "choose_other_when": "The report needs citeable period values, deltas, and percent deltas rather than a primarily visual reading.", "distinguishing_emphasis": { "this": "summary_exact_values", "other": "exact_values" } }, { "against": "period_comparison.dot", "choose_this_when": "The reader needs compact exact AC/PY totals and deltas by comparison row.", "choose_other_when": "The reader needs a low-clutter comparison of two values across categories, panels, or periods.", "distinguishing_emphasis": { "this": "summary_exact_values", "other": "gap_between_two_values" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `period_comparison.comparison_table` only when the task is one of ['ranking_and_comparison', 'evidence_and_reporting_tables'] and the required emphasis is `summary_exact_values`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "period_comparison.comparison_table", "plugin_sources": [ "period-comparison" ], "artifact_labels": [ "period / comparison_table" ], "output_forms": [ "table_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_filter", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_days", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "comparison_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "comparison_window", "required": true, "status": "mapped", "mapping_kind": "derived_from_period", "caller_binding_required": false, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null } ], "depends_on_role": "period_filter", "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "period / comparison_table", "plugin_source": "period-comparison", "output_form": "table_html", "selector_level": "base_capability", "layout_variant": "table", "encoding_variant": "table", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.period_comparison", "legacy_plugin_source": "period-comparison", "component_name": "period-comparison", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/period-comparison/scripts/period_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Give exact current, prior-year, delta, and percent-delta sales values." ], "negative_questions": [ { "question": "Give citeable monthly AC/PY sales values and variances.", "why_not": "This asks for `exact_values`, not `summary_exact_values`.", "better_capability_id": "period_comparison.time_series_table" }, { "question": "Compare AC/PY sales gaps across categories with low clutter.", "why_not": "This asks for `gap_between_two_values`, not `summary_exact_values`.", "better_capability_id": "period_comparison.dot" }, { "question": "Rank categories by sales for a selected scope.", "why_not": "This asks for `ranked_single_metric_comparison`, not `summary_exact_values`.", "better_capability_id": "mix.bar" }, { "question": "Show category sales in two periods and the difference, split into retailer panels.", "why_not": "This asks for `dimension_period_values_and_delta`, not `summary_exact_values`.", "better_capability_id": "mix.multitier_bar" }, { "question": "Find the few categories that explain most sales.", "why_not": "This asks for `ranked_contribution_and_cumulative_share`, not `summary_exact_values`.", "better_capability_id": "mix.pareto" } ], "ambiguous_questions": [ { "question": "Compare categories by sales.", "candidate_capability_ids": [ "period_comparison.comparison_table", "period_comparison.time_series_table", "period_comparison.dot", "mix.bar", "mix.multitier_bar" ], "disambiguation_needed": "Clarify whether the intended focus is `summary_exact_values`, `exact_values`, `gap_between_two_values`, `ranked_single_metric_comparison`, `dimension_period_values_and_delta`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "period_comparison.dot": { "family": "period_comparison", "visual_grammar": "dot_gap", "analysis_task_ids": [ "time_and_period_movement", "ranking_and_comparison" ], "selection_tags": [ "period_movement", "two_point_gap", "ranked_gap_comparison" ], "selection_emphasis": "gap_between_two_values", "best_when": "The reader needs a low-clutter comparison of two values across categories, panels, or periods.", "avoid_when": "Avoid when the month-by-month path or additive reconciliation matters.", "axis_roles": { "x": "metric", "y": "category_or_period", "marks": "baseline_and_current" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "current_period_metric", "baseline_period_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" } ], "minimum_source_metric_count": 1, "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimension_roles": [ "comparison_item" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "period_comparison.slope", "period_comparison.by_period", "period_comparison.multitier_column", "mix.multitier_bar", "period_comparison.comparison_table" ], "capability_id": "period_comparison.dot", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "period / year_over_year_dot", "period / year_over_year_dot_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for low-clutter comparison of two values across items.", "requires_question_focus": [ "two_value_gap", "low_clutter_comparison" ], "reject_decision_cues": [ "asks for monthly path", "asks for additive bridge", "asks for exact table" ], "forbidden_question_focus": [ "period_path", "bridge_reconciliation", "exact_values" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "year_over_year_dot" ], "variant_chart_options": [ "year_over_year_dot_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "year_over_year_dot" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" } ], "display_metric_roles": [ "current_period_metric", "baseline_period_metric" ], "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimensions": { "minimum_count": 1, "required_roles": [ "comparison_item" ], "optional_roles": [], "role_requirements": { "comparison_item": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "comparison_item", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "comparison_item", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "metric", "y": "category_or_period", "marks": "baseline_and_current" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs a low-clutter comparison of two values across categories, panels, or periods.", "reject_when": "Avoid when the month-by-month path or additive reconciliation matters.", "tie_breakers": [ { "against": "period_comparison.slope", "choose_this_when": "The reader needs a low-clutter comparison of two values across categories, panels, or periods.", "choose_other_when": "The reader needs direction and magnitude of change between two endpoints, especially across multiple comparable items.", "distinguishing_emphasis": { "this": "gap_between_two_values", "other": "endpoint_direction_and_relative_change" } }, { "against": "period_comparison.by_period", "choose_this_when": "The reader needs a low-clutter comparison of two values across categories, panels, or periods.", "choose_other_when": "The reader needs weekly-average current and baseline values across overlapping 52-, 26-, 13- and 4-week recency windows.", "distinguishing_emphasis": { "this": "gap_between_two_values", "other": "period_by_period_gap" } }, { "against": "period_comparison.multitier_column", "choose_this_when": "The reader needs a low-clutter comparison of two values across categories, panels, or periods.", "choose_other_when": "The reader needs a compact executive AC/PY period comparison with clear column contrast.", "distinguishing_emphasis": { "this": "gap_between_two_values", "other": "compact_side_by_side_period_comparison" } }, { "against": "mix.multitier_bar", "choose_this_when": "The reader needs a low-clutter comparison of two values across categories, panels, or periods.", "choose_other_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "distinguishing_emphasis": { "this": "gap_between_two_values", "other": "dimension_period_values_and_delta" } }, { "against": "period_comparison.comparison_table", "choose_this_when": "The reader needs a low-clutter comparison of two values across categories, panels, or periods.", "choose_other_when": "The reader needs compact exact AC/PY totals and deltas by comparison row.", "distinguishing_emphasis": { "this": "gap_between_two_values", "other": "summary_exact_values" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `period_comparison.dot` only when the task is one of ['time_and_period_movement', 'ranking_and_comparison'] and the required emphasis is `gap_between_two_values`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "period_comparison.dot", "plugin_sources": [ "period-comparison" ], "artifact_labels": [ "period / year_over_year_dot", "period / year_over_year_dot_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_days", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "comparison_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "comparison_item", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "period / year_over_year_dot_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "period / year_over_year_dot", "plugin_source": "period-comparison", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "dot", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "period / year_over_year_dot_small_multiples", "plugin_source": "period-comparison", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "dot", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.period_comparison", "legacy_plugin_source": "period-comparison", "component_name": "period-comparison", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/period-comparison/scripts/period_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Compare AC/PY sales gaps across categories with low clutter." ], "negative_questions": [ { "question": "Show endpoint direction and magnitude of category sales changes.", "why_not": "This asks for `endpoint_direction_and_relative_change`, not `gap_between_two_values`.", "better_capability_id": "period_comparison.slope" }, { "question": "How do weekly-average AC/PY sales gaps differ across overlapping 52-, 26-, 13- and 4-week recency windows?", "why_not": "This asks for `period_by_period_gap`, not `gap_between_two_values`.", "better_capability_id": "period_comparison.by_period" }, { "question": "Show compact AC/PY monthly sales columns.", "why_not": "This asks for `compact_side_by_side_period_comparison`, not `gap_between_two_values`.", "better_capability_id": "period_comparison.multitier_column" }, { "question": "Show category sales in two periods and the difference, split into retailer panels.", "why_not": "This asks for `dimension_period_values_and_delta`, not `gap_between_two_values`.", "better_capability_id": "mix.multitier_bar" }, { "question": "Give exact current, prior-year, delta, and percent-delta sales values.", "why_not": "This asks for `summary_exact_values`, not `gap_between_two_values`.", "better_capability_id": "period_comparison.comparison_table" } ], "ambiguous_questions": [ { "question": "How did sales change over time?", "candidate_capability_ids": [ "period_comparison.dot", "period_comparison.slope", "period_comparison.by_period", "period_comparison.multitier_column", "mix.multitier_bar" ], "disambiguation_needed": "Clarify whether the intended focus is `gap_between_two_values`, `endpoint_direction_and_relative_change`, `period_by_period_gap`, `compact_side_by_side_period_comparison`, `dimension_period_values_and_delta`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "period_comparison.horizontal_waterfall": { "family": "period_comparison", "visual_grammar": "period_bridge", "analysis_task_ids": [ "time_and_period_movement", "variance_and_bridge" ], "selection_tags": [ "period_movement", "period_reconciliation", "variance_bridge" ], "selection_emphasis": "additive_reconciliation", "best_when": "The reader needs to see how period variances add from previous total to current total.", "avoid_when": "Avoid when values are non-additive or the message is trend shape rather than reconciliation.", "axis_roles": { "x": "metric_delta", "y": "bridge_component_period" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "baseline_period_metric", "current_period_metric", "delta_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" } ], "minimum_source_metric_count": 1, "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimension_roles": [ "bridge_component_period" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "period_comparison.trend", "period_comparison.by_period", "variance.scenario_bridge", "period_comparison.slope" ], "capability_id": "period_comparison.horizontal_waterfall", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "period / year_over_year_waterfall", "period / year_over_year_waterfall_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks how period variances add from baseline total to current total.", "requires_question_focus": [ "bridge_reconciliation", "additive_period_variance" ], "reject_decision_cues": [ "asks for non-additive values", "asks for line shape", "asks for endpoint slope" ], "forbidden_question_focus": [ "non_additive_metric", "trajectory_shape", "endpoint_change" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "year_over_year_waterfall" ], "variant_chart_options": [ "year_over_year_waterfall_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "year_over_year_waterfall" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" } ], "display_metric_roles": [ "baseline_period_metric", "current_period_metric", "delta_metric" ], "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimensions": { "minimum_count": 0, "required_roles": [ "bridge_component_period" ], "optional_roles": [], "role_requirements": { "bridge_component_period": { "resolution_type": "derived_from_period_pair", "requires_profile_roles": [ "period" ], "output_role": "period delta bridge step", "notes": "Derived from ordered period deltas for an additive comparison metric.", "role": "bridge_component_period", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "metric_delta", "y": "bridge_component_period" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs to see how period variances add from previous total to current total.", "reject_when": "Avoid when values are non-additive or the message is trend shape rather than reconciliation.", "tie_breakers": [ { "against": "period_comparison.trend", "choose_this_when": "The reader needs to see how period variances add from previous total to current total.", "choose_other_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "distinguishing_emphasis": { "this": "additive_reconciliation", "other": "trajectory_shape" } }, { "against": "period_comparison.by_period", "choose_this_when": "The reader needs to see how period variances add from previous total to current total.", "choose_other_when": "The reader needs weekly-average current and baseline values across overlapping 52-, 26-, 13- and 4-week recency windows.", "distinguishing_emphasis": { "this": "additive_reconciliation", "other": "period_by_period_gap" } }, { "against": "variance.scenario_bridge", "choose_this_when": "The reader needs to see how period variances add from previous total to current total.", "choose_other_when": "Use for the plain bridge from one baseline total to one current total when the message is the additive reconciliation itself, not a ranked dimension split, root-cause path, or PVM mechanics.", "distinguishing_emphasis": { "this": "additive_reconciliation", "other": "scenario_reconciliation" } }, { "against": "period_comparison.slope", "choose_this_when": "The reader needs to see how period variances add from previous total to current total.", "choose_other_when": "The reader needs direction and magnitude of change between two endpoints, especially across multiple comparable items.", "distinguishing_emphasis": { "this": "additive_reconciliation", "other": "endpoint_direction_and_relative_change" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `period_comparison.horizontal_waterfall` only when the task is one of ['time_and_period_movement', 'variance_and_bridge'] and the required emphasis is `additive_reconciliation`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "period_comparison.horizontal_waterfall", "plugin_sources": [ "period-comparison" ], "artifact_labels": [ "period / year_over_year_waterfall", "period / year_over_year_waterfall_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_days", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "comparison_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "bridge_component_period", "required": true, "status": "mapped", "mapping_kind": "derived_from_period", "caller_binding_required": false, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null } ], "depends_on_role": "period_axis", "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "period / year_over_year_waterfall_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "period / year_over_year_waterfall", "plugin_source": "period-comparison", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "bridge", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "period / year_over_year_waterfall_small_multiples", "plugin_source": "period-comparison", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "bridge", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.period_comparison", "legacy_plugin_source": "period-comparison", "component_name": "period-comparison", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/period-comparison/scripts/period_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "How do period variances reconcile prior-year sales to current sales?" ], "negative_questions": [ { "question": "How did monthly cosmetics sales evolve versus previous year?", "why_not": "This asks for `trajectory_shape`, not `additive_reconciliation`.", "better_capability_id": "period_comparison.trend" }, { "question": "How do weekly-average AC/PY sales gaps differ across overlapping 52-, 26-, 13- and 4-week recency windows?", "why_not": "This asks for `period_by_period_gap`, not `additive_reconciliation`.", "better_capability_id": "period_comparison.by_period" }, { "question": "Reconcile total sales from baseline to current with a plain bridge.", "why_not": "This asks for `scenario_reconciliation`, not `additive_reconciliation`.", "better_capability_id": "variance.scenario_bridge" }, { "question": "Show endpoint direction and magnitude of category sales changes.", "why_not": "This asks for `endpoint_direction_and_relative_change`, not `additive_reconciliation`.", "better_capability_id": "period_comparison.slope" }, { "question": "Show sales contribution as an area trend across months.", "why_not": "This asks for `trend_with_cumulative_or_share_area`, not `additive_reconciliation`.", "better_capability_id": "mix.area" } ], "ambiguous_questions": [ { "question": "How did sales change over time?", "candidate_capability_ids": [ "period_comparison.horizontal_waterfall", "period_comparison.trend", "period_comparison.by_period", "variance.scenario_bridge", "period_comparison.slope" ], "disambiguation_needed": "Clarify whether the intended focus is `additive_reconciliation`, `trajectory_shape`, `period_by_period_gap`, `scenario_reconciliation`, `endpoint_direction_and_relative_change`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "period_comparison.multitier_column": { "family": "period_comparison", "visual_grammar": "comparison_column", "analysis_task_ids": [ "time_and_period_movement" ], "selection_tags": [ "period_movement", "period_gap_scan" ], "selection_emphasis": "compact_side_by_side_period_comparison", "best_when": "The reader needs a compact executive AC/PY period comparison with clear column contrast.", "avoid_when": "Avoid when line shape, exact values, or total bridge reconciliation is the main message.", "axis_roles": { "x": "ordered_period_or_category", "y": "metric", "series": "scenario_or_comparison_period" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "current_period_metric", "baseline_period_metric", "delta_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" } ], "minimum_source_metric_count": 1, "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimension_roles": [ "comparison_series" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "period_comparison.trend", "period_comparison.by_period", "period_comparison.dot", "mix.multitier_bar" ], "capability_id": "period_comparison.multitier_column", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "period / year_over_year_column", "period / year_over_year_column_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for compact side-by-side current and baseline period columns.", "requires_question_focus": [ "side_by_side_periods", "current_vs_baseline_values" ], "reject_decision_cues": [ "asks for line trajectory", "asks for exact table", "asks for bridge reconciliation" ], "forbidden_question_focus": [ "trajectory_shape", "exact_period_values", "bridge_reconciliation" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "year_over_year_column" ], "variant_chart_options": [ "year_over_year_column_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "year_over_year_column" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" } ], "display_metric_roles": [ "current_period_metric", "baseline_period_metric", "delta_metric" ], "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimensions": { "minimum_count": 0, "required_roles": [ "comparison_series" ], "optional_roles": [], "role_requirements": { "comparison_series": { "resolution_type": "derived_from_period_pair", "requires_profile_roles": [ "period" ], "output_role": "series label such as AC/PY, current/baseline, or scenario", "notes": "Derived after choosing the comparison periods; it is not a dataset column.", "role": "comparison_series", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "ordered_period_or_category", "y": "metric", "series": "scenario_or_comparison_period" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs a compact executive AC/PY period comparison with clear column contrast.", "reject_when": "Avoid when line shape, exact values, or total bridge reconciliation is the main message.", "tie_breakers": [ { "against": "period_comparison.trend", "choose_this_when": "The reader needs a compact executive AC/PY period comparison with clear column contrast.", "choose_other_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "distinguishing_emphasis": { "this": "compact_side_by_side_period_comparison", "other": "trajectory_shape" } }, { "against": "period_comparison.by_period", "choose_this_when": "The reader needs a compact executive AC/PY period comparison with clear column contrast.", "choose_other_when": "The reader needs weekly-average current and baseline values across overlapping 52-, 26-, 13- and 4-week recency windows.", "distinguishing_emphasis": { "this": "compact_side_by_side_period_comparison", "other": "period_by_period_gap" } }, { "against": "period_comparison.dot", "choose_this_when": "The reader needs a compact executive AC/PY period comparison with clear column contrast.", "choose_other_when": "The reader needs a low-clutter comparison of two values across categories, panels, or periods.", "distinguishing_emphasis": { "this": "compact_side_by_side_period_comparison", "other": "gap_between_two_values" } }, { "against": "mix.multitier_bar", "choose_this_when": "The reader needs a compact executive AC/PY period comparison with clear column contrast.", "choose_other_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "distinguishing_emphasis": { "this": "compact_side_by_side_period_comparison", "other": "dimension_period_values_and_delta" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `period_comparison.multitier_column` only when the task is one of ['time_and_period_movement'] and the required emphasis is `compact_side_by_side_period_comparison`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "period_comparison.multitier_column", "plugin_sources": [ "period-comparison" ], "artifact_labels": [ "period / year_over_year_column", "period / year_over_year_column_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_days", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "comparison_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "comparison_series", "required": true, "status": "mapped", "mapping_kind": "derived_from_period", "caller_binding_required": false, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null } ], "depends_on_role": "period_axis", "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "period / year_over_year_column_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "period / year_over_year_column", "plugin_source": "period-comparison", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "column", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "period / year_over_year_column_small_multiples", "plugin_source": "period-comparison", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "column", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.period_comparison", "legacy_plugin_source": "period-comparison", "component_name": "period-comparison", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/period-comparison/scripts/period_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show compact AC/PY monthly sales columns." ], "negative_questions": [ { "question": "How did monthly cosmetics sales evolve versus previous year?", "why_not": "This asks for `trajectory_shape`, not `compact_side_by_side_period_comparison`.", "better_capability_id": "period_comparison.trend" }, { "question": "How do weekly-average AC/PY sales gaps differ across overlapping 52-, 26-, 13- and 4-week recency windows?", "why_not": "This asks for `period_by_period_gap`, not `compact_side_by_side_period_comparison`.", "better_capability_id": "period_comparison.by_period" }, { "question": "Compare AC/PY sales gaps across categories with low clutter.", "why_not": "This asks for `gap_between_two_values`, not `compact_side_by_side_period_comparison`.", "better_capability_id": "period_comparison.dot" }, { "question": "Show category sales in two periods and the difference, split into retailer panels.", "why_not": "This asks for `dimension_period_values_and_delta`, not `compact_side_by_side_period_comparison`.", "better_capability_id": "mix.multitier_bar" }, { "question": "Show sales contribution as an area trend across months.", "why_not": "This asks for `trend_with_cumulative_or_share_area`, not `compact_side_by_side_period_comparison`.", "better_capability_id": "mix.area" } ], "ambiguous_questions": [ { "question": "How did sales change over time?", "candidate_capability_ids": [ "period_comparison.multitier_column", "period_comparison.trend", "period_comparison.by_period", "period_comparison.dot", "mix.multitier_bar" ], "disambiguation_needed": "Clarify whether the intended focus is `compact_side_by_side_period_comparison`, `trajectory_shape`, `period_by_period_gap`, `gap_between_two_values`, `dimension_period_values_and_delta`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "period_comparison.slope": { "family": "period_comparison", "visual_grammar": "slope_endpoint_change", "analysis_task_ids": [ "time_and_period_movement" ], "selection_tags": [ "period_movement", "two_point_change", "relative_direction_comparison" ], "selection_emphasis": "endpoint_direction_and_relative_change", "best_when": "The reader needs direction and magnitude of change between two endpoints, especially across multiple comparable items.", "avoid_when": "Avoid when intermediate months, exact values, or additive bridge components are essential.", "axis_roles": { "x": "two_endpoints", "y": "metric", "series": "item_or_panel" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "current_period_metric", "baseline_period_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" } ], "minimum_source_metric_count": 1, "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimension_roles": [ "comparison_item" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "period_comparison.dot", "period_comparison.trend", "period_comparison.horizontal_waterfall", "mix.multitier_bar" ], "capability_id": "period_comparison.slope", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "period / year_over_year_slope", "period / year_over_year_slope_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for direction and magnitude between two endpoints.", "requires_question_focus": [ "endpoint_change", "relative_direction" ], "reject_decision_cues": [ "asks for intermediate period path", "asks for additive bridge", "asks for exact values" ], "forbidden_question_focus": [ "period_path", "bridge_reconciliation", "exact_values" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "year_over_year_slope" ], "variant_chart_options": [ "year_over_year_slope_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "year_over_year_slope" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" } ], "display_metric_roles": [ "current_period_metric", "baseline_period_metric" ], "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimensions": { "minimum_count": 1, "required_roles": [ "comparison_item" ], "optional_roles": [], "role_requirements": { "comparison_item": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "comparison_item", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "comparison_item", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "two_endpoints", "y": "metric", "series": "item_or_panel" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs direction and magnitude of change between two endpoints, especially across multiple comparable items.", "reject_when": "Avoid when intermediate months, exact values, or additive bridge components are essential.", "tie_breakers": [ { "against": "period_comparison.dot", "choose_this_when": "The reader needs direction and magnitude of change between two endpoints, especially across multiple comparable items.", "choose_other_when": "The reader needs a low-clutter comparison of two values across categories, panels, or periods.", "distinguishing_emphasis": { "this": "endpoint_direction_and_relative_change", "other": "gap_between_two_values" } }, { "against": "period_comparison.trend", "choose_this_when": "The reader needs direction and magnitude of change between two endpoints, especially across multiple comparable items.", "choose_other_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "distinguishing_emphasis": { "this": "endpoint_direction_and_relative_change", "other": "trajectory_shape" } }, { "against": "period_comparison.horizontal_waterfall", "choose_this_when": "The reader needs direction and magnitude of change between two endpoints, especially across multiple comparable items.", "choose_other_when": "The reader needs to see how period variances add from previous total to current total.", "distinguishing_emphasis": { "this": "endpoint_direction_and_relative_change", "other": "additive_reconciliation" } }, { "against": "mix.multitier_bar", "choose_this_when": "The reader needs direction and magnitude of change between two endpoints, especially across multiple comparable items.", "choose_other_when": "The reader needs one dimension split into rows, with sales for two periods and their difference visible together; if a second dimension is needed, it becomes small-multiple panels.", "distinguishing_emphasis": { "this": "endpoint_direction_and_relative_change", "other": "dimension_period_values_and_delta" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `period_comparison.slope` only when the task is one of ['time_and_period_movement'] and the required emphasis is `endpoint_direction_and_relative_change`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "period_comparison.slope", "plugin_sources": [ "period-comparison" ], "artifact_labels": [ "period / year_over_year_slope", "period / year_over_year_slope_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_days", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "comparison_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "comparison_item", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "period / year_over_year_slope_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "period / year_over_year_slope", "plugin_source": "period-comparison", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "slope", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "period / year_over_year_slope_small_multiples", "plugin_source": "period-comparison", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "slope", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.period_comparison", "legacy_plugin_source": "period-comparison", "component_name": "period-comparison", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/period-comparison/scripts/period_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show endpoint direction and magnitude of category sales changes." ], "negative_questions": [ { "question": "Compare AC/PY sales gaps across categories with low clutter.", "why_not": "This asks for `gap_between_two_values`, not `endpoint_direction_and_relative_change`.", "better_capability_id": "period_comparison.dot" }, { "question": "How did monthly cosmetics sales evolve versus previous year?", "why_not": "This asks for `trajectory_shape`, not `endpoint_direction_and_relative_change`.", "better_capability_id": "period_comparison.trend" }, { "question": "How do period variances reconcile prior-year sales to current sales?", "why_not": "This asks for `additive_reconciliation`, not `endpoint_direction_and_relative_change`.", "better_capability_id": "period_comparison.horizontal_waterfall" }, { "question": "Show category sales in two periods and the difference, split into retailer panels.", "why_not": "This asks for `dimension_period_values_and_delta`, not `endpoint_direction_and_relative_change`.", "better_capability_id": "mix.multitier_bar" }, { "question": "Show sales contribution as an area trend across months.", "why_not": "This asks for `trend_with_cumulative_or_share_area`, not `endpoint_direction_and_relative_change`.", "better_capability_id": "mix.area" } ], "ambiguous_questions": [ { "question": "How did sales change over time?", "candidate_capability_ids": [ "period_comparison.slope", "period_comparison.dot", "period_comparison.trend", "period_comparison.horizontal_waterfall", "mix.multitier_bar" ], "disambiguation_needed": "Clarify whether the intended focus is `endpoint_direction_and_relative_change`, `gap_between_two_values`, `trajectory_shape`, `additive_reconciliation`, `dimension_period_values_and_delta`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "period_comparison.time_series_table": { "family": "period_comparison", "visual_grammar": "period_table", "analysis_task_ids": [ "time_and_period_movement" ], "selection_tags": [ "period_movement", "exact_period_values" ], "selection_emphasis": "exact_values", "best_when": "The report needs citeable period values, deltas, and percent deltas rather than a primarily visual reading.", "avoid_when": "Avoid as the only visual when the reader must quickly perceive shape, gap, or reconciliation.", "axis_roles": { "rows": "ordered_period", "columns": "metric_and_delta" }, "period_semantics": { "role": "axis_or_table", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "current_period_metric", "baseline_period_metric", "delta_metric", "percent_delta_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" }, { "role": "percent_delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "delta_metric / baseline_period_metric when baseline is non-zero" } ], "minimum_source_metric_count": 1, "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimension_roles": [], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "period_comparison.trend", "period_comparison.by_period", "period_comparison.comparison_table" ], "capability_id": "period_comparison.time_series_table", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "period / time_series_table" ], "example_count": 1, "primary_decision_cue": "Question asks for citeable exact period values, deltas, or percent deltas.", "requires_question_focus": [ "exact_period_values", "period_table" ], "reject_decision_cues": [ "asks for quick visual shape", "asks for bridge reconciliation", "asks for low-clutter comparison" ], "forbidden_question_focus": [ "trajectory_shape", "bridge_reconciliation", "two_value_gap" ], "period_scope_contract": { "role": "axis_or_table", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "time_series_table" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "time_series_table" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis_or_table", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis_or_table", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" }, { "role": "percent_delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "delta_metric / baseline_period_metric when baseline is non-zero" } ], "display_metric_roles": [ "current_period_metric", "baseline_period_metric", "delta_metric", "percent_delta_metric" ], "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimensions": { "minimum_count": 0, "required_roles": [], "optional_roles": [], "role_requirements": {}, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "rows": "ordered_period", "columns": "metric_and_delta" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The report needs citeable period values, deltas, and percent deltas rather than a primarily visual reading.", "reject_when": "Avoid as the only visual when the reader must quickly perceive shape, gap, or reconciliation.", "tie_breakers": [ { "against": "period_comparison.trend", "choose_this_when": "The report needs citeable period values, deltas, and percent deltas rather than a primarily visual reading.", "choose_other_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "distinguishing_emphasis": { "this": "exact_values", "other": "trajectory_shape" } }, { "against": "period_comparison.by_period", "choose_this_when": "The report needs citeable period values, deltas, and percent deltas rather than a primarily visual reading.", "choose_other_when": "The reader needs weekly-average current and baseline values across overlapping 52-, 26-, 13- and 4-week recency windows.", "distinguishing_emphasis": { "this": "exact_values", "other": "period_by_period_gap" } }, { "against": "period_comparison.comparison_table", "choose_this_when": "The report needs citeable period values, deltas, and percent deltas rather than a primarily visual reading.", "choose_other_when": "The reader needs compact exact AC/PY totals and deltas by comparison row.", "distinguishing_emphasis": { "this": "exact_values", "other": "summary_exact_values" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `period_comparison.time_series_table` only when the task is one of ['time_and_period_movement'] and the required emphasis is `exact_values`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "period_comparison.time_series_table", "plugin_sources": [ "period-comparison" ], "artifact_labels": [ "period / time_series_table" ], "output_forms": [ "table_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_days", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "comparison_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "period / time_series_table", "plugin_source": "period-comparison", "output_form": "table_html", "selector_level": "base_capability", "layout_variant": "table", "encoding_variant": "table", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.period_comparison", "legacy_plugin_source": "period-comparison", "component_name": "period-comparison", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/period-comparison/scripts/period_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Give citeable monthly AC/PY sales values and variances." ], "negative_questions": [ { "question": "How did monthly cosmetics sales evolve versus previous year?", "why_not": "This asks for `trajectory_shape`, not `exact_values`.", "better_capability_id": "period_comparison.trend" }, { "question": "How do weekly-average AC/PY sales gaps differ across overlapping 52-, 26-, 13- and 4-week recency windows?", "why_not": "This asks for `period_by_period_gap`, not `exact_values`.", "better_capability_id": "period_comparison.by_period" }, { "question": "Give exact current, prior-year, delta, and percent-delta sales values.", "why_not": "This asks for `summary_exact_values`, not `exact_values`.", "better_capability_id": "period_comparison.comparison_table" }, { "question": "Show sales contribution as an area trend across months.", "why_not": "This asks for `trend_with_cumulative_or_share_area`, not `exact_values`.", "better_capability_id": "mix.area" }, { "question": "Show total sales by month as compact columns.", "why_not": "This asks for `total_metric_by_period_or_scope`, not `exact_values`.", "better_capability_id": "mix.column" } ], "ambiguous_questions": [ { "question": "How did sales change over time?", "candidate_capability_ids": [ "period_comparison.time_series_table", "period_comparison.trend", "period_comparison.by_period", "period_comparison.comparison_table", "mix.area" ], "disambiguation_needed": "Clarify whether the intended focus is `exact_values`, `trajectory_shape`, `period_by_period_gap`, `summary_exact_values`, `trend_with_cumulative_or_share_area`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "period_comparison.trend": { "family": "period_comparison", "visual_grammar": "line_time_series", "analysis_task_ids": [ "time_and_period_movement" ], "selection_tags": [ "period_movement", "period_gap_shape" ], "selection_emphasis": "trajectory_shape", "best_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "avoid_when": "Avoid when exact values, total reconciliation, or a two-endpoint before/after comparison is the main message.", "axis_roles": { "x": "ordered_period", "y": "metric", "series": "scenario_or_comparison_period" }, "period_semantics": { "role": "axis", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "current_period_metric", "baseline_period_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" } ], "minimum_source_metric_count": 1, "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimension_roles": [ "comparison_series" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "period_comparison.by_period", "period_comparison.time_series_table", "period_comparison.slope", "period_comparison.horizontal_waterfall", "mix.area", "mix.column", "mix.stacked_column", "mix.timeline", "period_comparison.multitier_column" ], "capability_id": "period_comparison.trend", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "period / year_over_year_line", "period / year_over_year_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for ordered period trajectory: acceleration, reversal, narrowing, widening, or seasonality.", "requires_question_focus": [ "trajectory_shape", "current_vs_baseline_period_axis" ], "reject_decision_cues": [ "asks for exact values", "asks for additive reconciliation", "asks for endpoint-only comparison" ], "forbidden_question_focus": [ "exact_period_values", "bridge_reconciliation", "endpoint_change" ], "period_scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "year_over_year_line" ], "variant_chart_options": [ "year_over_year_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "year_over_year_line" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "comparison_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [ { "role": "baseline_period_metric", "produced_from": [ "comparison_metric", "baseline_period" ], "derivation": "aggregate comparison_metric over the baseline period or scenario" }, { "role": "current_period_metric", "produced_from": [ "comparison_metric", "current_period" ], "derivation": "aggregate comparison_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_period_metric", "current_period_metric" ], "derivation": "current_period_metric - baseline_period_metric" } ], "display_metric_roles": [ "current_period_metric", "baseline_period_metric" ], "metric_selection_notes": [ "The chart needs one source metric plus two periods/scenarios; baseline/current/delta are display roles derived after period filtering." ] }, "dimensions": { "minimum_count": 0, "required_roles": [ "comparison_series" ], "optional_roles": [], "role_requirements": { "comparison_series": { "resolution_type": "derived_from_period_pair", "requires_profile_roles": [ "period" ], "output_role": "series label such as AC/PY, current/baseline, or scenario", "notes": "Derived after choosing the comparison periods; it is not a dataset column.", "role": "comparison_series", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "ordered_period", "y": "metric", "series": "scenario_or_comparison_period" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "reject_when": "Avoid when exact values, total reconciliation, or a two-endpoint before/after comparison is the main message.", "tie_breakers": [ { "against": "period_comparison.by_period", "choose_this_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "choose_other_when": "The reader needs weekly-average current and baseline values across overlapping 52-, 26-, 13- and 4-week recency windows.", "distinguishing_emphasis": { "this": "trajectory_shape", "other": "period_by_period_gap" } }, { "against": "period_comparison.time_series_table", "choose_this_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "choose_other_when": "The report needs citeable period values, deltas, and percent deltas rather than a primarily visual reading.", "distinguishing_emphasis": { "this": "trajectory_shape", "other": "exact_values" } }, { "against": "period_comparison.slope", "choose_this_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "choose_other_when": "The reader needs direction and magnitude of change between two endpoints, especially across multiple comparable items.", "distinguishing_emphasis": { "this": "trajectory_shape", "other": "endpoint_direction_and_relative_change" } }, { "against": "period_comparison.horizontal_waterfall", "choose_this_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "choose_other_when": "The reader needs to see how period variances add from previous total to current total.", "distinguishing_emphasis": { "this": "trajectory_shape", "other": "additive_reconciliation" } }, { "against": "mix.area", "choose_this_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "choose_other_when": "The reader needs a time-series area view for absolute contribution or share over periods.", "distinguishing_emphasis": { "this": "trajectory_shape", "other": "trend_with_cumulative_or_share_area" } }, { "against": "mix.column", "choose_this_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "choose_other_when": "The reader needs a compact total metric column view across selected periods or scopes.", "distinguishing_emphasis": { "this": "trajectory_shape", "other": "total_metric_by_period_or_scope" } }, { "against": "mix.stacked_column", "choose_this_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "choose_other_when": "The reader needs to see total and mix composition across periods or comparable scopes.", "distinguishing_emphasis": { "this": "trajectory_shape", "other": "composition_change_over_periods" } }, { "against": "mix.timeline", "choose_this_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "choose_other_when": "The reader needs the trend path of the primary mix metric across ordered periods.", "distinguishing_emphasis": { "this": "trajectory_shape", "other": "single_metric_trend_shape" } }, { "against": "period_comparison.multitier_column", "choose_this_when": "The reader needs to see the ordered period path: acceleration, reversal, narrowing, widening, or seasonality.", "choose_other_when": "The reader needs a compact executive AC/PY period comparison with clear column contrast.", "distinguishing_emphasis": { "this": "trajectory_shape", "other": "compact_side_by_side_period_comparison" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `period_comparison.trend` only when the task is one of ['time_and_period_movement'] and the required emphasis is `trajectory_shape`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "period_comparison.trend", "plugin_sources": [ "period-comparison" ], "artifact_labels": [ "period / year_over_year_line", "period / year_over_year_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_days", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "comparison_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "comparison_series", "required": true, "status": "mapped", "mapping_kind": "derived_from_period", "caller_binding_required": false, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null } ], "depends_on_role": "period_axis", "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "period / year_over_year_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "period / year_over_year_line", "plugin_source": "period-comparison", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "line", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "period / year_over_year_small_multiples", "plugin_source": "period-comparison", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "line", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.period_comparison", "legacy_plugin_source": "period-comparison", "component_name": "period-comparison", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/period-comparison/scripts/period_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "How did monthly cosmetics sales evolve versus previous year?" ], "negative_questions": [ { "question": "How do weekly-average AC/PY sales gaps differ across overlapping 52-, 26-, 13- and 4-week recency windows?", "why_not": "This asks for `period_by_period_gap`, not `trajectory_shape`.", "better_capability_id": "period_comparison.by_period" }, { "question": "Give citeable monthly AC/PY sales values and variances.", "why_not": "This asks for `exact_values`, not `trajectory_shape`.", "better_capability_id": "period_comparison.time_series_table" }, { "question": "Show endpoint direction and magnitude of category sales changes.", "why_not": "This asks for `endpoint_direction_and_relative_change`, not `trajectory_shape`.", "better_capability_id": "period_comparison.slope" }, { "question": "How do period variances reconcile prior-year sales to current sales?", "why_not": "This asks for `additive_reconciliation`, not `trajectory_shape`.", "better_capability_id": "period_comparison.horizontal_waterfall" }, { "question": "Show sales contribution as an area trend across months.", "why_not": "This asks for `trend_with_cumulative_or_share_area`, not `trajectory_shape`.", "better_capability_id": "mix.area" } ], "ambiguous_questions": [ { "question": "How did sales change over time?", "candidate_capability_ids": [ "period_comparison.trend", "period_comparison.by_period", "period_comparison.time_series_table", "period_comparison.slope", "period_comparison.horizontal_waterfall" ], "disambiguation_needed": "Clarify whether the intended focus is `trajectory_shape`, `period_by_period_gap`, `exact_values`, `endpoint_direction_and_relative_change`, `additive_reconciliation`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "scatter.bubble": { "family": "scatter_bubble", "visual_grammar": "bubble_relationship", "analysis_task_ids": [ "metric_relationship" ], "selection_tags": [ "metric_relationship", "size_weighted_outlier_detection" ], "selection_emphasis": "two_metric_relationship_plus_size", "best_when": "The reader needs x/y relationship plus magnitude encoded by bubble size.", "avoid_when": "Avoid when bubble size would obscure the relationship or when period movement is the question.", "axis_roles": { "x": "metric", "y": "metric", "size": "metric", "color_or_panel": "dimension" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "x_metric", "y_metric", "size_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "x_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" }, { "role": "y_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" }, { "role": "size_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "minimum_source_metric_count": 3, "metric_selection_notes": [ "Bubble size should be non-negative and comparable within the plotted scope." ] }, "dimension_roles": [ "point_dimension", "optional_panel" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "scatter.scatter", "mix.stacked_bar_overlay", "mix.barmekko" ], "capability_id": "scatter.bubble", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "scatter / scatter_bubble / bubble", "scatter / scatter_bubble / bubble_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for relationship between two metrics with a third metric encoded by size.", "requires_question_focus": [ "scatter_relationship", "size_encoding" ], "reject_decision_cues": [ "asks for unweighted relationship", "asks for ranked bars", "asks for time trend" ], "forbidden_question_focus": [ "plain_scatter", "single_metric_rank", "time_trend" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "bubble" ], "variant_chart_options": [ "bubble_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "bubble" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [ "scatter_bubble_review" ], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 3, "source_metric_roles": [ { "role": "x_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" }, { "role": "y_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" }, { "role": "size_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [], "display_metric_roles": [ "x_metric", "y_metric", "size_metric" ], "metric_selection_notes": [ "Bubble size should be non-negative and comparable within the plotted scope." ] }, "dimensions": { "minimum_count": 1, "required_roles": [ "point_dimension" ], "optional_roles": [ "optional_panel" ], "role_requirements": { "point_dimension": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "point_dimension", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "point_dimension", "required": true }, "optional_panel": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "panel", "notes": "Fallback direct dimension role; review this role if it becomes selection-critical.", "role": "optional_panel", "required": false } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "metric", "y": "metric", "size": "metric", "color_or_panel": "dimension" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs x/y relationship plus magnitude encoded by bubble size.", "reject_when": "Avoid when bubble size would obscure the relationship or when period movement is the question.", "tie_breakers": [ { "against": "scatter.scatter", "choose_this_when": "The reader needs x/y relationship plus magnitude encoded by bubble size.", "choose_other_when": "The reader needs to see association, clusters, quadrants, or outliers between two metrics.", "distinguishing_emphasis": { "this": "two_metric_relationship_plus_size", "other": "relationship_between_two_metrics" } }, { "against": "mix.stacked_bar_overlay", "choose_this_when": "The reader needs x/y relationship plus magnitude encoded by bubble size.", "choose_other_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "distinguishing_emphasis": { "this": "two_metric_relationship_plus_size", "other": "primary_rank_plus_secondary_marker" } }, { "against": "mix.barmekko", "choose_this_when": "The reader needs x/y relationship plus magnitude encoded by bubble size.", "choose_other_when": "The reader needs variable-width categories where width is an additive quantity, area is an additive value, and height is their derived ratio.", "distinguishing_emphasis": { "this": "two_metric_relationship_plus_size", "other": "width_metric_times_height_metric" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `scatter.bubble` only when the task is one of ['metric_relationship'] and the required emphasis is `two_metric_relationship_plus_size`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "scatter.bubble", "plugin_sources": [ "scatter-bubble-analysis" ], "artifact_labels": [ "scatter / scatter_bubble / bubble", "scatter / scatter_bubble / bubble_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "metric", "role": "x_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.x_metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "metric", "role": "y_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.y_metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "metric", "role": "size_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.bubble_size_metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "point_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dot_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_days", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "dimension", "role": "optional_panel", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "scatter / scatter_bubble / bubble_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "scatter / scatter_bubble / bubble", "plugin_source": "scatter-bubble-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "bubble", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "scatter / scatter_bubble / bubble_small_multiples", "plugin_source": "scatter-bubble-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "bubble", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.scatter_bubble", "legacy_plugin_source": "scatter-bubble-analysis", "component_name": "scatter-bubble-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/scatter-bubble-analysis/scripts/scatter_bubble_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Do units and sales share relate, weighted by sales?" ], "negative_questions": [ { "question": "Do units and sales share relate without size encoding?", "why_not": "This asks for `relationship_between_two_metrics`, not `two_metric_relationship_plus_size`.", "better_capability_id": "scatter.scatter" }, { "question": "Rank category sales while overlaying sales-share context.", "why_not": "This asks for `primary_rank_plus_secondary_marker`, not `two_metric_relationship_plus_size`.", "better_capability_id": "mix.stacked_bar_overlay" }, { "question": "Show category width and retailer height as a variable-width composition.", "why_not": "This asks for `width_metric_times_height_metric`, not `two_metric_relationship_plus_size`.", "better_capability_id": "mix.barmekko" }, { "question": "Show total monthly sales with sales-share marker context.", "why_not": "This asks for `total_plus_related_marker`, not `two_metric_relationship_plus_size`.", "better_capability_id": "mix.column_overlay" } ], "ambiguous_questions": [ { "question": "Show the relationship between metrics.", "candidate_capability_ids": [ "scatter.bubble", "scatter.scatter", "mix.stacked_bar_overlay", "mix.barmekko", "mix.column_overlay" ], "disambiguation_needed": "Clarify whether the intended focus is `two_metric_relationship_plus_size`, `relationship_between_two_metrics`, `primary_rank_plus_secondary_marker`, `width_metric_times_height_metric`, `total_plus_related_marker`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "scatter.scatter": { "family": "scatter_bubble", "visual_grammar": "scatter_relationship", "analysis_task_ids": [ "metric_relationship" ], "selection_tags": [ "metric_relationship", "outlier_detection" ], "selection_emphasis": "relationship_between_two_metrics", "best_when": "The reader needs to see association, clusters, quadrants, or outliers between two metrics.", "avoid_when": "Avoid for time trends, one-dimensional ranking, or exact tables.", "axis_roles": { "x": "metric", "y": "metric", "color_or_panel": "dimension" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ] }, "display_metric_roles": [ "x_metric", "y_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "x_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" }, { "role": "y_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [], "minimum_source_metric_count": 2, "metric_selection_notes": [] }, "dimension_roles": [ "point_dimension", "optional_panel" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "scatter.bubble", "mix.stacked_bar_overlay", "mix.bar", "mix.column_overlay" ], "capability_id": "scatter.scatter", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "scatter / scatter_bubble / scatter", "scatter / scatter_bubble / scatter_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for relationship between two metrics without size encoding.", "requires_question_focus": [ "scatter_relationship", "two_metrics" ], "reject_decision_cues": [ "asks for bubble size", "asks for category ranking", "asks for period gap" ], "forbidden_question_focus": [ "size_encoding", "single_metric_rank", "period_gap" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "scatter" ], "variant_chart_options": [ "scatter_small_multiples" ], "fixed_option_overrides": {}, "expected_artifact_stems": [ "scatter" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [ "scatter_bubble_review" ], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 2, "source_metric_roles": [ { "role": "x_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" }, { "role": "y_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count", "rate", "share", "index", "score", "numeric_observation" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [], "display_metric_roles": [ "x_metric", "y_metric" ], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 1, "required_roles": [ "point_dimension" ], "optional_roles": [ "optional_panel" ], "role_requirements": { "point_dimension": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "point_dimension", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "point_dimension", "required": true }, "optional_panel": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "panel", "notes": "Fallback direct dimension role; review this role if it becomes selection-critical.", "role": "optional_panel", "required": false } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "metric", "y": "metric", "color_or_panel": "dimension" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs to see association, clusters, quadrants, or outliers between two metrics.", "reject_when": "Avoid for time trends, one-dimensional ranking, or exact tables.", "tie_breakers": [ { "against": "scatter.bubble", "choose_this_when": "The reader needs to see association, clusters, quadrants, or outliers between two metrics.", "choose_other_when": "The reader needs x/y relationship plus magnitude encoded by bubble size.", "distinguishing_emphasis": { "this": "relationship_between_two_metrics", "other": "two_metric_relationship_plus_size" } }, { "against": "mix.stacked_bar_overlay", "choose_this_when": "The reader needs to see association, clusters, quadrants, or outliers between two metrics.", "choose_other_when": "The reader needs ranked contribution plus a related non-additive marker such as price, margin percentage, or growth.", "distinguishing_emphasis": { "this": "relationship_between_two_metrics", "other": "primary_rank_plus_secondary_marker" } }, { "against": "mix.bar", "choose_this_when": "The reader needs to see association, clusters, quadrants, or outliers between two metrics.", "choose_other_when": "The reader needs a sorted comparison of one additive metric across items for one selected scope or period.", "distinguishing_emphasis": { "this": "relationship_between_two_metrics", "other": "ranked_single_metric_comparison" } }, { "against": "mix.column_overlay", "choose_this_when": "The reader needs to see association, clusters, quadrants, or outliers between two metrics.", "choose_other_when": "The reader needs total metric movement with a related marker shown in the same compact view.", "distinguishing_emphasis": { "this": "relationship_between_two_metrics", "other": "total_plus_related_marker" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `scatter.scatter` only when the task is one of ['metric_relationship'] and the required emphasis is `relationship_between_two_metrics`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "scatter.scatter", "plugin_sources": [ "scatter-bubble-analysis" ], "artifact_labels": [ "scatter / scatter_bubble / scatter", "scatter / scatter_bubble / scatter_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "metric", "role": "x_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.x_metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "metric", "role": "y_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.y_metric_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "point_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dot_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.date_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_months", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.rolling_window_days", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.current_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.previous_period_label", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "dimension", "role": "optional_panel", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "scatter / scatter_bubble / scatter_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "scatter / scatter_bubble / scatter", "plugin_source": "scatter-bubble-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "scatter", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "scatter / scatter_bubble / scatter_small_multiples", "plugin_source": "scatter-bubble-analysis", "output_form": "chart_html", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "scatter", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.scatter_bubble", "legacy_plugin_source": "scatter-bubble-analysis", "component_name": "scatter-bubble-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "options.rolling_window_months", "options.rolling_window_days", "options.current_period_label", "options.previous_period_label", "filters", "options.filters" ], "verified_by": [ "plugins/scatter-bubble-analysis/scripts/scatter_bubble_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Do units and sales share relate without size encoding?" ], "negative_questions": [ { "question": "Do units and sales share relate, weighted by sales?", "why_not": "This asks for `two_metric_relationship_plus_size`, not `relationship_between_two_metrics`.", "better_capability_id": "scatter.bubble" }, { "question": "Rank category sales while overlaying sales-share context.", "why_not": "This asks for `primary_rank_plus_secondary_marker`, not `relationship_between_two_metrics`.", "better_capability_id": "mix.stacked_bar_overlay" }, { "question": "Rank categories by sales for a selected scope.", "why_not": "This asks for `ranked_single_metric_comparison`, not `relationship_between_two_metrics`.", "better_capability_id": "mix.bar" }, { "question": "Show total monthly sales with sales-share marker context.", "why_not": "This asks for `total_plus_related_marker`, not `relationship_between_two_metrics`.", "better_capability_id": "mix.column_overlay" } ], "ambiguous_questions": [ { "question": "Show the relationship between metrics.", "candidate_capability_ids": [ "scatter.scatter", "scatter.bubble", "mix.stacked_bar_overlay", "mix.bar", "mix.column_overlay" ], "disambiguation_needed": "Clarify whether the intended focus is `relationship_between_two_metrics`, `two_metric_relationship_plus_size`, `primary_rank_plus_secondary_marker`, `ranked_single_metric_comparison`, `total_plus_related_marker`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "set_overlap.upset": { "family": "set_overlap", "visual_grammar": "upset_plot", "analysis_task_ids": [ "set_overlap" ], "selection_tags": [ "set_overlap" ], "selection_emphasis": "many_set_intersections", "best_when": "The reader needs to compare intersections across more than two sets.", "avoid_when": "Avoid when only two or three simple sets need a familiar Venn view.", "axis_roles": { "x": "set_intersection", "y": "count" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.selected_period", "filters", "options.filters" ] }, "display_metric_roles": [], "metric_requirements": { "source_metric_roles": [], "derived_metric_roles": [], "minimum_source_metric_count": 0, "metric_selection_notes": [] }, "dimension_roles": [ "set_membership_fields" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "set_overlap.venn", "set_overlap.upset_small_multiples" ], "capability_id": "set_overlap.upset", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "set_overlap / upset" ], "example_count": 1, "primary_decision_cue": "Question asks for intersection patterns across several sets.", "requires_question_focus": [ "many_set_intersections", "set_membership" ], "reject_decision_cues": [ "asks for only two or three sets", "asks for panel comparison", "asks for metric distribution" ], "forbidden_question_focus": [ "simple_set_overlap", "set_overlap_panels", "distribution_shape" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_period", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "upset" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "upset" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_period", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 0, "source_metric_roles": [], "derived_metric_roles": [], "display_metric_roles": [], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 0, "required_roles": [ "set_membership_fields" ], "optional_roles": [], "role_requirements": { "set_membership_fields": { "resolution_type": "derived_set_membership", "requires_profile_roles": [ "set_item", "set_dimension" ], "output_role": "boolean membership fields for several sets", "notes": "Requires an item column and a low-cardinality set-defining column or equivalent membership fields.", "role": "set_membership_fields", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "set_intersection", "y": "count" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs to compare intersections across more than two sets.", "reject_when": "Avoid when only two or three simple sets need a familiar Venn view.", "tie_breakers": [ { "against": "set_overlap.venn", "choose_this_when": "The reader needs to compare intersections across more than two sets.", "choose_other_when": "The reader needs an intuitive overlap picture for two or three sets.", "distinguishing_emphasis": { "this": "many_set_intersections", "other": "simple_two_or_three_set_overlap" } }, { "against": "set_overlap.upset_small_multiples", "choose_this_when": "The reader needs to compare intersections across more than two sets.", "choose_other_when": "The reader needs to compare overlap structures across panels or segments.", "distinguishing_emphasis": { "this": "many_set_intersections", "other": "intersection_patterns_across_panels" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `set_overlap.upset` only when the task is one of ['set_overlap'] and the required emphasis is `many_set_intersections`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "set_overlap.upset", "plugin_sources": [ "set-overlap-analysis" ], "artifact_labels": [ "set_overlap / upset" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "dimension", "role": "set_membership_fields", "required": true, "status": "mapped", "mapping_kind": "compound", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.item_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.set_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.selected_period", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_period", "filters", "options.filters" ], "explicit_all_data_allowed": true } } ], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "set_overlap / upset", "plugin_source": "set-overlap-analysis", "output_form": "chart_html", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "upset", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.set_overlap", "legacy_plugin_source": "set-overlap-analysis", "component_name": "set-overlap-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.selected_period", "filters", "options.filters" ], "verified_by": [ "plugins/set-overlap-analysis/scripts/set_overlap_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Which brands are shared across retailers?" ], "negative_questions": [ { "question": "Show simple brand overlap across the three retailers.", "why_not": "This asks for `simple_two_or_three_set_overlap`, not `many_set_intersections`.", "better_capability_id": "set_overlap.venn" }, { "question": "How does brand overlap across retailers differ by category?", "why_not": "This asks for `intersection_patterns_across_panels`, not `many_set_intersections`.", "better_capability_id": "set_overlap.upset_small_multiples" } ], "ambiguous_questions": [ { "question": "Show overlap between groups.", "candidate_capability_ids": [ "set_overlap.upset", "set_overlap.venn", "set_overlap.upset_small_multiples" ], "disambiguation_needed": "Clarify whether the intended focus is `many_set_intersections`, `simple_two_or_three_set_overlap`, `intersection_patterns_across_panels`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "set_overlap.upset_small_multiples": { "family": "set_overlap", "visual_grammar": "upset_small_multiples", "analysis_task_ids": [ "set_overlap" ], "selection_tags": [ "set_overlap_by_panel" ], "selection_emphasis": "intersection_patterns_across_panels", "best_when": "The reader needs to compare overlap structures across panels or segments.", "avoid_when": "Avoid when one aggregate overlap view is enough.", "axis_roles": { "x": "set_intersection", "y": "count", "panel": "segment" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.selected_period", "filters", "options.filters" ] }, "display_metric_roles": [], "metric_requirements": { "source_metric_roles": [], "derived_metric_roles": [], "minimum_source_metric_count": 0, "metric_selection_notes": [] }, "dimension_roles": [ "set_membership_fields", "panel_or_segment" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "set_overlap.upset" ], "capability_id": "set_overlap.upset_small_multiples", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "set_overlap / set_overlap_small_multiples / upset_small_multiples" ], "example_count": 1, "primary_decision_cue": "Question asks how set intersection patterns differ across panels or segments.", "requires_question_focus": [ "set_overlap_panels", "many_set_intersections" ], "reject_decision_cues": [ "asks for one global upset plot", "asks for simple Venn", "asks for ranking" ], "forbidden_question_focus": [ "global_set_overlap", "simple_set_overlap", "single_metric_rank" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_period", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "upset_small_multiples" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "upset_small_multiples" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_period", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 0, "source_metric_roles": [], "derived_metric_roles": [], "display_metric_roles": [], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 1, "required_roles": [ "set_membership_fields", "panel_or_segment" ], "optional_roles": [], "role_requirements": { "set_membership_fields": { "resolution_type": "derived_set_membership", "requires_profile_roles": [ "set_item", "set_dimension" ], "output_role": "boolean membership fields for several sets", "notes": "Requires an item column and a low-cardinality set-defining column or equivalent membership fields.", "role": "set_membership_fields", "required": true }, "panel_or_segment": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "panel_or_segment", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "panel_or_segment", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "set_intersection", "y": "count", "panel": "segment" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs to compare overlap structures across panels or segments.", "reject_when": "Avoid when one aggregate overlap view is enough.", "tie_breakers": [ { "against": "set_overlap.upset", "choose_this_when": "The reader needs to compare overlap structures across panels or segments.", "choose_other_when": "The reader needs to compare intersections across more than two sets.", "distinguishing_emphasis": { "this": "intersection_patterns_across_panels", "other": "many_set_intersections" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `set_overlap.upset_small_multiples` only when the task is one of ['set_overlap'] and the required emphasis is `intersection_patterns_across_panels`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "set_overlap.upset_small_multiples", "plugin_sources": [ "set-overlap-analysis" ], "artifact_labels": [ "set_overlap / set_overlap_small_multiples / upset_small_multiples" ], "output_forms": [ "chart_html" ], "required_role_contracts": [ { "kind": "dimension", "role": "set_membership_fields", "required": true, "status": "mapped", "mapping_kind": "compound", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.item_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.set_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "panel_or_segment", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.selected_period", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_period", "filters", "options.filters" ], "explicit_all_data_allowed": true } } ], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "set_overlap / set_overlap_small_multiples / upset_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "set_overlap / set_overlap_small_multiples / upset_small_multiples", "plugin_source": "set-overlap-analysis", "output_form": "chart_html", "selector_level": "capability_choice", "layout_variant": "small_multiples", "encoding_variant": "upset", "variant_changes_capability_selection": true, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.set_overlap", "legacy_plugin_source": "set-overlap-analysis", "component_name": "set-overlap-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.selected_period", "filters", "options.filters" ], "verified_by": [ "plugins/set-overlap-analysis/scripts/set_overlap_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "How does brand overlap across retailers differ by category?" ], "negative_questions": [ { "question": "Which brands are shared across retailers?", "why_not": "This asks for `many_set_intersections`, not `intersection_patterns_across_panels`.", "better_capability_id": "set_overlap.upset" }, { "question": "Show simple brand overlap across the three retailers.", "why_not": "This asks for `simple_two_or_three_set_overlap`, not `intersection_patterns_across_panels`.", "better_capability_id": "set_overlap.venn" } ], "ambiguous_questions": [ { "question": "Show overlap between groups.", "candidate_capability_ids": [ "set_overlap.upset_small_multiples", "set_overlap.upset", "set_overlap.venn" ], "disambiguation_needed": "Clarify whether the intended focus is `intersection_patterns_across_panels`, `many_set_intersections`, `simple_two_or_three_set_overlap`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "set_overlap.venn": { "family": "set_overlap", "visual_grammar": "venn", "analysis_task_ids": [ "set_overlap" ], "selection_tags": [ "set_overlap" ], "selection_emphasis": "simple_two_or_three_set_overlap", "best_when": "The reader needs an intuitive overlap picture for two or three sets.", "avoid_when": "Avoid with more than three sets or many intersections.", "axis_roles": { "areas": "set_counts_and_intersections" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": false, "requires_comparison_pair": false, "minimum_distinct_values": 0, "accepted_scope_controls": [ "options.selected_period", "filters", "options.filters" ] }, "display_metric_roles": [], "metric_requirements": { "source_metric_roles": [], "derived_metric_roles": [], "minimum_source_metric_count": 0, "metric_selection_notes": [] }, "dimension_roles": [ "two_or_three_set_membership_fields" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "set_overlap.upset" ], "capability_id": "set_overlap.venn", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "set_overlap / venn" ], "example_count": 1, "primary_decision_cue": "Question asks for simple overlap among two or three sets.", "requires_question_focus": [ "simple_set_overlap", "two_or_three_sets" ], "reject_decision_cues": [ "asks for many-set intersections", "asks for panels", "asks for metric relationship" ], "forbidden_question_focus": [ "many_set_intersections", "set_overlap_panels", "metric_relationship" ], "period_scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_period", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [ "venn" ], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "venn" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": false, "comparison_pair_required": false, "minimum_distinct_values": 0, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "optional_filter_scope_or_explicit_all_data", "period_column_required": false, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 0, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_period", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 0, "source_metric_roles": [], "derived_metric_roles": [], "display_metric_roles": [], "metric_selection_notes": [] }, "dimensions": { "minimum_count": 0, "required_roles": [ "two_or_three_set_membership_fields" ], "optional_roles": [], "role_requirements": { "two_or_three_set_membership_fields": { "resolution_type": "derived_set_membership", "requires_profile_roles": [ "set_item", "set_dimension" ], "output_role": "boolean membership fields for two or three sets", "notes": "Requires an item column and a set-defining column with two or three chosen set values.", "role": "two_or_three_set_membership_fields", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "areas": "set_counts_and_intersections" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs an intuitive overlap picture for two or three sets.", "reject_when": "Avoid with more than three sets or many intersections.", "tie_breakers": [ { "against": "set_overlap.upset", "choose_this_when": "The reader needs an intuitive overlap picture for two or three sets.", "choose_other_when": "The reader needs to compare intersections across more than two sets.", "distinguishing_emphasis": { "this": "simple_two_or_three_set_overlap", "other": "many_set_intersections" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `set_overlap.venn` only when the task is one of ['set_overlap'] and the required emphasis is `simple_two_or_three_set_overlap`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "set_overlap.venn", "plugin_sources": [ "set-overlap-analysis" ], "artifact_labels": [ "set_overlap / venn" ], "output_forms": [ "chart_png" ], "required_role_contracts": [ { "kind": "dimension", "role": "two_or_three_set_membership_fields", "required": true, "status": "mapped", "mapping_kind": "compound", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.item_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.set_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [ { "kind": "period", "role": "period_filter", "required": false, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.selected_period", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": false, "scope_required_for_render": true, "accepted_scope_controls": [ "options.selected_period", "filters", "options.filters" ], "explicit_all_data_allowed": true } } ], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "set_overlap / venn", "plugin_source": "set-overlap-analysis", "output_form": "chart_png", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "venn", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.set_overlap", "legacy_plugin_source": "set-overlap-analysis", "component_name": "set-overlap-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.selected_period", "filters", "options.filters" ], "verified_by": [ "plugins/set-overlap-analysis/scripts/set_overlap_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Show simple brand overlap across the three retailers." ], "negative_questions": [ { "question": "Which brands are shared across retailers?", "why_not": "This asks for `many_set_intersections`, not `simple_two_or_three_set_overlap`.", "better_capability_id": "set_overlap.upset" }, { "question": "How does brand overlap across retailers differ by category?", "why_not": "This asks for `intersection_patterns_across_panels`, not `simple_two_or_three_set_overlap`.", "better_capability_id": "set_overlap.upset_small_multiples" } ], "ambiguous_questions": [ { "question": "Show overlap between groups.", "candidate_capability_ids": [ "set_overlap.venn", "set_overlap.upset", "set_overlap.upset_small_multiples" ], "disambiguation_needed": "Clarify whether the intended focus is `simple_two_or_three_set_overlap`, `many_set_intersections`, `intersection_patterns_across_panels`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "statement.pnl_table": { "family": "statement", "visual_grammar": "pnl_statement_table", "analysis_task_ids": [ "evidence_and_reporting_tables" ], "selection_tags": [ "financial_statement" ], "selection_emphasis": "structured_statement_values", "best_when": "The reader needs a P&L-style table with business rows and comparison columns.", "avoid_when": "Avoid for exploratory charting or relationship analysis.", "axis_roles": { "rows": "statement_line_item", "columns": "period_or_scenario" }, "period_semantics": { "role": "axis_or_table", "supports_period_axis": true, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": false, "minimum_distinct_values": 1, "accepted_scope_controls": [ "periods" ] }, "display_metric_roles": [ "statement_value" ], "metric_requirements": { "source_metric_roles": [ { "role": "statement_value", "required": true, "accepted_metric_classes": [ "additive_value" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [], "minimum_source_metric_count": 1, "metric_selection_notes": [ "Statement tables require a statement line-item dimension, not just a numeric value column." ] }, "dimension_roles": [ "statement_line_item", "statement_scenario", "statement_structure" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [], "capability_id": "statement.pnl_table", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "statement / pnl_statement_table" ], "example_count": 1, "primary_decision_cue": "Question asks for structured P&L or statement line-item values.", "requires_question_focus": [ "statement_table", "line_item_values" ], "reject_decision_cues": [ "asks for charted trend", "asks for distribution", "asks for variance bridge" ], "forbidden_question_focus": [ "time_trend", "distribution_shape", "variance_bridge" ], "period_scope_contract": { "role": "axis_or_table", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 1, "scope_required_for_render": false, "accepted_scope_controls": [ "periods" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." }, "render_contract": { "schema_version": "0.1", "chart_options": [], "variant_chart_options": [], "fixed_option_overrides": {}, "expected_artifact_stems": [ "pnl_statement_table" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "axis_or_table", "required": true, "comparison_pair_required": false, "minimum_distinct_values": 1, "requires_period_axis": true, "allows_period_filter": true, "scope_contract": { "role": "axis_or_table", "status": "scope_optional_bounded_question", "period_column_required": true, "comparison_pair_required_for_render": false, "minimum_distinct_period_values": 1, "scope_required_for_render": false, "accepted_scope_controls": [ "periods" ], "explicit_all_data_allowed": true, "unscoped_default": "available_period_axis", "selector_warning": "A period-axis chart may intentionally show the available time range; pass a period scope when the requested analysis is bounded." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "statement_value", "required": true, "accepted_metric_classes": [ "additive_value" ], "aggregation": "semantic_layer_defined" } ], "derived_metric_roles": [], "display_metric_roles": [ "statement_value" ], "metric_selection_notes": [ "Statement tables require a statement line-item dimension, not just a numeric value column." ] }, "dimensions": { "minimum_count": 2, "required_roles": [ "statement_line_item", "statement_scenario", "statement_structure" ], "optional_roles": [], "role_requirements": { "statement_line_item": { "resolution_type": "schema_role", "requires_profile_roles": [ "statement_line_item" ], "output_role": "financial statement line item", "notes": "Requires a structured statement table, not generic dimensions.", "role": "statement_line_item", "required": true }, "statement_scenario": { "resolution_type": "schema_role", "requires_profile_roles": [ "statement_scenario" ], "output_role": "statement scenario such as actual, plan, or forecast", "notes": "Requires an explicit scenario column in the statement value table.", "role": "statement_scenario", "required": true }, "statement_structure": { "resolution_type": "semantic_or_package_role", "requires_profile_roles": [ "statement_recipe" ], "output_role": "ordered statement rows, formulas, periods, and scenarios", "notes": "Requires an explicit statement recipe; column names alone do not define P&L ordering or formulas.", "role": "statement_structure", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "rows": "statement_line_item", "columns": "period_or_scenario" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "The reader needs a P&L-style table with business rows and comparison columns.", "reject_when": "Avoid for exploratory charting or relationship analysis.", "tie_breakers": [], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `statement.pnl_table` only when the task is one of ['evidence_and_reporting_tables'] and the required emphasis is `structured_statement_values`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "statement.pnl_table", "plugin_sources": [ "statement-analysis" ], "artifact_labels": [ "statement / pnl_statement_table" ], "output_forms": [ "table_html" ], "required_role_contracts": [ { "kind": "period", "role": "period_axis", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "periods", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": false, "accepted_scope_controls": [ "periods" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "statement_value", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.value_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "statement_line_item", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.row_key_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "statement_scenario", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.scenario_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "statement_structure", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "statement_rows", "recipe_path": null }, { "target_type": "recipe_path", "target": "periods", "recipe_path": null }, { "target_type": "recipe_path", "target": "scenarios_by_period", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "statement / pnl_statement_table", "plugin_source": "statement-analysis", "output_form": "table_html", "selector_level": "base_capability", "layout_variant": "table", "encoding_variant": "table", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.statement", "legacy_plugin_source": "statement-analysis", "component_name": "statement-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "periods" ], "verified_by": [ "plugins/statement-analysis/scripts/statement_core.py:_validate_recipe" ] } } }, "selection_examples": { "positive_questions": [ "Build a P&L line-item table." ], "negative_questions": [ { "question": "How do current winning attribute bundles align or diverge from emerging signals?", "why_not": "This asks for `current_vs_emerging_signal_alignment`, not `structured_statement_values`.", "better_capability_id": "attributes.attribute_bridge_table" }, { "question": "Show exact share, delta, and index evidence for selected attribute bundles.", "why_not": "This asks for `bundle_share_and_index_evidence`, not `structured_statement_values`.", "better_capability_id": "attributes.attribute_bundle_comparison_table" }, { "question": "Which products provide evidence for the selected attribute signal?", "why_not": "This asks for `product_level_grounding`, not `structured_statement_values`.", "better_capability_id": "attributes.product_signal_evidence_table" }, { "question": "Which attribute bundles have rank-weighted visibility evidence?", "why_not": "This asks for `rank_weighted_visibility`, not `structured_statement_values`.", "better_capability_id": "attributes.rank_weighted_visibility_table" }, { "question": "What is the stage conversion funnel?", "why_not": "This asks for `stage_counts_and_conversion`, not `structured_statement_values`.", "better_capability_id": "funnel.stage_table" } ], "ambiguous_questions": [ { "question": "Show the supporting evidence table.", "candidate_capability_ids": [ "statement.pnl_table", "attributes.attribute_bridge_table", "attributes.attribute_bundle_comparison_table", "attributes.product_signal_evidence_table", "attributes.rank_weighted_visibility_table" ], "disambiguation_needed": "Clarify whether the intended focus is `structured_statement_values`, `current_vs_emerging_signal_alignment`, `bundle_share_and_index_evidence`, `product_level_grounding`, `rank_weighted_visibility`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "variance.exploded_variance_bridge": { "family": "variance", "visual_grammar": "parent_child_variance_bridge", "analysis_task_ids": [ "variance_and_bridge" ], "selection_tags": [ "variance_drilldown" ], "selection_emphasis": "parent_bridge_with_child_drilldowns", "best_when": "Use when the question names one parent grouping dimension and one fixed second decomposition dimension to explain selected parent-row variance moves in the same visual.", "avoid_when": "Avoid when only one dimension is requested, when the second dimension is not meaningful within each parent member, when the task is a variable mixed-dimension root-cause ordering, when PVM mechanics are required, or when exact tabular detail is the deliverable.", "axis_roles": { "x": "parent_and_child_driver", "y": "metric_delta" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ] }, "display_metric_roles": [ "baseline_metric", "current_metric", "delta_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "variance_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [ { "role": "baseline_metric", "produced_from": [ "variance_metric", "baseline_period_or_scenario" ], "derivation": "aggregate variance_metric over the baseline period or scenario" }, { "role": "current_metric", "produced_from": [ "variance_metric", "current_period_or_scenario" ], "derivation": "aggregate variance_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_metric", "current_metric" ], "derivation": "current_metric - baseline_metric" } ], "minimum_source_metric_count": 1, "metric_selection_notes": [ "Variance bridges require an additive source metric; baseline/current/delta are derived display roles." ] }, "dimension_roles": [ "parent_driver", "child_driver" ], "dimension_contract": { "required_roles": [ "parent_driver", "child_driver" ], "distinct_dimensions_required": true, "parent_dimension_behavior": "Left panel ranks members of one fixed parent dimension by total delta.", "child_dimension_behavior": "Right-side drilldown panels decompose selected parent members by one fixed child/decomposition dimension.", "child_dimension_scope": "constant_across_all_drilldown_panels", "child_dimension_meaning": "The second dimension should be a natural child of the parent or a meaningful within-parent cross-cut. This semantic validity is dataset/question-specific.", "selector_responsibility": "The selector/orchestrator must choose both dimensions from the question, dataset profile, and semantic validity layer. Plugin fallback order is mechanical and must not be treated as semantic dimension selection.", "not_a_root_cause_path": "Rows do not switch dimensional grain. Use root-cause bridge capabilities when the analysis needs a variable mixed-dimension driver path." }, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "variance.root_cause_exploded_bridge", "variance.root_cause_component_bridge", "variance.total_by_dimension_bridge" ], "capability_id": "variance.exploded_variance_bridge", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "variance / exploded_variance_bridge" ], "example_count": 1, "primary_decision_cue": "Question asks for one fixed parent dimension variance bridge plus child drilldowns for selected rows.", "requires_question_focus": [ "fixed_parent_child_drilldown", "variance_bridge" ], "reject_decision_cues": [ "asks for variable root-cause sequence", "asks for plain bridge", "asks for PVM mechanics" ], "forbidden_question_focus": [ "root_cause_sequence", "scenario_bridge", "pvm_decomposition" ], "period_scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [], "variant_chart_options": [], "fixed_option_overrides": { "exploded_variance_bridge": true, "pvm_decomposition_ladder": false, "root_cause_bridge": false, "root_cause_component_bridge": false, "total_by_dimension_bridge": false, "waterfall_chart": false, "waterfall_small_multiples": false }, "expected_artifact_stems": [ "exploded_variance_bridge" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "variance_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [ { "role": "baseline_metric", "produced_from": [ "variance_metric", "baseline_period_or_scenario" ], "derivation": "aggregate variance_metric over the baseline period or scenario" }, { "role": "current_metric", "produced_from": [ "variance_metric", "current_period_or_scenario" ], "derivation": "aggregate variance_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_metric", "current_metric" ], "derivation": "current_metric - baseline_metric" } ], "display_metric_roles": [ "baseline_metric", "current_metric", "delta_metric" ], "metric_selection_notes": [ "Variance bridges require an additive source metric; baseline/current/delta are derived display roles." ] }, "dimensions": { "minimum_count": 2, "required_roles": [ "parent_driver", "child_driver" ], "optional_roles": [], "role_requirements": { "parent_driver": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "parent_driver", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "parent_driver", "required": true }, "child_driver": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "child_driver", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "child_driver", "required": true } }, "dimension_contract": { "required_roles": [ "parent_driver", "child_driver" ], "distinct_dimensions_required": true, "parent_dimension_behavior": "Left panel ranks members of one fixed parent dimension by total delta.", "child_dimension_behavior": "Right-side drilldown panels decompose selected parent members by one fixed child/decomposition dimension.", "child_dimension_scope": "constant_across_all_drilldown_panels", "child_dimension_meaning": "The second dimension should be a natural child of the parent or a meaningful within-parent cross-cut. This semantic validity is dataset/question-specific.", "selector_responsibility": "The selector/orchestrator must choose both dimensions from the question, dataset profile, and semantic validity layer. Plugin fallback order is mechanical and must not be treated as semantic dimension selection.", "not_a_root_cause_path": "Rows do not switch dimensional grain. Use root-cause bridge capabilities when the analysis needs a variable mixed-dimension driver path." } }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "parent_and_child_driver", "y": "metric_delta" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "Use when the question names one parent grouping dimension and one fixed second decomposition dimension to explain selected parent-row variance moves in the same visual.", "reject_when": "Avoid when only one dimension is requested, when the second dimension is not meaningful within each parent member, when the task is a variable mixed-dimension root-cause ordering, when PVM mechanics are required, or when exact tabular detail is the deliverable.", "tie_breakers": [ { "against": "variance.root_cause_exploded_bridge", "choose_this_when": "Use when the question names one parent grouping dimension and one fixed second decomposition dimension to explain selected parent-row variance moves in the same visual.", "choose_other_when": "Use when the question asks for a variable mixed-dimension root-cause variance path and also asks to explain selected root-cause drivers with nested root-cause bridge drilldowns.", "distinguishing_emphasis": { "this": "parent_bridge_with_child_drilldowns", "other": "root_cause_path_with_nested_drilldowns" } }, { "against": "variance.root_cause_component_bridge", "choose_this_when": "Use when the question names one parent grouping dimension and one fixed second decomposition dimension to explain selected parent-row variance moves in the same visual.", "choose_other_when": "Use when the question asks which price, units, and mix component-by-dimension combinations explain movement, rather than which dimensions explain the total variance.", "distinguishing_emphasis": { "this": "parent_bridge_with_child_drilldowns", "other": "component_level_root_cause" } }, { "against": "variance.total_by_dimension_bridge", "choose_this_when": "Use when the question names one parent grouping dimension and one fixed second decomposition dimension to explain selected parent-row variance moves in the same visual.", "choose_other_when": "Use when the question explicitly asks how the total delta is distributed across members of one named dimension, such as category, retailer, region, brand, or channel.", "distinguishing_emphasis": { "this": "parent_bridge_with_child_drilldowns", "other": "total_delta_split_by_dimension" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `variance.exploded_variance_bridge` only when the task is one of ['variance_and_bridge'] and the required emphasis is `parent_bridge_with_child_drilldowns`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "variance.exploded_variance_bridge", "plugin_sources": [ "variance-analysis" ], "artifact_labels": [ "variance / exploded_variance_bridge" ], "output_forms": [ "chart_png" ], "required_role_contracts": [ { "kind": "period", "role": "period_filter", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.baseline_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.comparison_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "variance_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "parent_driver", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.exploded_variance_bridge_parent_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "child_driver", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.exploded_variance_bridge_child_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [ { "kind": "variant", "role": "drilldown_selection", "required": true, "status": "mapped", "mapping_kind": "compound", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.root_cause_bridge_alternative_result", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.root_cause_bridge_drilldown_rows", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "variance / exploded_variance_bridge" } ], "artifact_invocation_contracts": [ { "artifact_label": "variance / exploded_variance_bridge", "plugin_source": "variance-analysis", "output_form": "chart_png", "selector_level": "capability_choice", "layout_variant": "nested_drilldown", "encoding_variant": "bridge", "variant_changes_capability_selection": true, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "drilldown_selection", "required": true, "status": "mapped", "mapping_kind": "compound", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.root_cause_bridge_alternative_result", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.root_cause_bridge_drilldown_rows", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.variance", "legacy_plugin_source": "variance-analysis", "component_name": "variance-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "verified_by": [ "plugins/variance-analysis/scripts/variance_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Which categories drove variance, and which brands explain the selected category moves?" ], "negative_questions": [ { "question": "Which ordered root-cause path explains the total sales movement, and what explains the selected root-cause driver?", "why_not": "This asks for `root_cause_path_with_nested_drilldowns`, not `parent_bridge_with_child_drilldowns`.", "better_capability_id": "variance.root_cause_exploded_bridge" }, { "question": "Which dimension combinations explain the price component of sales movement?", "why_not": "This asks for `component_level_root_cause`, not `parent_bridge_with_child_drilldowns`.", "better_capability_id": "variance.root_cause_component_bridge" }, { "question": "Which categories account for the total sales variance?", "why_not": "This asks for `total_delta_split_by_dimension`, not `parent_bridge_with_child_drilldowns`.", "better_capability_id": "variance.total_by_dimension_bridge" }, { "question": "How do period variances reconcile prior-year sales to current sales?", "why_not": "This asks for `additive_reconciliation`, not `parent_bridge_with_child_drilldowns`.", "better_capability_id": "period_comparison.horizontal_waterfall" }, { "question": "How much of the sales movement is due to price, units, and mix?", "why_not": "This asks for `pvm_decomposition_comparison`, not `parent_bridge_with_child_drilldowns`.", "better_capability_id": "variance.price_volume_mix" } ], "ambiguous_questions": [ { "question": "Explain the sales variance.", "candidate_capability_ids": [ "variance.exploded_variance_bridge", "variance.root_cause_exploded_bridge", "variance.root_cause_component_bridge", "variance.total_by_dimension_bridge", "period_comparison.horizontal_waterfall" ], "disambiguation_needed": "Clarify whether the intended focus is `parent_bridge_with_child_drilldowns`, `root_cause_path_with_nested_drilldowns`, `component_level_root_cause`, `total_delta_split_by_dimension`, `additive_reconciliation`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "variance.price_volume_mix": { "family": "variance", "visual_grammar": "price_volume_mix_ladder", "analysis_task_ids": [ "variance_and_bridge" ], "selection_tags": [ "price_volume_mix" ], "selection_emphasis": "pvm_decomposition_comparison", "best_when": "Use only when the business question explicitly asks how value movement decomposes into price, volume, and mix effects, and the dataset has compatible value, units/volume, and price or derived price semantics.", "avoid_when": "Avoid for generic variance explanations, one-dimension splits, root-cause ordering, or any dataset without compatible value, volume, and rate semantics at the same grain.", "axis_roles": { "x": "decomposition_stage", "y": "metric_delta" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ] }, "display_metric_roles": [ "value_metric", "volume_metric", "price_or_rate_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "value_metric", "required": true, "accepted_metric_classes": [ "additive_value" ], "aggregation": "sum" }, { "role": "volume_metric", "required": true, "accepted_metric_classes": [ "additive_volume" ], "aggregation": "sum" } ], "derived_metric_roles": [ { "role": "price_or_rate_metric", "produced_from": [ "value_metric", "volume_metric" ], "derivation": "value_metric divided by volume_metric at the analysis grain" }, { "role": "price_effect", "produced_from": [ "value_metric", "volume_metric", "price_or_rate_metric" ], "derivation": "plugin decomposition formula" }, { "role": "volume_effect", "produced_from": [ "value_metric", "volume_metric" ], "derivation": "plugin decomposition formula" }, { "role": "mix_effect", "produced_from": [ "value_metric", "volume_metric", "price_or_rate_metric" ], "derivation": "plugin decomposition formula at the selected analysis grain; mix is a structural PVM component, not a required dataset dimension parameter" } ], "minimum_source_metric_count": 2, "metric_selection_notes": [ "PVM requires additive value and volume at the same grain; the plugin derives price/rate and the price, volume, and mix effects." ] }, "dimension_roles": [ "period_or_scenario_pair" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "variance.scenario_bridge", "variance.root_cause_total_bridge", "variance.total_by_dimension_bridge" ], "capability_id": "variance.price_volume_mix", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "variance / pvm_decomposition_ladder" ], "example_count": 1, "primary_decision_cue": "Question explicitly asks how movement decomposes into price, volume, and mix effects.", "requires_question_focus": [ "pvm_decomposition", "price_volume_mix" ], "reject_decision_cues": [ "asks for generic variance bridge", "asks for dimension split", "asks for root-cause ordering" ], "forbidden_question_focus": [ "scenario_bridge", "dimension_variance", "root_cause_sequence" ], "period_scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [], "variant_chart_options": [], "fixed_option_overrides": { "pvm_decomposition_ladder": true, "exploded_variance_bridge": false, "root_cause_bridge": false, "root_cause_component_bridge": false, "total_by_dimension_bridge": false, "waterfall_chart": false, "waterfall_small_multiples": false }, "expected_artifact_stems": [ "pvm_decomposition_ladder" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 2, "source_metric_roles": [ { "role": "value_metric", "required": true, "accepted_metric_classes": [ "additive_value" ], "aggregation": "sum" }, { "role": "volume_metric", "required": true, "accepted_metric_classes": [ "additive_volume" ], "aggregation": "sum" } ], "derived_metric_roles": [ { "role": "price_or_rate_metric", "produced_from": [ "value_metric", "volume_metric" ], "derivation": "value_metric divided by volume_metric at the analysis grain" }, { "role": "price_effect", "produced_from": [ "value_metric", "volume_metric", "price_or_rate_metric" ], "derivation": "plugin decomposition formula" }, { "role": "volume_effect", "produced_from": [ "value_metric", "volume_metric" ], "derivation": "plugin decomposition formula" }, { "role": "mix_effect", "produced_from": [ "value_metric", "volume_metric", "price_or_rate_metric" ], "derivation": "plugin decomposition formula at the selected analysis grain; mix is a structural PVM component, not a required dataset dimension parameter" } ], "display_metric_roles": [ "value_metric", "volume_metric", "price_or_rate_metric" ], "metric_selection_notes": [ "PVM requires additive value and volume at the same grain; the plugin derives price/rate and the price, volume, and mix effects." ] }, "dimensions": { "minimum_count": 0, "required_roles": [ "period_or_scenario_pair" ], "optional_roles": [], "role_requirements": { "period_or_scenario_pair": { "resolution_type": "derived_period_or_scenario_pair", "requires_profile_roles": [ "period" ], "output_role": "baseline/current period or scenario pair", "notes": "Can be produced from a period column; scenario dimensions can be used when present.", "role": "period_or_scenario_pair", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "decomposition_stage", "y": "metric_delta" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "Use only when the business question explicitly asks how value movement decomposes into price, volume, and mix effects, and the dataset has compatible value, units/volume, and price or derived price semantics.", "reject_when": "Avoid for generic variance explanations, one-dimension splits, root-cause ordering, or any dataset without compatible value, volume, and rate semantics at the same grain.", "tie_breakers": [ { "against": "variance.scenario_bridge", "choose_this_when": "Use only when the business question explicitly asks how value movement decomposes into price, volume, and mix effects, and the dataset has compatible value, units/volume, and price or derived price semantics.", "choose_other_when": "Use for the plain bridge from one baseline total to one current total when the message is the additive reconciliation itself, not a ranked dimension split, root-cause path, or PVM mechanics.", "distinguishing_emphasis": { "this": "pvm_decomposition_comparison", "other": "scenario_reconciliation" } }, { "against": "variance.root_cause_total_bridge", "choose_this_when": "Use only when the business question explicitly asks how value movement decomposes into price, volume, and mix effects, and the dataset has compatible value, units/volume, and price or derived price semantics.", "choose_other_when": "Use when the question asks for the ordered root-cause sequence behind the total movement across available dimensions, and the output should show which driver path explains the overall delta.", "distinguishing_emphasis": { "this": "pvm_decomposition_comparison", "other": "root_cause_total_movement" } }, { "against": "variance.total_by_dimension_bridge", "choose_this_when": "Use only when the business question explicitly asks how value movement decomposes into price, volume, and mix effects, and the dataset has compatible value, units/volume, and price or derived price semantics.", "choose_other_when": "Use when the question explicitly asks how the total delta is distributed across members of one named dimension, such as category, retailer, region, brand, or channel.", "distinguishing_emphasis": { "this": "pvm_decomposition_comparison", "other": "total_delta_split_by_dimension" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `variance.price_volume_mix` only when the task is one of ['variance_and_bridge'] and the required emphasis is `pvm_decomposition_comparison`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "variance.price_volume_mix", "plugin_sources": [ "variance-analysis" ], "artifact_labels": [ "variance / pvm_decomposition_ladder" ], "output_forms": [ "chart_png" ], "required_role_contracts": [ { "kind": "period", "role": "period_filter", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.baseline_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.comparison_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "value_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "metric", "role": "volume_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.units_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "period_or_scenario_pair", "required": true, "status": "mapped", "mapping_kind": "derived_from_period", "caller_binding_required": false, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.baseline_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.comparison_period", "recipe_path": null } ], "depends_on_role": "period_filter", "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "variance / pvm_decomposition_ladder", "plugin_source": "variance-analysis", "output_form": "chart_png", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "pvm_ladder", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.variance", "legacy_plugin_source": "variance-analysis", "component_name": "variance-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "verified_by": [ "plugins/variance-analysis/scripts/variance_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "How much of the sales movement is due to price, units, and mix?" ], "negative_questions": [ { "question": "Reconcile total sales from baseline to current with a plain bridge.", "why_not": "This asks for `scenario_reconciliation`, not `pvm_decomposition_comparison`.", "better_capability_id": "variance.scenario_bridge" }, { "question": "Which ordered root-cause path explains the total sales movement?", "why_not": "This asks for `root_cause_total_movement`, not `pvm_decomposition_comparison`.", "better_capability_id": "variance.root_cause_total_bridge" }, { "question": "Which categories account for the total sales variance?", "why_not": "This asks for `total_delta_split_by_dimension`, not `pvm_decomposition_comparison`.", "better_capability_id": "variance.total_by_dimension_bridge" }, { "question": "How do period variances reconcile prior-year sales to current sales?", "why_not": "This asks for `additive_reconciliation`, not `pvm_decomposition_comparison`.", "better_capability_id": "period_comparison.horizontal_waterfall" }, { "question": "Which categories drove variance, and which brands explain the selected category moves?", "why_not": "This asks for `parent_bridge_with_child_drilldowns`, not `pvm_decomposition_comparison`.", "better_capability_id": "variance.exploded_variance_bridge" } ], "ambiguous_questions": [ { "question": "Explain the sales variance.", "candidate_capability_ids": [ "variance.price_volume_mix", "variance.scenario_bridge", "variance.root_cause_total_bridge", "variance.total_by_dimension_bridge", "period_comparison.horizontal_waterfall" ], "disambiguation_needed": "Clarify whether the intended focus is `pvm_decomposition_comparison`, `scenario_reconciliation`, `root_cause_total_movement`, `total_delta_split_by_dimension`, `additive_reconciliation`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "variance.root_cause_component_bridge": { "family": "variance", "visual_grammar": "root_cause_component_bridge", "analysis_task_ids": [ "variance_and_bridge" ], "selection_tags": [ "root_cause_variance" ], "selection_emphasis": "component_level_root_cause", "best_when": "Use when the question asks which price, units, and mix component-by-dimension combinations explain movement, rather than which dimensions explain the total variance.", "avoid_when": "Avoid when units/volume is unavailable, when fewer than two candidate driver dimensions exist, when the report needs the total-variance root-cause sequence, or when a simple PVM ladder is sufficient.", "axis_roles": { "x": "component_and_root_cause_driver_sequence", "y": "component_delta" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ] }, "display_metric_roles": [ "component_delta" ], "metric_requirements": { "source_metric_roles": [ { "role": "value_metric", "required": true, "accepted_metric_classes": [ "additive_value" ], "aggregation": "sum" }, { "role": "volume_metric", "required": true, "accepted_metric_classes": [ "additive_volume" ], "aggregation": "sum" } ], "derived_metric_roles": [ { "role": "component_delta", "produced_from": [ "value_metric", "volume_metric", "baseline_period_or_scenario", "current_period_or_scenario" ], "derivation": "plugin component-variance calculation producing price, units, and mix component rows" } ], "minimum_source_metric_count": 2, "metric_selection_notes": [ "The component root-cause bridge requires additive value and units/volume at the same grain; component labels and deltas are calculated by the plugin." ] }, "dimension_roles": [ "component_root_cause_driver_sequence" ], "dimension_contract": { "required_roles": [ "component_root_cause_driver_sequence" ], "minimum_driver_dimensions": 2, "component_behavior": "Price, units, and mix components are calculated from the selected value metric, units/volume metric, and comparison periods; they are not selected from a dataset dimension.", "driver_behavior": "The plugin ranks component-by-dimension candidates across the available driver dimensions and returns an ordered sequence." }, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "variance.root_cause_total_bridge", "variance.total_by_dimension_bridge", "variance.exploded_variance_bridge", "variance.root_cause_exploded_bridge" ], "capability_id": "variance.root_cause_component_bridge", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "variance / root_cause_component_bridge" ], "example_count": 1, "primary_decision_cue": "Question asks which dimension-and-component combinations explain movement through price, units, and mix effects.", "requires_question_focus": [ "component_root_cause", "price_units_mix_components" ], "reject_decision_cues": [ "asks for total root-cause path", "asks for plain bridge", "asks for PVM mechanics" ], "forbidden_question_focus": [ "total_root_cause", "scenario_bridge", "pvm_decomposition" ], "period_scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [], "variant_chart_options": [], "fixed_option_overrides": { "exploded_variance_bridge": false, "pvm_decomposition_ladder": false, "root_cause_bridge": true, "root_cause_bridge_alternative_sweep": false, "root_cause_component_bridge": true, "total_by_dimension_bridge": false, "waterfall_chart": false, "waterfall_small_multiples": false }, "expected_artifact_stems": [ "root_cause_component_bridge" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [ "root_cause_total_bridge" ], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 2, "source_metric_roles": [ { "role": "value_metric", "required": true, "accepted_metric_classes": [ "additive_value" ], "aggregation": "sum" }, { "role": "volume_metric", "required": true, "accepted_metric_classes": [ "additive_volume" ], "aggregation": "sum" } ], "derived_metric_roles": [ { "role": "component_delta", "produced_from": [ "value_metric", "volume_metric", "baseline_period_or_scenario", "current_period_or_scenario" ], "derivation": "plugin component-variance calculation producing price, units, and mix component rows" } ], "display_metric_roles": [ "component_delta" ], "metric_selection_notes": [ "The component root-cause bridge requires additive value and units/volume at the same grain; component labels and deltas are calculated by the plugin." ] }, "dimensions": { "minimum_count": 0, "required_roles": [ "component_root_cause_driver_sequence" ], "optional_roles": [], "role_requirements": { "component_root_cause_driver_sequence": { "resolution_type": "derived_root_cause_sequence", "requires_profile_roles": [ "period", "direct_dimension" ], "minimum_candidate_count": 2, "requires_non_bijective_dimension_pair": true, "output_role": "ordered mixed-dimension component-variance driver sequence", "notes": "The runtime derives price, units, and mix component rows from value and units, then orders component-by-dimension candidates across at least two driver dimensions.", "role": "component_root_cause_driver_sequence", "required": true } }, "dimension_contract": { "required_roles": [ "component_root_cause_driver_sequence" ], "minimum_driver_dimensions": 2, "component_behavior": "Price, units, and mix components are calculated from the selected value metric, units/volume metric, and comparison periods; they are not selected from a dataset dimension.", "driver_behavior": "The plugin ranks component-by-dimension candidates across the available driver dimensions and returns an ordered sequence." } }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "component_and_root_cause_driver_sequence", "y": "component_delta" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "Use when the question asks which price, units, and mix component-by-dimension combinations explain movement, rather than which dimensions explain the total variance.", "reject_when": "Avoid when units/volume is unavailable, when fewer than two candidate driver dimensions exist, when the report needs the total-variance root-cause sequence, or when a simple PVM ladder is sufficient.", "tie_breakers": [ { "against": "variance.root_cause_total_bridge", "choose_this_when": "Use when the question asks which price, units, and mix component-by-dimension combinations explain movement, rather than which dimensions explain the total variance.", "choose_other_when": "Use when the question asks for the ordered root-cause sequence behind the total movement across available dimensions, and the output should show which driver path explains the overall delta.", "distinguishing_emphasis": { "this": "component_level_root_cause", "other": "root_cause_total_movement" } }, { "against": "variance.total_by_dimension_bridge", "choose_this_when": "Use when the question asks which price, units, and mix component-by-dimension combinations explain movement, rather than which dimensions explain the total variance.", "choose_other_when": "Use when the question explicitly asks how the total delta is distributed across members of one named dimension, such as category, retailer, region, brand, or channel.", "distinguishing_emphasis": { "this": "component_level_root_cause", "other": "total_delta_split_by_dimension" } }, { "against": "variance.exploded_variance_bridge", "choose_this_when": "Use when the question asks which price, units, and mix component-by-dimension combinations explain movement, rather than which dimensions explain the total variance.", "choose_other_when": "Use when the question names one parent grouping dimension and one fixed second decomposition dimension to explain selected parent-row variance moves in the same visual.", "distinguishing_emphasis": { "this": "component_level_root_cause", "other": "parent_bridge_with_child_drilldowns" } }, { "against": "variance.root_cause_exploded_bridge", "choose_this_when": "Use when the question asks which price, units, and mix component-by-dimension combinations explain movement, rather than which dimensions explain the total variance.", "choose_other_when": "Use when the question asks for a variable mixed-dimension root-cause variance path and also asks to explain selected root-cause drivers with nested root-cause bridge drilldowns.", "distinguishing_emphasis": { "this": "component_level_root_cause", "other": "root_cause_path_with_nested_drilldowns" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `variance.root_cause_component_bridge` only when the task is one of ['variance_and_bridge'] and the required emphasis is `component_level_root_cause`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "variance.root_cause_component_bridge", "plugin_sources": [ "variance-analysis" ], "artifact_labels": [ "variance / root_cause_component_bridge" ], "output_forms": [ "chart_png" ], "required_role_contracts": [ { "kind": "period", "role": "period_filter", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.baseline_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.comparison_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "value_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "metric", "role": "volume_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.units_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "component_root_cause_driver_sequence", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "variance / root_cause_component_bridge", "plugin_source": "variance-analysis", "output_form": "chart_png", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "bridge", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.variance", "legacy_plugin_source": "variance-analysis", "component_name": "variance-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "verified_by": [ "plugins/variance-analysis/scripts/variance_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Which dimension combinations explain the price component of sales movement?" ], "negative_questions": [ { "question": "Which ordered root-cause path explains the total sales movement?", "why_not": "This asks for `root_cause_total_movement`, not `component_level_root_cause`.", "better_capability_id": "variance.root_cause_total_bridge" }, { "question": "Which categories account for the total sales variance?", "why_not": "This asks for `total_delta_split_by_dimension`, not `component_level_root_cause`.", "better_capability_id": "variance.total_by_dimension_bridge" }, { "question": "Which categories drove variance, and which brands explain the selected category moves?", "why_not": "This asks for `parent_bridge_with_child_drilldowns`, not `component_level_root_cause`.", "better_capability_id": "variance.exploded_variance_bridge" }, { "question": "Which ordered root-cause path explains the total sales movement, and what explains the selected root-cause driver?", "why_not": "This asks for `root_cause_path_with_nested_drilldowns`, not `component_level_root_cause`.", "better_capability_id": "variance.root_cause_exploded_bridge" }, { "question": "How do period variances reconcile prior-year sales to current sales?", "why_not": "This asks for `additive_reconciliation`, not `component_level_root_cause`.", "better_capability_id": "period_comparison.horizontal_waterfall" } ], "ambiguous_questions": [ { "question": "Explain the sales variance.", "candidate_capability_ids": [ "variance.root_cause_component_bridge", "variance.root_cause_total_bridge", "variance.total_by_dimension_bridge", "variance.exploded_variance_bridge", "variance.root_cause_exploded_bridge" ], "disambiguation_needed": "Clarify whether the intended focus is `component_level_root_cause`, `root_cause_total_movement`, `total_delta_split_by_dimension`, `parent_bridge_with_child_drilldowns`, `root_cause_path_with_nested_drilldowns`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "variance.root_cause_exploded_bridge": { "family": "variance", "visual_grammar": "root_cause_exploded_bridge", "analysis_task_ids": [ "variance_and_bridge" ], "selection_tags": [ "root_cause_variance", "variance_drilldown" ], "selection_emphasis": "root_cause_path_with_nested_drilldowns", "best_when": "Use when the question asks for a variable mixed-dimension root-cause variance path and also asks to explain selected root-cause drivers with nested root-cause bridge drilldowns.", "avoid_when": "Avoid when the question names a fixed parent dimension and fixed child decomposition dimension; use variance.exploded_variance_bridge instead. Avoid when only a one-level root-cause path is needed, or when exact tabular detail is the deliverable.", "axis_roles": { "left": "root_cause_driver_sequence", "right": "nested_root_cause_driver_sequence", "y": "metric_delta" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ] }, "display_metric_roles": [ "baseline_metric", "current_metric", "delta_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "variance_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [ { "role": "baseline_metric", "produced_from": [ "variance_metric", "baseline_period_or_scenario" ], "derivation": "aggregate variance_metric over the baseline period or scenario" }, { "role": "current_metric", "produced_from": [ "variance_metric", "current_period_or_scenario" ], "derivation": "aggregate variance_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_metric", "current_metric" ], "derivation": "current_metric - baseline_metric" } ], "minimum_source_metric_count": 1, "metric_selection_notes": [ "Variance bridges require an additive source metric; baseline/current/delta are derived display roles." ] }, "dimension_roles": [ "root_cause_driver_sequence", "drilldown_selection" ], "dimension_contract": { "required_roles": [ "root_cause_driver_sequence", "drilldown_selection" ], "optional_roles": [], "left_panel_behavior": "Left panel shows a variable mixed-dimension root-cause bridge sequence.", "right_panel_behavior": "Right-side panels rerun or nest root-cause bridge logic inside selected left-row slices.", "nested_dimension_scope": "row_specific", "drilldown_binding_phase": "after_candidate_sequence_review", "drilldown_candidate_source": "alternative sequences and left-sequence rows with available detail rows", "selector_responsibility": "Use only when the question asks for root causes plus explanation of selected drivers. Do not select a fixed child dimension for all right-side panels.", "not_a_fixed_parent_child_bridge": "Rows may switch dimensional grain. Use variance.exploded_variance_bridge for a fixed parent_dimension plus fixed child_dimension." }, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "variance.root_cause_total_bridge", "variance.exploded_variance_bridge", "variance.root_cause_component_bridge" ], "capability_id": "variance.root_cause_exploded_bridge", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "variance / root_cause_exploded_bridge" ], "example_count": 1, "primary_decision_cue": "Question asks for ordered root-cause path plus nested drilldown for selected drivers.", "requires_question_focus": [ "root_cause_sequence", "nested_driver_drilldown" ], "reject_decision_cues": [ "asks for fixed parent-child dimensions", "asks for total path only", "asks for PVM mechanics" ], "forbidden_question_focus": [ "fixed_parent_child_drilldown", "total_root_cause_only", "pvm_decomposition" ], "period_scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [], "variant_chart_options": [], "fixed_option_overrides": { "exploded_variance_bridge": false, "pvm_decomposition_ladder": false, "root_cause_bridge": true, "root_cause_bridge_alternative_sweep": false, "root_cause_component_bridge": false, "total_by_dimension_bridge": false, "waterfall_chart": false, "waterfall_small_multiples": false }, "expected_artifact_stems": [], "expected_artifact_stem_templates": [ { "template": "root_cause_total_bridge_drilldown_row_{value}", "role": "drilldown_selection", "binding_key": "root_cause_bridge_drilldown_rows", "for_each": true } ], "allowed_support_artifact_stems": [ "root_cause_total_bridge" ], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "variance_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [ { "role": "baseline_metric", "produced_from": [ "variance_metric", "baseline_period_or_scenario" ], "derivation": "aggregate variance_metric over the baseline period or scenario" }, { "role": "current_metric", "produced_from": [ "variance_metric", "current_period_or_scenario" ], "derivation": "aggregate variance_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_metric", "current_metric" ], "derivation": "current_metric - baseline_metric" } ], "display_metric_roles": [ "baseline_metric", "current_metric", "delta_metric" ], "metric_selection_notes": [ "Variance bridges require an additive source metric; baseline/current/delta are derived display roles." ] }, "dimensions": { "minimum_count": 0, "required_roles": [ "root_cause_driver_sequence", "drilldown_selection" ], "optional_roles": [], "role_requirements": { "root_cause_driver_sequence": { "resolution_type": "derived_root_cause_sequence", "requires_profile_roles": [ "period", "direct_dimension" ], "minimum_candidate_count": 2, "requires_non_bijective_dimension_pair": true, "output_role": "ordered mixed-dimension driver sequence", "notes": "The candidate driver dimensions are mechanical; ordering and business validity are selected later.", "role": "root_cause_driver_sequence", "required": true }, "drilldown_selection": { "resolution_type": "structural_row_selection", "requires_profile_roles": [], "output_role": "selected root-cause alternative plus one-based rows to drill into", "notes": "A caller selects an alternative sequence and rows only after finding a sequence with available child detail; these are runtime structural values, not dataset columns.", "role": "drilldown_selection", "required": true } }, "dimension_contract": { "required_roles": [ "root_cause_driver_sequence", "drilldown_selection" ], "optional_roles": [], "left_panel_behavior": "Left panel shows a variable mixed-dimension root-cause bridge sequence.", "right_panel_behavior": "Right-side panels rerun or nest root-cause bridge logic inside selected left-row slices.", "nested_dimension_scope": "row_specific", "drilldown_binding_phase": "after_candidate_sequence_review", "drilldown_candidate_source": "alternative sequences and left-sequence rows with available detail rows", "selector_responsibility": "Use only when the question asks for root causes plus explanation of selected drivers. Do not select a fixed child dimension for all right-side panels.", "not_a_fixed_parent_child_bridge": "Rows may switch dimensional grain. Use variance.exploded_variance_bridge for a fixed parent_dimension plus fixed child_dimension." } }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "left": "root_cause_driver_sequence", "right": "nested_root_cause_driver_sequence", "y": "metric_delta" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "Use when the question asks for a variable mixed-dimension root-cause variance path and also asks to explain selected root-cause drivers with nested root-cause bridge drilldowns.", "reject_when": "Avoid when the question names a fixed parent dimension and fixed child decomposition dimension; use variance.exploded_variance_bridge instead. Avoid when only a one-level root-cause path is needed, or when exact tabular detail is the deliverable.", "tie_breakers": [ { "against": "variance.root_cause_total_bridge", "choose_this_when": "Use when the question asks for a variable mixed-dimension root-cause variance path and also asks to explain selected root-cause drivers with nested root-cause bridge drilldowns.", "choose_other_when": "Use when the question asks for the ordered root-cause sequence behind the total movement across available dimensions, and the output should show which driver path explains the overall delta.", "distinguishing_emphasis": { "this": "root_cause_path_with_nested_drilldowns", "other": "root_cause_total_movement" } }, { "against": "variance.exploded_variance_bridge", "choose_this_when": "Use when the question asks for a variable mixed-dimension root-cause variance path and also asks to explain selected root-cause drivers with nested root-cause bridge drilldowns.", "choose_other_when": "Use when the question names one parent grouping dimension and one fixed second decomposition dimension to explain selected parent-row variance moves in the same visual.", "distinguishing_emphasis": { "this": "root_cause_path_with_nested_drilldowns", "other": "parent_bridge_with_child_drilldowns" } }, { "against": "variance.root_cause_component_bridge", "choose_this_when": "Use when the question asks for a variable mixed-dimension root-cause variance path and also asks to explain selected root-cause drivers with nested root-cause bridge drilldowns.", "choose_other_when": "Use when the question asks which price, units, and mix component-by-dimension combinations explain movement, rather than which dimensions explain the total variance.", "distinguishing_emphasis": { "this": "root_cause_path_with_nested_drilldowns", "other": "component_level_root_cause" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `variance.root_cause_exploded_bridge` only when the task is one of ['variance_and_bridge'] and the required emphasis is `root_cause_path_with_nested_drilldowns`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "variance.root_cause_exploded_bridge", "plugin_sources": [ "variance-analysis" ], "artifact_labels": [ "variance / root_cause_exploded_bridge" ], "output_forms": [ "chart_png" ], "required_role_contracts": [ { "kind": "period", "role": "period_filter", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.baseline_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.comparison_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "variance_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "root_cause_driver_sequence", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "drilldown_selection", "required": true, "status": "mapped", "mapping_kind": "compound", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.root_cause_bridge_alternative_result", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.root_cause_bridge_drilldown_rows", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [ { "kind": "variant", "role": "drilldown_selection", "required": true, "status": "mapped", "mapping_kind": "compound", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.root_cause_bridge_alternative_result", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.root_cause_bridge_drilldown_rows", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "variance / root_cause_exploded_bridge" } ], "artifact_invocation_contracts": [ { "artifact_label": "variance / root_cause_exploded_bridge", "plugin_source": "variance-analysis", "output_form": "chart_png", "selector_level": "capability_choice", "layout_variant": "nested_drilldown", "encoding_variant": "bridge", "variant_changes_capability_selection": true, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "drilldown_selection", "required": true, "status": "mapped", "mapping_kind": "compound", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.root_cause_bridge_alternative_result", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.root_cause_bridge_drilldown_rows", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.variance", "legacy_plugin_source": "variance-analysis", "component_name": "variance-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "verified_by": [ "plugins/variance-analysis/scripts/variance_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Which ordered root-cause path explains the total sales movement, and what explains the selected root-cause driver?" ], "negative_questions": [ { "question": "Which ordered root-cause path explains the total sales movement?", "why_not": "This asks for `root_cause_total_movement`, not `root_cause_path_with_nested_drilldowns`.", "better_capability_id": "variance.root_cause_total_bridge" }, { "question": "Which categories drove variance, and which brands explain the selected category moves?", "why_not": "This asks for `parent_bridge_with_child_drilldowns`, not `root_cause_path_with_nested_drilldowns`.", "better_capability_id": "variance.exploded_variance_bridge" }, { "question": "Which dimension combinations explain the price component of sales movement?", "why_not": "This asks for `component_level_root_cause`, not `root_cause_path_with_nested_drilldowns`.", "better_capability_id": "variance.root_cause_component_bridge" }, { "question": "How do period variances reconcile prior-year sales to current sales?", "why_not": "This asks for `additive_reconciliation`, not `root_cause_path_with_nested_drilldowns`.", "better_capability_id": "period_comparison.horizontal_waterfall" }, { "question": "How much of the sales movement is due to price, units, and mix?", "why_not": "This asks for `pvm_decomposition_comparison`, not `root_cause_path_with_nested_drilldowns`.", "better_capability_id": "variance.price_volume_mix" } ], "ambiguous_questions": [ { "question": "Explain the sales variance.", "candidate_capability_ids": [ "variance.root_cause_exploded_bridge", "variance.root_cause_total_bridge", "variance.exploded_variance_bridge", "variance.root_cause_component_bridge", "period_comparison.horizontal_waterfall" ], "disambiguation_needed": "Clarify whether the intended focus is `root_cause_path_with_nested_drilldowns`, `root_cause_total_movement`, `parent_bridge_with_child_drilldowns`, `component_level_root_cause`, `additive_reconciliation`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "variance.root_cause_total_bridge": { "family": "variance", "visual_grammar": "root_cause_total_bridge", "analysis_task_ids": [ "variance_and_bridge" ], "selection_tags": [ "root_cause_variance" ], "selection_emphasis": "root_cause_total_movement", "best_when": "Use when the question asks for the ordered root-cause sequence behind the total movement across available dimensions, and the output should show which driver path explains the overall delta.", "avoid_when": "Avoid for a simple total bridge, a one-dimension split, a component-only root-cause question, or PVM decomposition.", "axis_roles": { "x": "ordered_root_cause_driver", "y": "metric_delta" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ] }, "display_metric_roles": [ "baseline_metric", "current_metric", "delta_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "variance_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [ { "role": "baseline_metric", "produced_from": [ "variance_metric", "baseline_period_or_scenario" ], "derivation": "aggregate variance_metric over the baseline period or scenario" }, { "role": "current_metric", "produced_from": [ "variance_metric", "current_period_or_scenario" ], "derivation": "aggregate variance_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_metric", "current_metric" ], "derivation": "current_metric - baseline_metric" } ], "minimum_source_metric_count": 1, "metric_selection_notes": [ "Variance bridges require an additive source metric; baseline/current/delta are derived display roles." ] }, "dimension_roles": [ "root_cause_driver_sequence" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "variance.root_cause_exploded_bridge", "variance.total_by_dimension_bridge", "variance.root_cause_component_bridge", "variance.scenario_bridge", "variance.price_volume_mix" ], "capability_id": "variance.root_cause_total_bridge", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "variance / root_cause_total_bridge" ], "example_count": 1, "primary_decision_cue": "Question asks for ordered root-cause path explaining total movement.", "requires_question_focus": [ "root_cause_sequence", "total_movement" ], "reject_decision_cues": [ "asks for selected component", "asks for nested drilldown", "asks for fixed dimension split" ], "forbidden_question_focus": [ "component_root_cause", "nested_driver_drilldown", "dimension_variance" ], "period_scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [], "variant_chart_options": [], "fixed_option_overrides": { "exploded_variance_bridge": false, "pvm_decomposition_ladder": false, "root_cause_bridge": true, "root_cause_bridge_alternative_sweep": false, "root_cause_component_bridge": false, "total_by_dimension_bridge": false, "waterfall_chart": false, "waterfall_small_multiples": false }, "expected_artifact_stems": [ "root_cause_total_bridge" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "variance_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [ { "role": "baseline_metric", "produced_from": [ "variance_metric", "baseline_period_or_scenario" ], "derivation": "aggregate variance_metric over the baseline period or scenario" }, { "role": "current_metric", "produced_from": [ "variance_metric", "current_period_or_scenario" ], "derivation": "aggregate variance_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_metric", "current_metric" ], "derivation": "current_metric - baseline_metric" } ], "display_metric_roles": [ "baseline_metric", "current_metric", "delta_metric" ], "metric_selection_notes": [ "Variance bridges require an additive source metric; baseline/current/delta are derived display roles." ] }, "dimensions": { "minimum_count": 0, "required_roles": [ "root_cause_driver_sequence" ], "optional_roles": [], "role_requirements": { "root_cause_driver_sequence": { "resolution_type": "derived_root_cause_sequence", "requires_profile_roles": [ "period", "direct_dimension" ], "minimum_candidate_count": 2, "requires_non_bijective_dimension_pair": true, "output_role": "ordered mixed-dimension driver sequence", "notes": "The candidate driver dimensions are mechanical; ordering and business validity are selected later.", "role": "root_cause_driver_sequence", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "ordered_root_cause_driver", "y": "metric_delta" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "Use when the question asks for the ordered root-cause sequence behind the total movement across available dimensions, and the output should show which driver path explains the overall delta.", "reject_when": "Avoid for a simple total bridge, a one-dimension split, a component-only root-cause question, or PVM decomposition.", "tie_breakers": [ { "against": "variance.root_cause_exploded_bridge", "choose_this_when": "Use when the question asks for the ordered root-cause sequence behind the total movement across available dimensions, and the output should show which driver path explains the overall delta.", "choose_other_when": "Use when the question asks for a variable mixed-dimension root-cause variance path and also asks to explain selected root-cause drivers with nested root-cause bridge drilldowns.", "distinguishing_emphasis": { "this": "root_cause_total_movement", "other": "root_cause_path_with_nested_drilldowns" } }, { "against": "variance.total_by_dimension_bridge", "choose_this_when": "Use when the question asks for the ordered root-cause sequence behind the total movement across available dimensions, and the output should show which driver path explains the overall delta.", "choose_other_when": "Use when the question explicitly asks how the total delta is distributed across members of one named dimension, such as category, retailer, region, brand, or channel.", "distinguishing_emphasis": { "this": "root_cause_total_movement", "other": "total_delta_split_by_dimension" } }, { "against": "variance.root_cause_component_bridge", "choose_this_when": "Use when the question asks for the ordered root-cause sequence behind the total movement across available dimensions, and the output should show which driver path explains the overall delta.", "choose_other_when": "Use when the question asks which price, units, and mix component-by-dimension combinations explain movement, rather than which dimensions explain the total variance.", "distinguishing_emphasis": { "this": "root_cause_total_movement", "other": "component_level_root_cause" } }, { "against": "variance.scenario_bridge", "choose_this_when": "Use when the question asks for the ordered root-cause sequence behind the total movement across available dimensions, and the output should show which driver path explains the overall delta.", "choose_other_when": "Use for the plain bridge from one baseline total to one current total when the message is the additive reconciliation itself, not a ranked dimension split, root-cause path, or PVM mechanics.", "distinguishing_emphasis": { "this": "root_cause_total_movement", "other": "scenario_reconciliation" } }, { "against": "variance.price_volume_mix", "choose_this_when": "Use when the question asks for the ordered root-cause sequence behind the total movement across available dimensions, and the output should show which driver path explains the overall delta.", "choose_other_when": "Use only when the business question explicitly asks how value movement decomposes into price, volume, and mix effects, and the dataset has compatible value, units/volume, and price or derived price semantics.", "distinguishing_emphasis": { "this": "root_cause_total_movement", "other": "pvm_decomposition_comparison" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `variance.root_cause_total_bridge` only when the task is one of ['variance_and_bridge'] and the required emphasis is `root_cause_total_movement`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "variance.root_cause_total_bridge", "plugin_sources": [ "variance-analysis" ], "artifact_labels": [ "variance / root_cause_total_bridge" ], "output_forms": [ "chart_png" ], "required_role_contracts": [ { "kind": "period", "role": "period_filter", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.baseline_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.comparison_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "variance_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "root_cause_driver_sequence", "required": true, "status": "mapped", "mapping_kind": "collection", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.dimensions", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "variance / root_cause_total_bridge", "plugin_source": "variance-analysis", "output_form": "chart_png", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "bridge", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.variance", "legacy_plugin_source": "variance-analysis", "component_name": "variance-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "verified_by": [ "plugins/variance-analysis/scripts/variance_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Which ordered root-cause path explains the total sales movement?" ], "negative_questions": [ { "question": "Which ordered root-cause path explains the total sales movement, and what explains the selected root-cause driver?", "why_not": "This asks for `root_cause_path_with_nested_drilldowns`, not `root_cause_total_movement`.", "better_capability_id": "variance.root_cause_exploded_bridge" }, { "question": "Which categories account for the total sales variance?", "why_not": "This asks for `total_delta_split_by_dimension`, not `root_cause_total_movement`.", "better_capability_id": "variance.total_by_dimension_bridge" }, { "question": "Which dimension combinations explain the price component of sales movement?", "why_not": "This asks for `component_level_root_cause`, not `root_cause_total_movement`.", "better_capability_id": "variance.root_cause_component_bridge" }, { "question": "Reconcile total sales from baseline to current with a plain bridge.", "why_not": "This asks for `scenario_reconciliation`, not `root_cause_total_movement`.", "better_capability_id": "variance.scenario_bridge" }, { "question": "How much of the sales movement is due to price, units, and mix?", "why_not": "This asks for `pvm_decomposition_comparison`, not `root_cause_total_movement`.", "better_capability_id": "variance.price_volume_mix" } ], "ambiguous_questions": [ { "question": "Explain the sales variance.", "candidate_capability_ids": [ "variance.root_cause_total_bridge", "variance.root_cause_exploded_bridge", "variance.total_by_dimension_bridge", "variance.root_cause_component_bridge", "variance.scenario_bridge" ], "disambiguation_needed": "Clarify whether the intended focus is `root_cause_total_movement`, `root_cause_path_with_nested_drilldowns`, `total_delta_split_by_dimension`, `component_level_root_cause`, `scenario_reconciliation`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "variance.scenario_bridge": { "family": "variance", "visual_grammar": "variance_waterfall", "analysis_task_ids": [ "variance_and_bridge" ], "selection_tags": [ "variance_bridge" ], "selection_emphasis": "scenario_reconciliation", "best_when": "Use for the plain bridge from one baseline total to one current total when the message is the additive reconciliation itself, not a ranked dimension split, root-cause path, or PVM mechanics.", "avoid_when": "Avoid when the question names a dimension to split by, asks for nested drilldowns, asks why via root-cause ordering, asks for price/volume/mix, or when trend shape is the message.", "axis_roles": { "x": "variance_step", "y": "metric_delta" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ] }, "display_metric_roles": [ "baseline_metric", "current_metric", "delta_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "variance_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [ { "role": "baseline_metric", "produced_from": [ "variance_metric", "baseline_period_or_scenario" ], "derivation": "aggregate variance_metric over the baseline period or scenario" }, { "role": "current_metric", "produced_from": [ "variance_metric", "current_period_or_scenario" ], "derivation": "aggregate variance_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_metric", "current_metric" ], "derivation": "current_metric - baseline_metric" } ], "minimum_source_metric_count": 1, "metric_selection_notes": [ "Variance bridges require an additive source metric; baseline/current/delta are derived display roles." ] }, "dimension_roles": [ "variance_step" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "period_comparison.horizontal_waterfall", "variance.total_by_dimension_bridge", "variance.root_cause_total_bridge", "variance.price_volume_mix" ], "capability_id": "variance.scenario_bridge", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "variance / waterfall", "variance / waterfall_small_multiples" ], "example_count": 2, "primary_decision_cue": "Question asks for a plain reconciliation from baseline or scenario to current total.", "requires_question_focus": [ "scenario_bridge", "baseline_to_current_total" ], "reject_decision_cues": [ "asks for dimension contributors", "asks for root-cause ordering", "asks for PVM mechanics" ], "forbidden_question_focus": [ "dimension_variance", "root_cause_sequence", "pvm_decomposition" ], "period_scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [], "variant_chart_options": [], "fixed_option_overrides": { "exploded_variance_bridge": false, "pvm_decomposition_ladder": false, "root_cause_bridge": false, "root_cause_component_bridge": false, "total_by_dimension_bridge": false, "waterfall_chart": true, "waterfall_small_multiples": false }, "expected_artifact_stems": [ "waterfall" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "variance_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [ { "role": "baseline_metric", "produced_from": [ "variance_metric", "baseline_period_or_scenario" ], "derivation": "aggregate variance_metric over the baseline period or scenario" }, { "role": "current_metric", "produced_from": [ "variance_metric", "current_period_or_scenario" ], "derivation": "aggregate variance_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_metric", "current_metric" ], "derivation": "current_metric - baseline_metric" } ], "display_metric_roles": [ "baseline_metric", "current_metric", "delta_metric" ], "metric_selection_notes": [ "Variance bridges require an additive source metric; baseline/current/delta are derived display roles." ] }, "dimensions": { "minimum_count": 0, "required_roles": [ "variance_step" ], "optional_roles": [], "role_requirements": { "variance_step": { "resolution_type": "structural_variance_step", "requires_profile_roles": [], "output_role": "baseline, component deltas, and current total rows", "notes": "Structural rows produced by the variance renderer after baseline/current aggregation.", "role": "variance_step", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "variance_step", "y": "metric_delta" } }, "implementation_evidence": { "gallery_example_count": 2, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "Use for the plain bridge from one baseline total to one current total when the message is the additive reconciliation itself, not a ranked dimension split, root-cause path, or PVM mechanics.", "reject_when": "Avoid when the question names a dimension to split by, asks for nested drilldowns, asks why via root-cause ordering, asks for price/volume/mix, or when trend shape is the message.", "tie_breakers": [ { "against": "period_comparison.horizontal_waterfall", "choose_this_when": "Use for the plain bridge from one baseline total to one current total when the message is the additive reconciliation itself, not a ranked dimension split, root-cause path, or PVM mechanics.", "choose_other_when": "The reader needs to see how period variances add from previous total to current total.", "distinguishing_emphasis": { "this": "scenario_reconciliation", "other": "additive_reconciliation" } }, { "against": "variance.total_by_dimension_bridge", "choose_this_when": "Use for the plain bridge from one baseline total to one current total when the message is the additive reconciliation itself, not a ranked dimension split, root-cause path, or PVM mechanics.", "choose_other_when": "Use when the question explicitly asks how the total delta is distributed across members of one named dimension, such as category, retailer, region, brand, or channel.", "distinguishing_emphasis": { "this": "scenario_reconciliation", "other": "total_delta_split_by_dimension" } }, { "against": "variance.root_cause_total_bridge", "choose_this_when": "Use for the plain bridge from one baseline total to one current total when the message is the additive reconciliation itself, not a ranked dimension split, root-cause path, or PVM mechanics.", "choose_other_when": "Use when the question asks for the ordered root-cause sequence behind the total movement across available dimensions, and the output should show which driver path explains the overall delta.", "distinguishing_emphasis": { "this": "scenario_reconciliation", "other": "root_cause_total_movement" } }, { "against": "variance.price_volume_mix", "choose_this_when": "Use for the plain bridge from one baseline total to one current total when the message is the additive reconciliation itself, not a ranked dimension split, root-cause path, or PVM mechanics.", "choose_other_when": "Use only when the business question explicitly asks how value movement decomposes into price, volume, and mix effects, and the dataset has compatible value, units/volume, and price or derived price semantics.", "distinguishing_emphasis": { "this": "scenario_reconciliation", "other": "pvm_decomposition_comparison" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `variance.scenario_bridge` only when the task is one of ['variance_and_bridge'] and the required emphasis is `scenario_reconciliation`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "variance.scenario_bridge", "plugin_sources": [ "variance-analysis" ], "artifact_labels": [ "variance / waterfall", "variance / waterfall_small_multiples" ], "output_forms": [ "chart_png" ], "required_role_contracts": [ { "kind": "period", "role": "period_filter", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.baseline_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.comparison_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "variance_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "variance_step", "required": true, "status": "mapped", "mapping_kind": "derived_from_period", "caller_binding_required": false, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.baseline_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.comparison_period", "recipe_path": null } ], "depends_on_role": "period_filter", "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.waterfall_small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": "variance / waterfall_small_multiples" } ], "artifact_invocation_contracts": [ { "artifact_label": "variance / waterfall", "plugin_source": "variance-analysis", "output_form": "chart_png", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "bridge", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] }, { "artifact_label": "variance / waterfall_small_multiples", "plugin_source": "variance-analysis", "output_form": "chart_png", "selector_level": "rendering_variant_choice", "layout_variant": "small_multiples", "encoding_variant": "bridge", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [ { "kind": "variant", "role": "panel_dimension", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.waterfall_small_multiples_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 2, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.variance", "legacy_plugin_source": "variance-analysis", "component_name": "variance-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "verified_by": [ "plugins/variance-analysis/scripts/variance_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Reconcile total sales from baseline to current with a plain bridge." ], "negative_questions": [ { "question": "How do period variances reconcile prior-year sales to current sales?", "why_not": "This asks for `additive_reconciliation`, not `scenario_reconciliation`.", "better_capability_id": "period_comparison.horizontal_waterfall" }, { "question": "Which categories account for the total sales variance?", "why_not": "This asks for `total_delta_split_by_dimension`, not `scenario_reconciliation`.", "better_capability_id": "variance.total_by_dimension_bridge" }, { "question": "Which ordered root-cause path explains the total sales movement?", "why_not": "This asks for `root_cause_total_movement`, not `scenario_reconciliation`.", "better_capability_id": "variance.root_cause_total_bridge" }, { "question": "How much of the sales movement is due to price, units, and mix?", "why_not": "This asks for `pvm_decomposition_comparison`, not `scenario_reconciliation`.", "better_capability_id": "variance.price_volume_mix" }, { "question": "Which categories drove variance, and which brands explain the selected category moves?", "why_not": "This asks for `parent_bridge_with_child_drilldowns`, not `scenario_reconciliation`.", "better_capability_id": "variance.exploded_variance_bridge" } ], "ambiguous_questions": [ { "question": "Explain the sales variance.", "candidate_capability_ids": [ "variance.scenario_bridge", "period_comparison.horizontal_waterfall", "variance.total_by_dimension_bridge", "variance.root_cause_total_bridge", "variance.price_volume_mix" ], "disambiguation_needed": "Clarify whether the intended focus is `scenario_reconciliation`, `additive_reconciliation`, `total_delta_split_by_dimension`, `root_cause_total_movement`, `pvm_decomposition_comparison`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } }, "variance.total_by_dimension_bridge": { "family": "variance", "visual_grammar": "dimension_variance_bridge", "analysis_task_ids": [ "variance_and_bridge" ], "selection_tags": [ "variance_by_dimension" ], "selection_emphasis": "total_delta_split_by_dimension", "best_when": "Use when the question explicitly asks how the total delta is distributed across members of one named dimension, such as category, retailer, region, brand, or channel.", "avoid_when": "Avoid when the reader needs the generic total bridge, a nested parent/child drilldown, an ordered root-cause path across multiple dimensions, or price-volume-mix mechanics.", "axis_roles": { "x": "dimension_member", "y": "metric_delta" }, "period_semantics": { "role": "filter", "supports_period_axis": false, "supports_period_filter": true, "requires_period_column": true, "requires_comparison_pair": true, "minimum_distinct_values": 2, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ] }, "display_metric_roles": [ "baseline_metric", "current_metric", "delta_metric" ], "metric_requirements": { "source_metric_roles": [ { "role": "variance_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [ { "role": "baseline_metric", "produced_from": [ "variance_metric", "baseline_period_or_scenario" ], "derivation": "aggregate variance_metric over the baseline period or scenario" }, { "role": "current_metric", "produced_from": [ "variance_metric", "current_period_or_scenario" ], "derivation": "aggregate variance_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_metric", "current_metric" ], "derivation": "current_metric - baseline_metric" } ], "minimum_source_metric_count": 1, "metric_selection_notes": [ "Variance bridges require an additive source metric; baseline/current/delta are derived display roles." ] }, "dimension_roles": [ "dimension_member" ], "dimension_contract": null, "observation_requirements": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "competing_capability_ids": [ "variance.scenario_bridge", "variance.root_cause_total_bridge", "variance.exploded_variance_bridge", "variance.price_volume_mix", "variance.root_cause_component_bridge" ], "capability_id": "variance.total_by_dimension_bridge", "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "example_artifact_labels": [ "variance / total_by_dimension_bridge" ], "example_count": 1, "primary_decision_cue": "Question asks which members of one selected dimension account for total variance.", "requires_question_focus": [ "dimension_variance", "total_delta_split" ], "reject_decision_cues": [ "asks for root-cause ordering", "asks for child drilldowns", "asks for plain scenario bridge" ], "forbidden_question_focus": [ "root_cause_sequence", "fixed_parent_child_drilldown", "scenario_bridge" ], "period_scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." }, "render_contract": { "schema_version": "0.1", "chart_options": [], "variant_chart_options": [], "fixed_option_overrides": { "exploded_variance_bridge": false, "pvm_decomposition_ladder": false, "root_cause_bridge": false, "root_cause_component_bridge": false, "total_by_dimension_bridge": true, "waterfall_chart": false, "waterfall_small_multiples": false }, "expected_artifact_stems": [ "total_by_dimension_bridge" ], "expected_artifact_stem_templates": [], "allowed_support_artifact_stems": [], "renderer_managed_parameters": [ { "target": "source_file", "source": "request.input_file" }, { "target": "options.charts", "source": "chart_options", "condition": "chart_options is non-empty" }, { "target": "options.small_multiples", "source": "request.include_variants", "condition": "chart_options is non-empty" }, { "target": "options.*", "source": "fixed_option_overrides", "condition": "override is registered" } ], "caller_parameters": { "required": [ "capability_id", "input_file", "output_dir", "role_bindings" ], "optional": [ "recipe_path", "language", "currency", "artifact_mode", "include_variants", "options" ] }, "exact_artifact_proof_required": true, "boundary": "Mechanical rendering contract. Chart options and fixed overrides are selected by capability; role bindings remain dataset-specific." }, "selection_contract": { "selector_must_know": [ "analysis_task", "selection_emphasis", "available_source_metric_roles", "available_dimension_roles", "period_role_in_question" ], "dataset_requirements": { "period": { "role": "filter", "required": true, "comparison_pair_required": true, "minimum_distinct_values": 2, "requires_period_axis": false, "allows_period_filter": true, "scope_contract": { "role": "filter", "status": "scope_required_or_explicit_all_data", "period_column_required": true, "comparison_pair_required_for_render": true, "minimum_distinct_period_values": 2, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true, "unscoped_default": "all_available_records", "selector_warning": "A period-filter chart needs an explicit analysis period scope or an explicit all-data scope; a date column by itself can render every row in the dataset." } }, "metrics": { "minimum_source_metric_count": 1, "source_metric_roles": [ { "role": "variance_metric", "required": true, "accepted_metric_classes": [ "additive_value", "additive_volume", "additive_count" ], "aggregation": "sum_or_count" } ], "derived_metric_roles": [ { "role": "baseline_metric", "produced_from": [ "variance_metric", "baseline_period_or_scenario" ], "derivation": "aggregate variance_metric over the baseline period or scenario" }, { "role": "current_metric", "produced_from": [ "variance_metric", "current_period_or_scenario" ], "derivation": "aggregate variance_metric over the current period or scenario" }, { "role": "delta_metric", "produced_from": [ "baseline_metric", "current_metric" ], "derivation": "current_metric - baseline_metric" } ], "display_metric_roles": [ "baseline_metric", "current_metric", "delta_metric" ], "metric_selection_notes": [ "Variance bridges require an additive source metric; baseline/current/delta are derived display roles." ] }, "dimensions": { "minimum_count": 1, "required_roles": [ "dimension_member" ], "optional_roles": [], "role_requirements": { "dimension_member": { "resolution_type": "direct_dimension", "requires_profile_roles": [ "direct_dimension" ], "output_role": "dimension_member", "notes": "Resolved by choosing a concrete dataset dimension or identifier candidate.", "role": "dimension_member", "required": true } }, "dimension_contract": null }, "observations": { "minimum_non_null_rows": 1, "scope": "rendered_analysis_scope" }, "visual_role_bindings": { "x": "dimension_member", "y": "metric_delta" } }, "implementation_evidence": { "gallery_example_count": 1, "present_in_gallery_manifest": true, "present_in_generated_manifest": true, "evidence_status": "gallery_image_reviewed" }, "accept_when": "Use when the question explicitly asks how the total delta is distributed across members of one named dimension, such as category, retailer, region, brand, or channel.", "reject_when": "Avoid when the reader needs the generic total bridge, a nested parent/child drilldown, an ordered root-cause path across multiple dimensions, or price-volume-mix mechanics.", "tie_breakers": [ { "against": "variance.scenario_bridge", "choose_this_when": "Use when the question explicitly asks how the total delta is distributed across members of one named dimension, such as category, retailer, region, brand, or channel.", "choose_other_when": "Use for the plain bridge from one baseline total to one current total when the message is the additive reconciliation itself, not a ranked dimension split, root-cause path, or PVM mechanics.", "distinguishing_emphasis": { "this": "total_delta_split_by_dimension", "other": "scenario_reconciliation" } }, { "against": "variance.root_cause_total_bridge", "choose_this_when": "Use when the question explicitly asks how the total delta is distributed across members of one named dimension, such as category, retailer, region, brand, or channel.", "choose_other_when": "Use when the question asks for the ordered root-cause sequence behind the total movement across available dimensions, and the output should show which driver path explains the overall delta.", "distinguishing_emphasis": { "this": "total_delta_split_by_dimension", "other": "root_cause_total_movement" } }, { "against": "variance.exploded_variance_bridge", "choose_this_when": "Use when the question explicitly asks how the total delta is distributed across members of one named dimension, such as category, retailer, region, brand, or channel.", "choose_other_when": "Use when the question names one parent grouping dimension and one fixed second decomposition dimension to explain selected parent-row variance moves in the same visual.", "distinguishing_emphasis": { "this": "total_delta_split_by_dimension", "other": "parent_bridge_with_child_drilldowns" } }, { "against": "variance.price_volume_mix", "choose_this_when": "Use when the question explicitly asks how the total delta is distributed across members of one named dimension, such as category, retailer, region, brand, or channel.", "choose_other_when": "Use only when the business question explicitly asks how value movement decomposes into price, volume, and mix effects, and the dataset has compatible value, units/volume, and price or derived price semantics.", "distinguishing_emphasis": { "this": "total_delta_split_by_dimension", "other": "pvm_decomposition_comparison" } }, { "against": "variance.root_cause_component_bridge", "choose_this_when": "Use when the question explicitly asks how the total delta is distributed across members of one named dimension, such as category, retailer, region, brand, or channel.", "choose_other_when": "Use when the question asks which price, units, and mix component-by-dimension combinations explain movement, rather than which dimensions explain the total variance.", "distinguishing_emphasis": { "this": "total_delta_split_by_dimension", "other": "component_level_root_cause" } } ], "selection_boundary": "This contract constrains valid chart choices and required data roles; the selector still has to match the report question to the intended selection_emphasis rather than selecting by keywords alone.", "selection_decision": "Choose `variance.total_by_dimension_bridge` only when the task is one of ['variance_and_bridge'] and the required emphasis is `total_delta_split_by_dimension`; otherwise compare the tie_breakers rather than selecting by chart family name." }, "normalized_invocation_contract": { "schema_version": "0.1", "status": "parameter_contract_ready", "capability_id": "variance.total_by_dimension_bridge", "plugin_sources": [ "variance-analysis" ], "artifact_labels": [ "variance / total_by_dimension_bridge" ], "output_forms": [ "chart_png" ], "required_role_contracts": [ { "kind": "period", "role": "period_filter", "required": true, "status": "mapped", "mapping_kind": "runtime_contract", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.period_column", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.baseline_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "mappings.comparison_period", "recipe_path": null }, { "target_type": "recipe_path", "target": "options.period_type", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_grain", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.period_comparison_mode", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.fiscal_start_month", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "filters", "recipe_path": null, "scope_control": true }, { "target_type": "recipe_path", "target": "options.filters", "recipe_path": null, "scope_control": true } ], "depends_on_role": null, "issue": null, "artifact_label": null, "scope_binding": { "status": "supported", "period_column_required": true, "scope_required_for_render": true, "accepted_scope_controls": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "explicit_all_data_allowed": true } }, { "kind": "metric", "role": "variance_metric", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "mappings.amount_column", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null }, { "kind": "dimension", "role": "dimension_member", "required": true, "status": "mapped", "mapping_kind": "explicit", "caller_binding_required": true, "parameter_targets": [ { "target_type": "recipe_path", "target": "options.total_by_dimension_bridge_dimension", "recipe_path": null } ], "depends_on_role": null, "issue": null, "artifact_label": null } ], "optional_role_contracts": [], "variant_role_contracts": [], "artifact_invocation_contracts": [ { "artifact_label": "variance / total_by_dimension_bridge", "plugin_source": "variance-analysis", "output_form": "chart_png", "selector_level": "base_capability", "layout_variant": "single", "encoding_variant": "bridge", "variant_changes_capability_selection": false, "status": "parameter_contract_ready", "variant_role_contracts": [], "missing_variant_roles": [] } ], "missing_roles": [], "parameter_source_count": 1, "boundary": "Mechanical invocation contract only. It proves role-to-parameter evidence; it does not select semantically valid columns.", "clara_adapter": { "owner": "clara.reporting-engine", "adapter_id": "reporting-engine.variance", "legacy_plugin_source": "variance-analysis", "component_name": "variance-analysis", "legacy_plugin_source_policy": "provenance_only", "render_api_status": "unified_component_cli_adapter", "renderer": "scripts/render_capability.py:render_capability", "prepare_invocation": "scripts/reporting_adapters.py:prepare_invocation_plan", "prepare_render_recipe": "scripts/render_capability.py:build_render_recipe", "period_scope_contract": { "accepted_paths": [ "options.period_type", "options.period_grain", "options.period_comparison_mode", "options.fiscal_start_month", "filters", "options.filters" ], "verified_by": [ "plugins/variance-analysis/scripts/variance_core.py", "plugins/_shared/vendor/modules/chart_harness/recipe_filters.py" ] } } }, "selection_examples": { "positive_questions": [ "Which categories account for the total sales variance?" ], "negative_questions": [ { "question": "Reconcile total sales from baseline to current with a plain bridge.", "why_not": "This asks for `scenario_reconciliation`, not `total_delta_split_by_dimension`.", "better_capability_id": "variance.scenario_bridge" }, { "question": "Which ordered root-cause path explains the total sales movement?", "why_not": "This asks for `root_cause_total_movement`, not `total_delta_split_by_dimension`.", "better_capability_id": "variance.root_cause_total_bridge" }, { "question": "Which categories drove variance, and which brands explain the selected category moves?", "why_not": "This asks for `parent_bridge_with_child_drilldowns`, not `total_delta_split_by_dimension`.", "better_capability_id": "variance.exploded_variance_bridge" }, { "question": "How much of the sales movement is due to price, units, and mix?", "why_not": "This asks for `pvm_decomposition_comparison`, not `total_delta_split_by_dimension`.", "better_capability_id": "variance.price_volume_mix" }, { "question": "Which dimension combinations explain the price component of sales movement?", "why_not": "This asks for `component_level_root_cause`, not `total_delta_split_by_dimension`.", "better_capability_id": "variance.root_cause_component_bridge" } ], "ambiguous_questions": [ { "question": "Explain the sales variance.", "candidate_capability_ids": [ "variance.total_by_dimension_bridge", "variance.scenario_bridge", "variance.root_cause_total_bridge", "variance.exploded_variance_bridge", "variance.price_volume_mix" ], "disambiguation_needed": "Clarify whether the intended focus is `total_delta_split_by_dimension`, `scenario_reconciliation`, `root_cause_total_movement`, `parent_bridge_with_child_drilldowns`, `pvm_decomposition_comparison`." } ], "example_source": "positive questions are authored from reviewed proof/review cases; negative and ambiguous examples are derived from explicit competitor and task-sibling links." } } }, "artifacts": [ { "label": "variance / waterfall", "capability_id": "variance.scenario_bridge", "plugin_source": "variance-analysis", "artifact_type": "png", "source": "../variance/variance/waterfall.png", "output": "variance__waterfall.png", "sidecars": [ { "label": "source", "href": "../variance/variance/waterfall.png" }, { "label": "context", "href": "../variance/variance/waterfall_context.json" }, { "label": "data", "href": "../variance/variance/waterfall_chart_data.json" }, { "label": "manifest", "href": "../variance/variance/manifest.json" }, { "label": "recipe", "href": "../variance/variance/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales variance | LC", "_Aug-2017 vs _Aug-2016, year to date" ], "who": "Mexico hair color", "what": "Sales variance | LC", "when": "_Aug-2017 vs _Aug-2016, year to date", "source": "../variance/variance/waterfall_context.json" }, "context_summary": { "capability": null, "grammar": null, "metrics": "Value_LC", "dimensions": "Company, Brand, Channel +1", "periods": null, "trace_widths": null, "source_reference": null }, "original_artifact_contract": { "capability_id": "variance.scenario_bridge", "status": "context_only", "when_to_use": "standard_variance_waterfall", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "png", "formats": [ "png" ] } ] }, "rendering_variant": { "output_form": "chart_png", "layout_variant": "single", "encoding_variant": "bridge", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "variance / waterfall_small_multiples", "capability_id": "variance.scenario_bridge", "plugin_source": "variance-analysis", "artifact_type": "png", "source": "../variance/variance/waterfall_small_multiples.png", "output": "variance__waterfall_small_multiples.png", "sidecars": [ { "label": "source", "href": "../variance/variance/waterfall_small_multiples.png" }, { "label": "context", "href": "../variance/variance/waterfall_small_multiples_context.json" }, { "label": "data", "href": "../variance/variance/waterfall_small_multiples_summary.csv" }, { "label": "manifest", "href": "../variance/variance/manifest.json" }, { "label": "recipe", "href": "../variance/variance/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales variance by Company | LC", "_Aug-2017 vs _Aug-2016, year to date" ], "who": "Mexico hair color", "what": "Sales variance by Company | LC", "when": "_Aug-2017 vs _Aug-2016, year to date", "source": "../variance/variance/waterfall_small_multiples_context.json" }, "context_summary": { "capability": null, "grammar": null, "metrics": null, "dimensions": null, "periods": null, "trace_widths": null, "source_reference": null }, "original_artifact_contract": { "capability_id": "variance.scenario_bridge", "status": "context_only", "when_to_use": "standard_variance_small_multiples", "required_parameters": [ "dimension" ], "optional_parameters": [], "outputs": [ { "artifact_type": "png", "formats": [ "png" ] } ] }, "rendering_variant": { "output_form": "chart_png", "layout_variant": "small_multiples", "encoding_variant": "bridge", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "variance / pvm_decomposition_ladder", "capability_id": "variance.price_volume_mix", "plugin_source": "variance-analysis", "artifact_type": "png", "source": "../variance/variance/pvm_decomposition_ladder.png", "output": "variance__pvm_decomposition_ladder.png", "sidecars": [ { "label": "source", "href": "../variance/variance/pvm_decomposition_ladder.png" }, { "label": "context", "href": "../variance/variance/pvm_decomposition_ladder_context.json" }, { "label": "data", "href": "../variance/variance/pvm_decomposition_ladder.csv" }, { "label": "manifest", "href": "../variance/variance/manifest.json" }, { "label": "recipe", "href": "../variance/variance/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales variance: price, units, mix | LC", "_Aug-2017 vs _Aug-2016, year to date" ], "who": "Mexico hair color", "what": "Sales variance: price, units, mix | LC", "when": "_Aug-2017 vs _Aug-2016, year to date", "source": "../variance/variance/pvm_decomposition_ladder_context.json" }, "context_summary": { "capability": null, "grammar": null, "metrics": "Value_LC", "dimensions": null, "periods": null, "trace_widths": null, "source_reference": null }, "original_artifact_contract": { "capability_id": "variance.price_volume_mix", "status": "context_only", "when_to_use": "Compare the same total variance under progressively richer Price / Units / Mix decompositions before deciding which breakdown is useful for the client story.", "required_parameters": [ "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "png", "formats": [ "png" ] } ] }, "rendering_variant": { "output_form": "chart_png", "layout_variant": "single", "encoding_variant": "pvm_ladder", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "variance / total_by_dimension_bridge", "capability_id": "variance.total_by_dimension_bridge", "plugin_source": "variance-analysis", "artifact_type": "png", "source": "../variance/variance/total_by_dimension_bridge.png", "output": "variance__total_by_dimension_bridge.png", "sidecars": [ { "label": "source", "href": "../variance/variance/total_by_dimension_bridge.png" }, { "label": "context", "href": "../variance/variance/total_by_dimension_bridge_context.json" }, { "label": "data", "href": "../variance/variance/total_by_dimension_bridge.csv" }, { "label": "manifest", "href": "../variance/variance/manifest.json" }, { "label": "recipe", "href": "../variance/variance/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Total By Dimension Bridge for Value LC", "Aug 2017 vs Aug 2016, through 2017 08 27" ], "who": "Mexico hair color", "what": "Total By Dimension Bridge for Value LC", "when": "Aug 2017 vs Aug 2016, through 2017 08 27", "source": "../variance/variance/total_by_dimension_bridge_context.json" }, "context_summary": { "capability": null, "grammar": null, "metrics": "Value_LC", "dimensions": "Company", "periods": "_Aug-2016, _Aug-2017", "trace_widths": null, "source_reference": null }, "original_artifact_contract": { "capability_id": "variance.total_by_dimension_bridge", "status": "context_only", "when_to_use": "Show how the total metric movement is split across one fixed dimension, one row per dimension member.", "required_parameters": [ "metric", "dimension", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "png", "formats": [ "png" ] } ] }, "rendering_variant": { "output_form": "chart_png", "layout_variant": "single", "encoding_variant": "bridge", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "variance / root_cause_total_bridge", "capability_id": "variance.root_cause_total_bridge", "plugin_source": "variance-analysis", "artifact_type": "png", "source": "../variance/variance/root_cause_total_bridge.png", "output": "variance__root_cause_total_bridge.png", "sidecars": [ { "label": "source", "href": "../variance/variance/root_cause_total_bridge.png" }, { "label": "context", "href": "../variance/variance/root_cause_total_bridge_context.json" }, { "label": "data", "href": "../variance/variance/root_cause_total_bridge.csv" }, { "label": "manifest", "href": "../variance/variance/manifest.json" }, { "label": "recipe", "href": "../variance/variance/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales variable-dimension root-cause total variance | LC", "_Aug-2017 vs _Aug-2016, year to date" ], "who": "Mexico hair color", "what": "Sales variable-dimension root-cause total variance | LC", "when": "_Aug-2017 vs _Aug-2016, year to date", "source": "../variance/variance/root_cause_total_bridge_context.json" }, "context_summary": { "capability": null, "grammar": null, "metrics": "Value_LC", "dimensions": null, "periods": null, "trace_widths": null, "source_reference": null }, "original_artifact_contract": { "capability_id": "variance.root_cause_total_bridge", "status": "context_only", "when_to_use": "root_cause_total_bridge", "required_parameters": [ "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "png", "formats": [ "png" ] } ] }, "rendering_variant": { "output_form": "chart_png", "layout_variant": "single", "encoding_variant": "bridge", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "variance / root_cause_component_bridge", "capability_id": "variance.root_cause_component_bridge", "plugin_source": "variance-analysis", "artifact_type": "png", "source": "../variance/variance/root_cause_component_bridge.png", "output": "variance__root_cause_component_bridge.png", "sidecars": [ { "label": "source", "href": "../variance/variance/root_cause_component_bridge.png" }, { "label": "context", "href": "../variance/variance/root_cause_component_bridge_context.json" }, { "label": "data", "href": "../variance/variance/root_cause_component_bridge.csv" }, { "label": "manifest", "href": "../variance/variance/manifest.json" }, { "label": "recipe", "href": "../variance/variance/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Root Cause Component Bridge for Value LC", "Aug 2017 vs Aug 2016, through 2017 08 27" ], "who": "Mexico hair color", "what": "Root Cause Component Bridge for Value LC", "when": "Aug 2017 vs Aug 2016, through 2017 08 27", "source": "../variance/variance/root_cause_component_bridge_context.json" }, "context_summary": { "capability": null, "grammar": null, "metrics": "Value_LC", "dimensions": null, "periods": null, "trace_widths": null, "source_reference": null }, "original_artifact_contract": { "capability_id": "variance.root_cause_component_bridge", "status": "context_only", "when_to_use": "root_cause_component_bridge", "required_parameters": [ "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "png", "formats": [ "png" ] } ] }, "rendering_variant": { "output_form": "chart_png", "layout_variant": "single", "encoding_variant": "bridge", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "variance / exploded_variance_bridge", "capability_id": "variance.exploded_variance_bridge", "plugin_source": "variance-analysis", "artifact_type": "png", "source": "../variance/variance/exploded_variance_bridge.png", "output": "variance__exploded_variance_bridge.png", "sidecars": [ { "label": "source", "href": "../variance/variance/exploded_variance_bridge.png" }, { "label": "context", "href": "../variance/variance/exploded_variance_bridge_context.json" }, { "label": "data", "href": "../variance/variance/exploded_variance_bridge_chart_data.json" }, { "label": "manifest", "href": "../variance/variance/manifest.json" }, { "label": "recipe", "href": "../variance/variance/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Exploded Variance Bridge for Value LC", "Aug 2017 vs Aug 2016, through 2017 08 27" ], "who": "Mexico hair color", "what": "Exploded Variance Bridge for Value LC", "when": "Aug 2017 vs Aug 2016, through 2017 08 27", "source": "../variance/variance/exploded_variance_bridge_context.json" }, "context_summary": { "capability": null, "grammar": null, "metrics": "Value_LC", "dimensions": null, "periods": null, "trace_widths": null, "source_reference": null }, "original_artifact_contract": { "native_payload": "exploded_variance_bridge_spec.json", "chart_data": "exploded_variance_bridge_chart_data.json", "capability_id": "variance.exploded_variance_bridge", "status": "context_only", "when_to_use": "Show one fixed parent-dimension total-variance bridge and up to two fixed child/decomposition-dimension drilldowns for selected parent rows.", "required_parameters": [ "metric", "parent_dimension", "child_dimension" ], "optional_parameters": [], "editable_slide_target": "pptx", "can_insert_in_ppt": true, "requires_image_interpretation": false, "one_page": true, "max_drilldowns": 2, "ppt_composition": { "insert_mode": "single_slide", "fallback_render": "exploded_variance_bridge.png", "recommended_slide_aspect_ratio": "16:9" }, "outputs": [ { "artifact_type": "png", "formats": [ "png" ] } ] }, "rendering_variant": { "output_form": "chart_png", "layout_variant": "nested_drilldown", "encoding_variant": "bridge", "selector_level": "capability_choice", "variant_changes_capability_selection": true, "adds_parameter_roles": [ "drilldown_selection" ], "variant_selection_cues": [ "question asks for selected-row drilldown or nested detail" ] } }, { "label": "variance / root_cause_exploded_bridge", "capability_id": "variance.root_cause_exploded_bridge", "plugin_source": "variance-analysis", "artifact_type": "png", "source": "../variance/variance/root_cause_exploded_bridge.png", "output": "variance__root_cause_exploded_bridge.png", "sidecars": [ { "label": "source", "href": "../variance/variance/root_cause_exploded_bridge.png" }, { "label": "context", "href": "../variance/variance/root_cause_exploded_bridge_context.json" }, { "label": "data", "href": "../variance/variance/root_cause_exploded_bridge_chart_data.json" }, { "label": "manifest", "href": "../variance/variance/manifest.json" }, { "label": "recipe", "href": "../variance/variance/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Root-cause exploded bridge for Value LC", "_Aug-2017 vs _Aug-2016, year to date" ], "who": "Mexico hair color", "what": "Root-cause exploded bridge for Value LC", "when": "_Aug-2017 vs _Aug-2016, year to date", "source": "../variance/variance/root_cause_exploded_bridge_context.json" }, "context_summary": { "capability": null, "grammar": null, "metrics": "Value_LC", "dimensions": null, "periods": null, "trace_widths": null, "source_reference": null }, "original_artifact_contract": { "capability_id": "variance.root_cause_exploded_bridge", "status": "context_only", "when_to_use": "Show a variable mixed-dimension root-cause bridge with a nested root-cause drilldown for a selected driver row.", "required_parameters": [ "metric", "root_cause_parent_artifact", "parent_row_number" ], "optional_parameters": [], "outputs": [ { "artifact_type": "png", "formats": [ "png" ] } ] }, "rendering_variant": { "output_form": "chart_png", "layout_variant": "nested_drilldown", "encoding_variant": "bridge", "selector_level": "capability_choice", "variant_changes_capability_selection": true, "adds_parameter_roles": [ "drilldown_selection" ], "variant_selection_cues": [ "question asks for selected-row drilldown or nested detail" ] } }, { "label": "period / comparison_table", "capability_id": "period_comparison.comparison_table", "plugin_source": "period-comparison", "artifact_type": "table", "source": "../period/period/comparison_table.html", "output": "period__comparison_table.png", "sidecars": [ { "label": "source", "href": "../period/period/comparison_table.html" }, { "label": "context", "href": "../period/period/comparison_table_chart_context.json" }, { "label": "data", "href": "../period/period/comparison_table_chart_data.csv" }, { "label": "manifest", "href": "../period/period/source_pack/manifest.json" }, { "label": "recipe", "href": "../period/period/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in m", "AC vs PY" ], "who": "Mexico hair color", "what": "Sales in m", "when": "AC vs PY", "source": "../period/period/comparison_table_chart_context.json" }, "context_summary": { "capability": "period_comparison.comparison_table", "grammar": "period_comparison.comparison_table", "metrics": "Sales", "dimensions": "Company, Brand, Channel +3", "periods": "PY, AC", "trace_widths": null, "source_reference": "comparison_table" }, "original_artifact_contract": { "capability_id": "period_comparison.comparison_table", "status": "context_only", "when_to_use": "period_comparison.comparison_table", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "table_html", "layout_variant": "table", "encoding_variant": "table", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "table output for exact values or evidence rows", "default single-view rendering for the selected capability" ] } }, { "label": "period / time_series_table", "capability_id": "period_comparison.time_series_table", "plugin_source": "period-comparison", "artifact_type": "table", "source": "../period/period/time_series_table.html", "output": "period__time_series_table.png", "sidecars": [ { "label": "source", "href": "../period/period/time_series_table.html" }, { "label": "context", "href": "../period/period/time_series_table_chart_context.json" }, { "label": "data", "href": "../period/period/time_series_table_chart_data.csv" }, { "label": "manifest", "href": "../period/period/source_pack/manifest.json" }, { "label": "recipe", "href": "../period/period/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in m", "AC vs PY" ], "who": "Mexico hair color", "what": "Sales in m", "when": "AC vs PY", "source": "../period/period/time_series_table_chart_context.json" }, "context_summary": { "capability": "period_comparison.time_series_table", "grammar": "period_comparison.time_series_table", "metrics": "Sales", "dimensions": "Company, Brand, Channel +3", "periods": "PY, AC", "trace_widths": null, "source_reference": "time_series_table" }, "original_artifact_contract": { "capability_id": "period_comparison.time_series_table", "status": "context_only", "when_to_use": "period_comparison.time_series_table", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "table_html", "layout_variant": "table", "encoding_variant": "table", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "table output for exact values or evidence rows", "default single-view rendering for the selected capability" ] } }, { "label": "period / year_over_year_by_recency_window", "capability_id": "period_comparison.by_period", "plugin_source": "period-comparison", "artifact_type": "html", "source": "../period/period/year_over_year_by_period.html", "output": "period__year_over_year_by_period.png", "sidecars": [ { "label": "source", "href": "../period/period/year_over_year_by_period.html" }, { "label": "context", "href": "../period/period/source_pack/contexts/period_comparison_context.json" }, { "label": "data", "href": "../period/period/period_comparison_by_period.csv" }, { "label": "manifest", "href": "../period/period/source_pack/manifest.json" }, { "label": "recipe", "href": "../period/period/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Weekly Average Sales by Recency Window in m", "AC vs PY, through 2017-08-27" ], "who": "Mexico hair color", "what": "Weekly Average Sales by Recency Window in m", "when": "AC vs PY, through 2017-08-27", "source": "../period/period/year_over_year_by_period.html" }, "context_summary": { "capability": "period_comparison.by_period", "grammar": "period_comparison.by_period", "metrics": "Value_LC", "dimensions": "Company, Brand, Channel +3", "periods": "PY, AC", "trace_widths": null, "source_reference": "year_over_year_by_period" }, "original_artifact_contract": { "capability_id": "period_comparison.by_period", "status": "context_only", "when_to_use": "period_comparison", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "period_gap", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "period / year_over_year_by_recency_window_small_multiples", "capability_id": "period_comparison.by_period", "plugin_source": "period-comparison", "artifact_type": "html", "source": "../period/period/year_over_year_by_period_small_multiples.html", "output": "period__year_over_year_by_period_small_multiples.png", "sidecars": [ { "label": "source", "href": "../period/period/year_over_year_by_period_small_multiples.html" }, { "label": "context", "href": "../period/period/source_pack/contexts/period_comparison_context.json" }, { "label": "data", "href": "../period/period/period_comparison_by_period.csv" }, { "label": "manifest", "href": "../period/period/source_pack/manifest.json" }, { "label": "recipe", "href": "../period/period/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Weekly Average Sales by Recency Window in m by Type", "AC vs PY, through 2017-08-27" ], "who": "Mexico hair color", "what": "Weekly Average Sales by Recency Window in m by Type", "when": "AC vs PY, through 2017-08-27", "source": "../period/period/year_over_year_by_period_small_multiples.html" }, "context_summary": { "capability": "period_comparison.by_period", "grammar": "period_comparison.by_period", "metrics": "Value_LC", "dimensions": "Company, Brand, Channel +3", "periods": "PY, AC", "trace_widths": null, "source_reference": "year_over_year_by_period..." }, "original_artifact_contract": { "capability_id": "period_comparison.by_period", "status": "context_only", "when_to_use": "period_comparison", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "period_gap", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "period / year_over_year_column", "capability_id": "period_comparison.multitier_column", "plugin_source": "period-comparison", "artifact_type": "html", "source": "../period/period/year_over_year_column.html", "output": "period__year_over_year_column.png", "sidecars": [ { "label": "source", "href": "../period/period/year_over_year_column.html" }, { "label": "context", "href": "../period/period/source_pack/contexts/period_comparison_context.json" }, { "label": "data", "href": "../period/period/period_comparison_by_period.csv" }, { "label": "manifest", "href": "../period/period/source_pack/manifest.json" }, { "label": "recipe", "href": "../period/period/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in m", "AC vs PY, through 2017-08-27" ], "who": "Mexico hair color", "what": "Sales in m", "when": "AC vs PY, through 2017-08-27", "source": "../period/period/year_over_year_column.html" }, "context_summary": { "capability": "period_comparison.multitier_column", "grammar": "period_comparison.multitier_column", "metrics": "Value_LC", "dimensions": "Company, Brand, Channel +3", "periods": "PY, AC", "trace_widths": "0.048, 0.68", "source_reference": "year_over_year_column" }, "original_artifact_contract": { "capability_id": "period_comparison.multitier_column", "status": "context_only", "when_to_use": "period_comparison", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "column", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "period / year_over_year_column_small_multiples", "capability_id": "period_comparison.multitier_column", "plugin_source": "period-comparison", "artifact_type": "html", "source": "../period/period/year_over_year_column_small_multiples.html", "output": "period__year_over_year_column_small_multiples.png", "sidecars": [ { "label": "source", "href": "../period/period/year_over_year_column_small_multiples.html" }, { "label": "context", "href": "../period/period/source_pack/contexts/period_comparison_context.json" }, { "label": "data", "href": "../period/period/period_comparison_by_period.csv" }, { "label": "manifest", "href": "../period/period/source_pack/manifest.json" }, { "label": "recipe", "href": "../period/period/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in m by Type", "AC vs PY, through 2017-08-27" ], "who": "Mexico hair color", "what": "Sales in m by Type", "when": "AC vs PY, through 2017-08-27", "source": "../period/period/year_over_year_column_small_multiples.html" }, "context_summary": { "capability": "period_comparison.multitier_column", "grammar": "period_comparison.multitier_column", "metrics": "Value_LC", "dimensions": "Company, Brand, Channel +3", "periods": "PY, AC", "trace_widths": "0.68", "source_reference": "year_over_year_column_sm..." }, "original_artifact_contract": { "capability_id": "period_comparison.multitier_column", "status": "context_only", "when_to_use": "period_comparison", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "column", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "period / year_over_year_line", "capability_id": "period_comparison.trend", "plugin_source": "period-comparison", "artifact_type": "html", "source": "../period/period/year_over_year_line.html", "output": "period__year_over_year_line.png", "sidecars": [ { "label": "source", "href": "../period/period/year_over_year_line.html" }, { "label": "context", "href": "../period/period/source_pack/contexts/period_comparison_context.json" }, { "label": "data", "href": "../period/period/period_comparison_by_period.csv" }, { "label": "manifest", "href": "../period/period/source_pack/manifest.json" }, { "label": "recipe", "href": "../period/period/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in m", "AC vs PY, through 2017-08-27" ], "who": "Mexico hair color", "what": "Sales in m", "when": "AC vs PY, through 2017-08-27", "source": "../period/period/year_over_year_line.html" }, "context_summary": { "capability": "period_comparison.trend", "grammar": "period_comparison.trend", "metrics": "Value_LC", "dimensions": "Company, Brand, Channel +3", "periods": "PY, AC", "trace_widths": null, "source_reference": "year_over_year_line" }, "original_artifact_contract": { "capability_id": "period_comparison.trend", "status": "context_only", "when_to_use": "period_comparison", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "line", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "period / year_over_year_small_multiples", "capability_id": "period_comparison.trend", "plugin_source": "period-comparison", "artifact_type": "html", "source": "../period/period/year_over_year_small_multiples.html", "output": "period__year_over_year_small_multiples.png", "sidecars": [ { "label": "source", "href": "../period/period/year_over_year_small_multiples.html" }, { "label": "context", "href": "../period/period/year_over_year_small_multiples_context.json" }, { "label": "data", "href": "../period/period/year_over_year_small_multiples_summary.csv" }, { "label": "manifest", "href": "../period/period/source_pack/manifest.json" }, { "label": "recipe", "href": "../period/period/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in m by Type", "AC vs PY, through 2017-08-27" ], "who": "Mexico hair color", "what": "Sales in m by Type", "when": "AC vs PY, through 2017-08-27", "source": "../period/period/year_over_year_small_multiples.html" }, "context_summary": { "capability": "period_comparison.by_period", "grammar": "period_comparison.by_period", "metrics": "Value_LC", "dimensions": "Company, Brand, Channel +3", "periods": "PY, AC", "trace_widths": null, "source_reference": "year_over_year_small_mul..." }, "original_artifact_contract": { "capability_id": "period_comparison.by_period", "status": "context_only", "when_to_use": "period_comparison_small_multiples", "required_parameters": [ "dimension" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "source_capability_id": "period_comparison.by_period", "capability_override_reason": "Visual inspection: this artifact is the line small-multiple variant and should inherit the line trend capability.", "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "line", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "period / year_over_year_waterfall", "capability_id": "period_comparison.horizontal_waterfall", "plugin_source": "period-comparison", "artifact_type": "html", "source": "../period/period/year_over_year_waterfall.html", "output": "period__year_over_year_waterfall.png", "sidecars": [ { "label": "source", "href": "../period/period/year_over_year_waterfall.html" }, { "label": "context", "href": "../period/period/source_pack/contexts/period_comparison_context.json" }, { "label": "data", "href": "../period/period/period_comparison_by_period.csv" }, { "label": "manifest", "href": "../period/period/source_pack/manifest.json" }, { "label": "recipe", "href": "../period/period/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in m", "AC vs PY, through 2017-08-27" ], "who": "Mexico hair color", "what": "Sales in m", "when": "AC vs PY, through 2017-08-27", "source": "../period/period/year_over_year_waterfall.html" }, "context_summary": { "capability": "period_comparison.horizontal_waterfall", "grammar": "period_comparison.horizontal_waterfall", "metrics": "Value_LC", "dimensions": "Company, Brand, Channel +3", "periods": "PY, AC", "trace_widths": "0.048, 0.68", "source_reference": "year_over_year_waterfall" }, "original_artifact_contract": { "capability_id": "period_comparison.horizontal_waterfall", "status": "context_only", "when_to_use": "period_comparison", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "bridge", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "period / year_over_year_waterfall_small_multiples", "capability_id": "period_comparison.horizontal_waterfall", "plugin_source": "period-comparison", "artifact_type": "html", "source": "../period/period/year_over_year_waterfall_small_multiples.html", "output": "period__year_over_year_waterfall_small_multiples.png", "sidecars": [ { "label": "source", "href": "../period/period/year_over_year_waterfall_small_multiples.html" }, { "label": "context", "href": "../period/period/source_pack/contexts/period_comparison_context.json" }, { "label": "data", "href": "../period/period/period_comparison_by_period.csv" }, { "label": "manifest", "href": "../period/period/source_pack/manifest.json" }, { "label": "recipe", "href": "../period/period/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in m by Type", "AC vs PY, through 2017-08-27" ], "who": "Mexico hair color", "what": "Sales in m by Type", "when": "AC vs PY, through 2017-08-27", "source": "../period/period/year_over_year_waterfall_small_multiples.html" }, "context_summary": { "capability": "period_comparison.horizontal_waterfall", "grammar": "period_comparison.horizontal_waterfall", "metrics": "Value_LC", "dimensions": "Company, Brand, Channel +3", "periods": "PY, AC", "trace_widths": "0.68", "source_reference": "year_over_year_waterfall..." }, "original_artifact_contract": { "capability_id": "period_comparison.horizontal_waterfall", "status": "context_only", "when_to_use": "period_comparison", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "bridge", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "period / year_over_year_dot", "capability_id": "period_comparison.dot", "plugin_source": "period-comparison", "artifact_type": "html", "source": "../period/period/year_over_year_dot.html", "output": "period__year_over_year_dot.png", "sidecars": [ { "label": "source", "href": "../period/period/year_over_year_dot.html" }, { "label": "context", "href": "../period/period/source_pack/contexts/period_comparison_context.json" }, { "label": "data", "href": "../period/period/period_comparison_by_period.csv" }, { "label": "manifest", "href": "../period/period/source_pack/manifest.json" }, { "label": "recipe", "href": "../period/period/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in m by Company", "AC vs PY, through 2017-08-27" ], "who": "Mexico hair color", "what": "Sales in m by Company", "when": "AC vs PY, through 2017-08-27", "source": "../period/period/year_over_year_dot.html" }, "context_summary": { "capability": "period_comparison.dot", "grammar": "period_comparison.dot", "metrics": "Value_LC", "dimensions": "Company, Brand, Channel +3", "periods": "PY, AC", "trace_widths": null, "source_reference": "year_over_year_dot" }, "original_artifact_contract": { "capability_id": "period_comparison.dot", "status": "context_only", "when_to_use": "period_comparison", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "dot", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "period / year_over_year_dot_small_multiples", "capability_id": "period_comparison.dot", "plugin_source": "period-comparison", "artifact_type": "html", "source": "../period/period/year_over_year_dot_small_multiples.html", "output": "period__year_over_year_dot_small_multiples.png", "sidecars": [ { "label": "source", "href": "../period/period/year_over_year_dot_small_multiples.html" }, { "label": "context", "href": "../period/period/source_pack/contexts/period_comparison_context.json" }, { "label": "data", "href": "../period/period/period_comparison_by_period.csv" }, { "label": "manifest", "href": "../period/period/source_pack/manifest.json" }, { "label": "recipe", "href": "../period/period/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in m by Company and Type", "AC vs PY, through 2017-08-27" ], "who": "Mexico hair color", "what": "Sales in m by Company and Type", "when": "AC vs PY, through 2017-08-27", "source": "../period/period/year_over_year_dot_small_multiples.html" }, "context_summary": { "capability": "period_comparison.dot", "grammar": "period_comparison.dot", "metrics": "Value_LC", "dimensions": "Company, Brand, Channel +3", "periods": "PY, AC", "trace_widths": null, "source_reference": "year_over_year_dot_small..." }, "original_artifact_contract": { "capability_id": "period_comparison.dot", "status": "context_only", "when_to_use": "period_comparison", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "dot", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "period / year_over_year_slope", "capability_id": "period_comparison.slope", "plugin_source": "period-comparison", "artifact_type": "html", "source": "../period/period/year_over_year_slope.html", "output": "period__year_over_year_slope.png", "sidecars": [ { "label": "source", "href": "../period/period/year_over_year_slope.html" }, { "label": "context", "href": "../period/period/source_pack/contexts/period_comparison_context.json" }, { "label": "data", "href": "../period/period/period_comparison_by_period.csv" }, { "label": "manifest", "href": "../period/period/source_pack/manifest.json" }, { "label": "recipe", "href": "../period/period/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in m by Channel", "AC vs PY, through 2017-08-27" ], "who": "Mexico hair color", "what": "Sales in m by Channel", "when": "AC vs PY, through 2017-08-27", "source": "../period/period/year_over_year_slope.html" }, "context_summary": { "capability": "period_comparison.slope", "grammar": "period_comparison.slope", "metrics": "Value_LC", "dimensions": "Company, Brand, Channel +3", "periods": "PY, AC", "trace_widths": null, "source_reference": "year_over_year_slope" }, "original_artifact_contract": { "capability_id": "period_comparison.slope", "status": "context_only", "when_to_use": "period_comparison", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "slope", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "period / year_over_year_slope_small_multiples", "capability_id": "period_comparison.slope", "plugin_source": "period-comparison", "artifact_type": "html", "source": "../period/period/year_over_year_slope_small_multiples.html", "output": "period__year_over_year_slope_small_multiples.png", "sidecars": [ { "label": "source", "href": "../period/period/year_over_year_slope_small_multiples.html" }, { "label": "context", "href": "../period/period/source_pack/contexts/period_comparison_context.json" }, { "label": "data", "href": "../period/period/period_comparison_by_period.csv" }, { "label": "manifest", "href": "../period/period/source_pack/manifest.json" }, { "label": "recipe", "href": "../period/period/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in m by Type", "AC vs PY, through 2017-08-27" ], "who": "Mexico hair color", "what": "Sales in m by Type", "when": "AC vs PY, through 2017-08-27", "source": "../period/period/year_over_year_slope_small_multiples.html" }, "context_summary": { "capability": "period_comparison.slope", "grammar": "period_comparison.slope", "metrics": "Value_LC", "dimensions": "Company, Brand, Channel +3", "periods": "PY, AC", "trace_widths": null, "source_reference": "year_over_year_slope_sma..." }, "original_artifact_contract": { "capability_id": "period_comparison.slope", "status": "context_only", "when_to_use": "period_comparison", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "slope", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "mix_comparison / bar", "capability_id": "mix.bar", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_comparison/bar.html", "output": "mix_comparison__bar.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_comparison/bar.html" }, { "label": "context", "href": "../mix_comparison/mix_comparison/bar_chart_context.json" }, { "label": "data", "href": "../mix_comparison/mix_comparison/bar_chart_data.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_comparison/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_comparison/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Bar for Sales", "infer current or all" ], "who": "Mexico hair color", "what": "Bar for Sales", "when": "infer current or all", "source": "../mix_comparison/mix_comparison/bar_chart_context.json" }, "context_summary": { "capability": "mix.bar", "grammar": "bar", "metrics": "Sales", "dimensions": "Brand", "periods": "_Aug-2016, _Aug-2017", "trace_widths": "0.9", "source_reference": "bar" }, "original_artifact_contract": { "capability_id": "mix.bar", "status": "context_only", "when_to_use": "mix.bar", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "bar", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_current / stacked_bar", "capability_id": "mix.stacked_bar", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_current/mix_regular/stacked_bar.html", "output": "mix_current__mix_regular__stacked_bar.png", "sidecars": [ { "label": "source", "href": "../mix_current/mix_regular/stacked_bar.html" }, { "label": "context", "href": "../mix_current/mix_regular/stacked_bar_chart_context.json" }, { "label": "data", "href": "../mix_current/mix_regular/stacked_bar_chart_data.csv" }, { "label": "manifest", "href": "../mix_current/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_current/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in mEUR by Company and Channel", "AC" ], "who": "Mexico hair color", "what": "Sales in mEUR by Company and Channel", "when": "AC", "source": "../mix_current/mix_regular/stacked_bar_chart_context.json" }, "context_summary": { "capability": "mix.stacked_bar", "grammar": "stacked bar", "metrics": "Sales", "dimensions": "Company, Channel", "periods": "AC", "trace_widths": "0.9", "source_reference": "stacked_bar" }, "original_artifact_contract": { "capability_id": "mix.stacked_bar", "status": "context_only", "when_to_use": "mix.stacked_bar", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "stacked", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_comparison / bar_small_multiples", "capability_id": "mix.bar", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_comparison/bar_small_multiples.html", "output": "mix_comparison__bar_small_multiples.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_comparison/bar_small_multiples.html" }, { "label": "context", "href": "../mix_comparison/mix_comparison/bar_small_multiples_chart_context.json" }, { "label": "data", "href": "../mix_comparison/mix_comparison/bar_small_multiples_chart_data.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_comparison/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_comparison/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Bar Small Multiples for Sales", "infer current or all" ], "who": "Mexico hair color", "what": "Bar Small Multiples for Sales", "when": "infer current or all", "source": "../mix_comparison/mix_comparison/bar_small_multiples_chart_context.json" }, "context_summary": { "capability": "mix.bar", "grammar": "bar", "metrics": "Sales", "dimensions": "Brand, Channel", "periods": "_Aug-2016, _Aug-2017", "trace_widths": "0.9", "source_reference": "bar_small_multiples" }, "original_artifact_contract": { "capability_id": "mix.bar", "status": "context_only", "when_to_use": "mix.bar", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "bar", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "mix_current / stacked_bar_small_multiples", "capability_id": "mix.stacked_bar", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_current/mix_regular/stacked_bar_small_multiples.html", "output": "mix_current__mix_regular__stacked_bar_small_multiples.png", "sidecars": [ { "label": "source", "href": "../mix_current/mix_regular/stacked_bar_small_multiples.html" }, { "label": "context", "href": "../mix_current/mix_regular/stacked_bar_small_multiples_chart_context.json" }, { "label": "data", "href": "../mix_current/mix_regular/stacked_bar_small_multiples_chart_data.csv" }, { "label": "manifest", "href": "../mix_current/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_current/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in mEUR by Company, Channel and Type", "AC" ], "who": "Mexico hair color", "what": "Sales in mEUR by Company, Channel and Type", "when": "AC", "source": "../mix_current/mix_regular/stacked_bar_small_multiples_chart_context.json" }, "context_summary": { "capability": "mix.stacked_bar", "grammar": "stacked bar", "metrics": "Sales", "dimensions": "Company, Channel, Type", "periods": "AC", "trace_widths": "0.9", "source_reference": "stacked_bar_small_multip..." }, "original_artifact_contract": { "capability_id": "mix.stacked_bar", "status": "context_only", "when_to_use": "mix.stacked_bar", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "stacked", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "mix_comparison / related_metrics_bar", "capability_id": "mix.stacked_bar_overlay", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_comparison/related_metrics_bar.html", "output": "mix_comparison__related_metrics_bar.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_comparison/related_metrics_bar.html" }, { "label": "context", "href": "../mix_comparison/mix_comparison/related_metrics_bar_chart_context.json" }, { "label": "data", "href": "../mix_comparison/mix_comparison/related_metrics_bar_chart_data.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_comparison/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_comparison/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Related Metrics Bar for Sales, Sales Growth Rate", "infer current or all" ], "who": "Mexico hair color", "what": "Related Metrics Bar for Sales, Sales Growth Rate", "when": "infer current or all", "source": "../mix_comparison/mix_comparison/related_metrics_bar_chart_context.json" }, "context_summary": { "capability": "mix.stacked_bar_overlay", "grammar": "bar with marker", "metrics": "Sales, Sales Growth Rate", "dimensions": "Brand", "periods": "_Aug-2016, _Aug-2017", "trace_widths": "0.9", "source_reference": "related_metrics_bar" }, "original_artifact_contract": { "capability_id": "mix.stacked_bar_overlay", "status": "context_only", "when_to_use": "mix.stacked_bar_overlay", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "overlay", "selector_level": "capability_choice", "variant_changes_capability_selection": true, "adds_parameter_roles": [ "related_marker_metric" ], "variant_selection_cues": [ "question asks for a primary metric plus a related marker metric" ] } }, { "label": "mix_comparison / related_metrics_bar_small_multiples", "capability_id": "mix.stacked_bar_overlay", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_comparison/related_metrics_bar_small_multiples.html", "output": "mix_comparison__related_metrics_bar_small_multiples.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_comparison/related_metrics_bar_small_multiples.html" }, { "label": "context", "href": "../mix_comparison/mix_comparison/related_metrics_bar_small_multiples_chart_context.json" }, { "label": "data", "href": "../mix_comparison/mix_comparison/related_metrics_bar_small_multiples_chart_data.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_comparison/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_comparison/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Related Metrics Bar Small Multiples for Sales, Sales Growth Rate", "infer current or all" ], "who": "Mexico hair color", "what": "Related Metrics Bar Small Multiples for Sales, Sales Growth Rate", "when": "infer current or all", "source": "../mix_comparison/mix_comparison/related_metrics_bar_small_multiples_chart_context.json" }, "context_summary": { "capability": "mix.stacked_bar_overlay", "grammar": "bar with marker", "metrics": "Sales, Sales Growth Rate", "dimensions": "Brand, Channel", "periods": "_Aug-2016, _Aug-2017", "trace_widths": "0.9", "source_reference": "related_metrics_bar_smal..." }, "original_artifact_contract": { "capability_id": "mix.stacked_bar_overlay", "status": "context_only", "when_to_use": "mix.stacked_bar_overlay", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "overlay", "selector_level": "capability_choice", "variant_changes_capability_selection": true, "adds_parameter_roles": [ "panel_dimension", "related_marker_metric" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension", "question asks for a primary metric plus a related marker metric" ] } }, { "label": "mix_comparison / multitier_bar", "capability_id": "mix.multitier_bar", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_comparison/multitier_bar.html", "output": "mix_comparison__multitier_bar.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_comparison/multitier_bar.html" }, { "label": "context", "href": "../mix_comparison/mix_comparison/multitier_bar_chart_context.json" }, { "label": "data", "href": "../mix_comparison/mix_comparison/multitier_bar_chart_data.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_comparison/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_comparison/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Multitier Bar for Sales", "infer current or all" ], "who": "Mexico hair color", "what": "Multitier Bar for Sales", "when": "infer current or all", "source": "../mix_comparison/mix_comparison/multitier_bar_chart_context.json" }, "context_summary": { "capability": "mix.multitier_bar", "grammar": "multitier_bar", "metrics": "Sales", "dimensions": "Company", "periods": "_Aug-2016, _Aug-2017", "trace_widths": "0.1, 0.68", "source_reference": "multitier_bar" }, "original_artifact_contract": { "capability_id": "mix.multitier_bar", "status": "context_only", "when_to_use": "mix.multitier_bar", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "multitier", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_comparison / multitier_bar_dimension_panels", "capability_id": "mix.multitier_bar", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_comparison/multitier_bar_dimension_panels.html", "output": "mix_comparison__multitier_bar_dimension_panels.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_comparison/multitier_bar_dimension_panels.html" }, { "label": "context", "href": "../mix_comparison/mix_comparison/source_pack/contexts/mix_contribution_context.json" }, { "label": "data", "href": "../mix_comparison/mix_comparison/mix_contribution_summary.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_comparison/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_comparison/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Multitier Bar Two Dimension for Sales", "infer current or all" ], "who": "Mexico hair color", "what": "Multitier Bar Two Dimension for Sales", "when": "infer current or all", "source": "../mix_comparison/mix_comparison/source_pack/contexts/mix_contribution_context.json" }, "context_summary": { "capability": "mix.multitier_bar", "grammar": "mix.multitier_bar", "metrics": "Sales", "dimensions": null, "periods": "_Aug-2016, _Aug-2017", "trace_widths": "0.68", "source_reference": "multitier_bar_dimension_..." }, "original_artifact_contract": { "capability_id": "mix.multitier_bar", "status": "context_only", "when_to_use": "mix.multitier_bar", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "panelled", "encoding_variant": "multitier", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks for side-by-side panels for the same capability" ] } }, { "label": "mix_comparison / multitier_bar_two_dimension", "capability_id": "mix.multitier_bar", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_comparison/multitier_bar_two_dimension.html", "output": "mix_comparison__multitier_bar_two_dimension.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_comparison/multitier_bar_two_dimension.html" }, { "label": "context", "href": "../mix_comparison/mix_comparison/source_pack/contexts/mix_contribution_context.json" }, { "label": "data", "href": "../mix_comparison/mix_comparison/mix_contribution_summary.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_comparison/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_comparison/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Multitier Bar Two Dimension for Sales", "infer current or all" ], "who": "Mexico hair color", "what": "Multitier Bar Two Dimension for Sales", "when": "infer current or all", "source": "../mix_comparison/mix_comparison/source_pack/contexts/mix_contribution_context.json" }, "context_summary": { "capability": "mix.multitier_bar", "grammar": "mix.multitier_bar", "metrics": "Sales", "dimensions": "Brand, Channel", "periods": "_Aug-2016, _Aug-2017", "trace_widths": "0.68", "source_reference": "multitier_bar_two_dimens..." }, "original_artifact_contract": { "capability_id": "mix.multitier_bar", "status": "context_only", "when_to_use": "mix.multitier_bar", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "panelled", "encoding_variant": "multitier", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks for side-by-side panels for the same capability" ] } }, { "label": "mix_like_for_like / like_for_like_column_total", "capability_id": "mix.like_for_like_column", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_like_for_like/mix_like_for_like/like_for_like_column_total.html", "output": "mix_like_for_like__like_for_like_column_total.png", "sidecars": [ { "label": "source", "href": "../mix_like_for_like/mix_like_for_like/like_for_like_column_total.html" }, { "label": "context", "href": "../mix_like_for_like/mix_like_for_like/like_for_like_column_total_chart_context.json" }, { "label": "data", "href": "../mix_like_for_like/mix_like_for_like/like_for_like_column_total_chart_data.csv" }, { "label": "manifest", "href": "../mix_like_for_like/mix_like_for_like/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_like_for_like/mix_like_for_like/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Like For Like Column Total for Sales", "explicit comparison periods" ], "who": "Mexico hair color", "what": "Like For Like Column Total for Sales", "when": "explicit comparison periods", "source": "../mix_like_for_like/mix_like_for_like/like_for_like_column_total_chart_context.json" }, "context_summary": { "capability": "mix.like_for_like_column", "grammar": "stacked column", "metrics": "Sales", "dimensions": "Total View", "periods": "_Aug-2016, _Aug-2017, ", "trace_widths": "0.8", "source_reference": "like_for_like_column_tot..." }, "original_artifact_contract": { "capability_id": "mix.like_for_like_column", "status": "context_only", "when_to_use": "mix.like_for_like_column", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "like_for_like", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_like_for_like / like_for_like_stacked_column", "capability_id": "mix.like_for_like_stacked_column", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_like_for_like/mix_like_for_like/like_for_like_stacked_column.html", "output": "mix_like_for_like__like_for_like_stacked_column.png", "sidecars": [ { "label": "source", "href": "../mix_like_for_like/mix_like_for_like/like_for_like_stacked_column.html" }, { "label": "context", "href": "../mix_like_for_like/mix_like_for_like/like_for_like_stacked_column_chart_context.json" }, { "label": "data", "href": "../mix_like_for_like/mix_like_for_like/like_for_like_stacked_column_chart_data.csv" }, { "label": "manifest", "href": "../mix_like_for_like/mix_like_for_like/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_like_for_like/mix_like_for_like/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Like For Like Stacked Column for Sales", "explicit comparison periods" ], "who": "Mexico hair color", "what": "Like For Like Stacked Column for Sales", "when": "explicit comparison periods", "source": "../mix_like_for_like/mix_like_for_like/like_for_like_stacked_column_chart_context.json" }, "context_summary": { "capability": "mix.like_for_like_stacked_column", "grammar": "stacked column", "metrics": "Sales", "dimensions": "Company", "periods": "_Aug-2016, _Aug-2017, ", "trace_widths": "0.8", "source_reference": "like_for_like_stacked_co..." }, "original_artifact_contract": { "capability_id": "mix.like_for_like_stacked_column", "status": "context_only", "when_to_use": "mix.like_for_like_stacked_column", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "like_for_like", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_cohort / cohort_since_stacked_column", "capability_id": "mix.cohort_since_stacked_column", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_cohort/mix_cohort/cohort_since_stacked_column.html", "output": "mix_cohort__cohort_since_stacked_column.png", "sidecars": [ { "label": "source", "href": "../mix_cohort/mix_cohort/cohort_since_stacked_column.html" }, { "label": "context", "href": "../mix_cohort/mix_cohort/cohort_since_stacked_column_chart_context.json" }, { "label": "data", "href": "../mix_cohort/mix_cohort/cohort_since_stacked_column_chart_data.csv" }, { "label": "manifest", "href": "../mix_cohort/mix_cohort/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_cohort/mix_cohort/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Cohort Since Stacked Column for Sales", "infer current or all" ], "who": "Mexico hair color", "what": "Cohort Since Stacked Column for Sales", "when": "infer current or all", "source": "../mix_cohort/mix_cohort/cohort_since_stacked_column_chart_context.json" }, "context_summary": { "capability": "mix.cohort_since_stacked_column", "grammar": "stacked column", "metrics": "Sales", "dimensions": "Period, Barcode_Since", "periods": "2015, 2016, 2017", "trace_widths": "0.8", "source_reference": "cohort_since_stacked_col..." }, "original_artifact_contract": { "capability_id": "mix.cohort_since_stacked_column", "status": "context_only", "when_to_use": "mix.cohort_since_stacked_column", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "cohort", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_cohort / cohort_lost_stacked_column", "capability_id": "mix.cohort_lost_stacked_column", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_cohort/mix_cohort/cohort_lost_stacked_column.html", "output": "mix_cohort__cohort_lost_stacked_column.png", "sidecars": [ { "label": "source", "href": "../mix_cohort/mix_cohort/cohort_lost_stacked_column.html" }, { "label": "context", "href": "../mix_cohort/mix_cohort/cohort_lost_stacked_column_chart_context.json" }, { "label": "data", "href": "../mix_cohort/mix_cohort/cohort_lost_stacked_column_chart_data.csv" }, { "label": "manifest", "href": "../mix_cohort/mix_cohort/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_cohort/mix_cohort/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Cohort Lost Stacked Column for Sales", "infer current or all" ], "who": "Mexico hair color", "what": "Cohort Lost Stacked Column for Sales", "when": "infer current or all", "source": "../mix_cohort/mix_cohort/cohort_lost_stacked_column_chart_context.json" }, "context_summary": { "capability": "mix.cohort_lost_stacked_column", "grammar": "stacked column", "metrics": "Sales", "dimensions": "Period, Barcode_Lost", "periods": "2015, 2016, 2017", "trace_widths": "0.8", "source_reference": "cohort_lost_stacked_colu..." }, "original_artifact_contract": { "capability_id": "mix.cohort_lost_stacked_column", "status": "context_only", "when_to_use": "mix.cohort_lost_stacked_column", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "cohort", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_comparison / line", "capability_id": "mix.timeline", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_regular/line.html", "output": "mix_comparison__mix_regular__line.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_regular/line.html" }, { "label": "context", "href": "../mix_comparison/mix_regular/source_pack/contexts/mix_contribution_context.json" }, { "label": "data", "href": "../mix_comparison/mix_regular/mix_contribution_summary.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mix & Contribution Analysis", "mix.timeline | Sales", "AC" ], "who": "Mix & Contribution Analysis", "what": "mix.timeline | Sales", "when": "AC", "source": "../mix_comparison/mix_regular/source_pack/contexts/mix_contribution_context.json" }, "context_summary": { "capability": "mix.timeline", "grammar": "mix.timeline", "metrics": "Sales", "dimensions": null, "periods": "AC", "trace_widths": null, "source_reference": "line" }, "original_artifact_contract": { "capability_id": "mix.timeline", "status": "context_only", "when_to_use": "mix.timeline", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "line", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_comparison / line_small_multiples", "capability_id": "mix.timeline", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_regular/line_small_multiples.html", "output": "mix_comparison__mix_regular__line_small_multiples.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_regular/line_small_multiples.html" }, { "label": "context", "href": "../mix_comparison/mix_regular/source_pack/contexts/mix_contribution_context.json" }, { "label": "data", "href": "../mix_comparison/mix_regular/mix_contribution_summary.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mix & Contribution Analysis", "mix.timeline | Sales | Company", "AC" ], "who": "Mix & Contribution Analysis", "what": "mix.timeline | Sales | Company", "when": "AC", "source": "../mix_comparison/mix_regular/source_pack/contexts/mix_contribution_context.json" }, "context_summary": { "capability": "mix.timeline", "grammar": "mix.timeline", "metrics": "Sales", "dimensions": "Company", "periods": "AC", "trace_widths": null, "source_reference": "line_small_multiples" }, "original_artifact_contract": { "capability_id": "mix.timeline", "status": "context_only", "when_to_use": "mix.timeline", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "line", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "mix_comparison / area_absolute", "capability_id": "mix.area", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_regular/area_absolute.html", "output": "mix_comparison__mix_regular__area_absolute.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_regular/area_absolute.html" }, { "label": "context", "href": "../mix_comparison/mix_regular/source_pack/contexts/mix_contribution_context.json" }, { "label": "data", "href": "../mix_comparison/mix_regular/mix_contribution_summary.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mix & Contribution Analysis", "mix.area | Sales | Company", "AC" ], "who": "Mix & Contribution Analysis", "what": "mix.area | Sales | Company", "when": "AC", "source": "../mix_comparison/mix_regular/source_pack/contexts/mix_contribution_context.json" }, "context_summary": { "capability": "mix.area", "grammar": "mix.area", "metrics": "Sales", "dimensions": "Company", "periods": "AC", "trace_widths": null, "source_reference": "area_absolute" }, "original_artifact_contract": { "capability_id": "mix.area", "status": "context_only", "when_to_use": "mix.area", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "area", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_comparison / area_share", "capability_id": "mix.area", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_regular/area_share.html", "output": "mix_comparison__mix_regular__area_share.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_regular/area_share.html" }, { "label": "context", "href": "../mix_comparison/mix_regular/source_pack/contexts/mix_contribution_context.json" }, { "label": "data", "href": "../mix_comparison/mix_regular/mix_contribution_summary.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mix & Contribution Analysis", "mix.area | Sales | Company", "AC" ], "who": "Mix & Contribution Analysis", "what": "mix.area | Sales | Company", "when": "AC", "source": "../mix_comparison/mix_regular/source_pack/contexts/mix_contribution_context.json" }, "context_summary": { "capability": "mix.area", "grammar": "mix.area", "metrics": "Sales", "dimensions": "Company", "periods": "AC", "trace_widths": null, "source_reference": "area_share" }, "original_artifact_contract": { "capability_id": "mix.area", "status": "context_only", "when_to_use": "mix.area", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "area", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_current / barmekko", "capability_id": "mix.barmekko", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_current/mix_regular/barmekko.html", "output": "mix_current__mix_regular__barmekko.png", "sidecars": [ { "label": "source", "href": "../mix_current/mix_regular/barmekko.html" }, { "label": "context", "href": "../mix_current/mix_regular/source_pack/contexts/mix_contribution_context.json" }, { "label": "data", "href": "../mix_current/mix_regular/mix_contribution_summary.csv" }, { "label": "manifest", "href": "../mix_current/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_current/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mix & Contribution Analysis", "mix.barmekko | Unit Price, Units | Company, Channel", "AC" ], "who": "Mix & Contribution Analysis", "what": "mix.barmekko | Unit Price, Units | Company, Channel", "when": "AC", "source": "../mix_current/mix_regular/source_pack/contexts/mix_contribution_context.json" }, "context_summary": { "capability": "mix.barmekko", "grammar": "mix.barmekko", "metrics": "Unit Price, Units", "dimensions": "Company, Channel", "periods": "AC", "trace_widths": "758695, 2154343, 4131041, 4220396 +2", "source_reference": "barmekko" }, "original_artifact_contract": { "capability_id": "mix.barmekko", "status": "context_only", "when_to_use": "mix.barmekko", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "variable_width", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_current / barmekko_small_multiples", "capability_id": "mix.barmekko", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_current/mix_regular/barmekko_small_multiples.html", "output": "mix_current__mix_regular__barmekko_small_multiples.png", "sidecars": [ { "label": "source", "href": "../mix_current/mix_regular/barmekko_small_multiples.html" }, { "label": "context", "href": "../mix_current/mix_regular/source_pack/contexts/mix_contribution_context.json" }, { "label": "data", "href": "../mix_current/mix_regular/mix_contribution_summary.csv" }, { "label": "manifest", "href": "../mix_current/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_current/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mix & Contribution Analysis", "mix.barmekko | Unit Price, Units | Company, Channel, Type", "AC" ], "who": "Mix & Contribution Analysis", "what": "mix.barmekko | Unit Price, Units | Company, Channel, Type", "when": "AC", "source": "../mix_current/mix_regular/source_pack/contexts/mix_contribution_context.json" }, "context_summary": { "capability": "mix.barmekko", "grammar": "mix.barmekko", "metrics": "Unit Price, Units", "dimensions": "Company, Channel, Type", "periods": "AC", "trace_widths": "1354, 18391, 21099, 27940 +9", "source_reference": "barmekko_small_multiples" }, "original_artifact_contract": { "capability_id": "mix.barmekko", "status": "context_only", "when_to_use": "mix.barmekko", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "variable_width", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "mix_current / marimekko", "capability_id": "mix.marimekko", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_current/mix_regular/marimekko.html", "output": "mix_current__mix_regular__marimekko.png", "sidecars": [ { "label": "source", "href": "../mix_current/mix_regular/marimekko.html" }, { "label": "context", "href": "../mix_current/mix_regular/source_pack/contexts/mix_contribution_context.json" }, { "label": "data", "href": "../mix_current/mix_regular/mix_contribution_summary.csv" }, { "label": "manifest", "href": "../mix_current/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_current/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mix & Contribution Analysis", "mix.marimekko | Sales | Company, Channel", "AC" ], "who": "Mix & Contribution Analysis", "what": "mix.marimekko | Sales | Company, Channel", "when": "AC", "source": "../mix_current/mix_regular/source_pack/contexts/mix_contribution_context.json" }, "context_summary": { "capability": "mix.marimekko", "grammar": "mix.marimekko", "metrics": "Sales", "dimensions": "Company, Channel", "periods": "AC", "trace_widths": "103820870, 107924856, 130655887, 131283368 +2", "source_reference": "marimekko" }, "original_artifact_contract": { "capability_id": "mix.marimekko", "status": "context_only", "when_to_use": "mix.marimekko", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "variable_width", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_current / marimekko_small_multiples", "capability_id": "mix.marimekko", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_current/mix_regular/marimekko_small_multiples.html", "output": "mix_current__mix_regular__marimekko_small_multiples.png", "sidecars": [ { "label": "source", "href": "../mix_current/mix_regular/marimekko_small_multiples.html" }, { "label": "context", "href": "../mix_current/mix_regular/source_pack/contexts/mix_contribution_context.json" }, { "label": "data", "href": "../mix_current/mix_regular/mix_contribution_summary.csv" }, { "label": "manifest", "href": "../mix_current/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_current/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mix & Contribution Analysis", "mix.marimekko | Sales | Company, Channel, Type", "AC" ], "who": "Mix & Contribution Analysis", "what": "mix.marimekko | Sales | Company, Channel, Type", "when": "AC", "source": "../mix_current/mix_regular/source_pack/contexts/mix_contribution_context.json" }, "context_summary": { "capability": "mix.marimekko", "grammar": "mix.marimekko", "metrics": "Sales", "dimensions": "Company, Channel, Type", "periods": "AC", "trace_widths": "131468, 1874924, 1916776, 1956355 +9", "source_reference": "marimekko_small_multiple..." }, "original_artifact_contract": { "capability_id": "mix.marimekko", "status": "context_only", "when_to_use": "mix.marimekko", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "variable_width", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "mix_current / pareto", "capability_id": "mix.pareto", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_current/mix_regular/pareto.html", "output": "mix_current__mix_regular__pareto.png", "sidecars": [ { "label": "source", "href": "../mix_current/mix_regular/pareto.html" }, { "label": "context", "href": "../mix_current/mix_regular/source_pack/contexts/mix_contribution_context.json" }, { "label": "data", "href": "../mix_current/mix_regular/mix_contribution_summary.csv" }, { "label": "manifest", "href": "../mix_current/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_current/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mix & Contribution Analysis", "mix.pareto | Sales, Units | Product", "AC" ], "who": "Mix & Contribution Analysis", "what": "mix.pareto | Sales, Units | Product", "when": "AC", "source": "../mix_current/mix_regular/source_pack/contexts/mix_contribution_context.json" }, "context_summary": { "capability": "mix.pareto", "grammar": "mix.pareto", "metrics": "Sales, Units", "dimensions": "Product", "periods": "AC", "trace_widths": null, "source_reference": "pareto" }, "original_artifact_contract": { "capability_id": "mix.pareto", "status": "context_only", "when_to_use": "mix.pareto", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "pareto", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_current / stacked_pareto_abc", "capability_id": "mix.stacked_pareto", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_current/mix_regular/stacked_pareto_abc.html", "output": "mix_current__mix_regular__stacked_pareto_abc.png", "sidecars": [ { "label": "source", "href": "../mix_current/mix_regular/stacked_pareto_abc.html" }, { "label": "context", "href": "../mix_current/mix_regular/stacked_pareto_abc_chart_context.json" }, { "label": "data", "href": "../mix_current/mix_regular/stacked_pareto_abc_chart_data.csv" }, { "label": "manifest", "href": "../mix_current/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_current/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mix & Contribution Analysis", "pareto stacked column | Sales, Units | Brand", "AC" ], "who": "Mix & Contribution Analysis", "what": "pareto stacked column | Sales, Units | Brand", "when": "AC", "source": "../mix_current/mix_regular/stacked_pareto_abc_chart_context.json" }, "context_summary": { "capability": "mix.stacked_pareto", "grammar": "pareto stacked column", "metrics": "Sales, Units", "dimensions": "Brand", "periods": "AC", "trace_widths": "0.9", "source_reference": "stacked_pareto_abc" }, "original_artifact_contract": { "capability_id": "mix.stacked_pareto", "status": "context_only", "when_to_use": "mix.stacked_pareto", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "stacked_pareto", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_current / stacked_pareto_by_dimension", "capability_id": "mix.stacked_pareto", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_current/mix_regular/stacked_pareto_by_dimension.html", "output": "mix_current__mix_regular__stacked_pareto_by_dimension.png", "sidecars": [ { "label": "source", "href": "../mix_current/mix_regular/stacked_pareto_by_dimension.html" }, { "label": "context", "href": "../mix_current/mix_regular/stacked_pareto_by_dimension_chart_context.json" }, { "label": "data", "href": "../mix_current/mix_regular/stacked_pareto_by_dimension_chart_data.csv" }, { "label": "manifest", "href": "../mix_current/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_current/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mix & Contribution Analysis", "pareto stacked column | Sales, Units | Brand, Company", "AC" ], "who": "Mix & Contribution Analysis", "what": "pareto stacked column | Sales, Units | Brand, Company", "when": "AC", "source": "../mix_current/mix_regular/stacked_pareto_by_dimension_chart_context.json" }, "context_summary": { "capability": "mix.stacked_pareto", "grammar": "pareto stacked column", "metrics": "Sales, Units", "dimensions": "Brand, Company", "periods": "AC", "trace_widths": "0.9", "source_reference": "stacked_pareto_by_dimens..." }, "original_artifact_contract": { "capability_id": "mix.stacked_pareto", "status": "context_only", "when_to_use": "mix.stacked_pareto", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "stacked_pareto", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_comparison / mix_comparison_column_total / column_total", "capability_id": "mix.column", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_comparison_column_total/column_total.html", "output": "mix_comparison__mix_comparison_column_total__column_total.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_comparison_column_total/column_total.html" }, { "label": "context", "href": "../mix_comparison/mix_comparison_column_total/column_total_chart_context.json" }, { "label": "data", "href": "../mix_comparison/mix_comparison_column_total/column_total_chart_data.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_comparison_column_total/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_comparison_column_total/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Column Total for Sales", "infer current or all" ], "who": "Mexico hair color", "what": "Column Total for Sales", "when": "infer current or all", "source": "../mix_comparison/mix_comparison_column_total/column_total_chart_context.json" }, "context_summary": { "capability": "mix.column", "grammar": "stacked column", "metrics": "Sales", "dimensions": "Total View", "periods": "_Aug-2016, _Aug-2017, ", "trace_widths": "0.8", "source_reference": "column_total" }, "original_artifact_contract": { "capability_id": "mix.column", "status": "context_only", "when_to_use": "mix.column", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "column", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_comparison / mix_comparison_column_total / column_total_with_overlay", "capability_id": "mix.column_overlay", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_comparison_column_total/column_total_with_overlay.html", "output": "mix_comparison__mix_comparison_column_total__column_total_with_overlay.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_comparison_column_total/column_total_with_overlay.html" }, { "label": "context", "href": "../mix_comparison/mix_comparison_column_total/column_total_with_overlay_chart_context.json" }, { "label": "data", "href": "../mix_comparison/mix_comparison_column_total/column_total_with_overlay_chart_data.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_comparison_column_total/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_comparison_column_total/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Column Total With Overlay for Sales, Units", "infer current or all" ], "who": "Mexico hair color", "what": "Column Total With Overlay for Sales, Units", "when": "infer current or all", "source": "../mix_comparison/mix_comparison_column_total/column_total_with_overlay_chart_context.json" }, "context_summary": { "capability": "mix.column_overlay", "grammar": "stacked column", "metrics": "Sales, Units", "dimensions": "Total View", "periods": "_Aug-2016, _Aug-2017, ", "trace_widths": "0.8", "source_reference": "column_total_with_overla..." }, "original_artifact_contract": { "capability_id": "mix.column_overlay", "status": "context_only", "when_to_use": "mix.column_overlay", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "overlay", "selector_level": "capability_choice", "variant_changes_capability_selection": true, "adds_parameter_roles": [ "related_marker_metric" ], "variant_selection_cues": [ "question asks for a primary metric plus a related marker metric" ] } }, { "label": "mix_comparison / mix_regular / stacked_column", "capability_id": "mix.stacked_column", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_regular/stacked_column.html", "output": "mix_comparison__mix_regular__stacked_column.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_regular/stacked_column.html" }, { "label": "context", "href": "../mix_comparison/mix_regular/stacked_column_chart_context.json" }, { "label": "data", "href": "../mix_comparison/mix_regular/stacked_column_chart_data.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in mEUR by Company", "YTD through 2017-08-27" ], "who": "Mexico hair color", "what": "Sales in mEUR by Company", "when": "YTD through 2017-08-27", "source": "../mix_comparison/mix_regular/stacked_column_chart_context.json" }, "context_summary": { "capability": "mix.stacked_column", "grammar": "stacked column", "metrics": "Sales", "dimensions": "Company", "periods": "_Aug-2016, _Aug-2017, ", "trace_widths": "0.8", "source_reference": "stacked_column" }, "original_artifact_contract": { "capability_id": "mix.stacked_column", "status": "context_only", "when_to_use": "mix.stacked_column", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "stacked", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "mix_comparison / mix_regular / stacked_column_small_multiples", "capability_id": "mix.stacked_column", "plugin_source": "mix-contribution-analysis", "artifact_type": "html", "source": "../mix_comparison/mix_regular/stacked_column_small_multiples.html", "output": "mix_comparison__mix_regular__stacked_column_small_multiples.png", "sidecars": [ { "label": "source", "href": "../mix_comparison/mix_regular/stacked_column_small_multiples.html" }, { "label": "context", "href": "../mix_comparison/mix_regular/stacked_column_small_multiples_chart_context.json" }, { "label": "data", "href": "../mix_comparison/mix_regular/stacked_column_small_multiples_chart_data.csv" }, { "label": "manifest", "href": "../mix_comparison/mix_regular/source_pack/manifest.json" }, { "label": "recipe", "href": "../mix_comparison/mix_regular/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Sales in mEUR by Company", "YTD through 2017-08-27" ], "who": "Mexico hair color", "what": "Sales in mEUR by Company", "when": "YTD through 2017-08-27", "source": "../mix_comparison/mix_regular/stacked_column_small_multiples_chart_context.json" }, "context_summary": { "capability": "mix.stacked_column", "grammar": "stacked column", "metrics": "Sales", "dimensions": "Company", "periods": "_Aug-2016, _Aug-2017, ", "trace_widths": "0.8", "source_reference": "stacked_column_small_mul..." }, "original_artifact_contract": { "capability_id": "mix.stacked_column", "status": "context_only", "when_to_use": "mix.stacked_column", "required_parameters": [ "metric", "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "stacked", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "scatter / scatter_bubble / bubble", "capability_id": "scatter.bubble", "plugin_source": "scatter-bubble-analysis", "artifact_type": "html", "source": "../scatter/scatter_bubble/bubble.html", "output": "scatter__scatter_bubble__bubble.png", "sidecars": [ { "label": "source", "href": "../scatter/scatter_bubble/bubble.html" }, { "label": "context", "href": "../scatter/scatter_bubble/bubble_chart_context.json" }, { "label": "data", "href": "../scatter/scatter_bubble/bubble_chart_data.csv" }, { "label": "manifest", "href": "../scatter/scatter_bubble/source_pack/manifest.json" }, { "label": "recipe", "href": "../scatter/scatter_bubble/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Units, CWD, Value_LC in m by Company", "AC vs PY" ], "who": "Mexico hair color", "what": "Units, CWD, Value_LC in m by Company", "when": "AC vs PY", "source": "../scatter/scatter_bubble/bubble_chart_context.json" }, "context_summary": { "capability": "scatter.bubble", "grammar": "bubbleChart", "metrics": null, "dimensions": "Company, Brand, Channel +3", "periods": "AC", "trace_widths": null, "source_reference": "bubble" }, "original_artifact_contract": { "capability_id": "scatter.bubble", "status": "context_only", "when_to_use": "scatter.bubble", "required_parameters": [ "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "bubble", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "scatter / scatter_bubble / bubble_small_multiples", "capability_id": "scatter.bubble", "plugin_source": "scatter-bubble-analysis", "artifact_type": "html", "source": "../scatter/scatter_bubble/bubble_small_multiples.html", "output": "scatter__scatter_bubble__bubble_small_multiples.png", "sidecars": [ { "label": "source", "href": "../scatter/scatter_bubble/bubble_small_multiples.html" }, { "label": "context", "href": "../scatter/scatter_bubble/bubble_small_multiples_chart_context.json" }, { "label": "data", "href": "../scatter/scatter_bubble/bubble_small_multiples_chart_data.csv" }, { "label": "manifest", "href": "../scatter/scatter_bubble/source_pack/manifest.json" }, { "label": "recipe", "href": "../scatter/scatter_bubble/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Units, CWD, Value_LC in m by Company and Channel", "AC vs PY" ], "who": "Mexico hair color", "what": "Units, CWD, Value_LC in m by Company and Channel", "when": "AC vs PY", "source": "../scatter/scatter_bubble/bubble_small_multiples_chart_context.json" }, "context_summary": { "capability": "scatter.bubble", "grammar": "bubbleChart", "metrics": null, "dimensions": "Company, Brand, Channel +3", "periods": "AC", "trace_widths": null, "source_reference": "bubble_small_multiples" }, "original_artifact_contract": { "capability_id": "scatter.bubble", "status": "context_only", "when_to_use": "scatter.bubble", "required_parameters": [ "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "bubble", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "scatter / scatter_bubble / scatter", "capability_id": "scatter.scatter", "plugin_source": "scatter-bubble-analysis", "artifact_type": "html", "source": "../scatter/scatter_bubble/scatter.html", "output": "scatter__scatter_bubble__scatter.png", "sidecars": [ { "label": "source", "href": "../scatter/scatter_bubble/scatter.html" }, { "label": "context", "href": "../scatter/scatter_bubble/scatter_chart_context.json" }, { "label": "data", "href": "../scatter/scatter_bubble/scatter_chart_data.csv" }, { "label": "manifest", "href": "../scatter/scatter_bubble/source_pack/manifest.json" }, { "label": "recipe", "href": "../scatter/scatter_bubble/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Units, CWD in m aggregated by Company", "AC vs PY" ], "who": "Mexico hair color", "what": "Units, CWD in m aggregated by Company", "when": "AC vs PY", "source": "../scatter/scatter_bubble/scatter_chart_context.json" }, "context_summary": { "capability": "scatter.scatter", "grammar": "scatterChart", "metrics": null, "dimensions": "Company, Brand, Channel +3", "periods": "AC", "trace_widths": null, "source_reference": "scatter" }, "original_artifact_contract": { "capability_id": "scatter.scatter", "status": "context_only", "when_to_use": "scatter.scatter", "required_parameters": [ "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "scatter", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "scatter / scatter_bubble / scatter_small_multiples", "capability_id": "scatter.scatter", "plugin_source": "scatter-bubble-analysis", "artifact_type": "html", "source": "../scatter/scatter_bubble/scatter_small_multiples.html", "output": "scatter__scatter_bubble__scatter_small_multiples.png", "sidecars": [ { "label": "source", "href": "../scatter/scatter_bubble/scatter_small_multiples.html" }, { "label": "context", "href": "../scatter/scatter_bubble/scatter_small_multiples_chart_context.json" }, { "label": "data", "href": "../scatter/scatter_bubble/scatter_small_multiples_chart_data.csv" }, { "label": "manifest", "href": "../scatter/scatter_bubble/source_pack/manifest.json" }, { "label": "recipe", "href": "../scatter/scatter_bubble/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Units, CWD in m aggregated by Company and Channel", "AC vs PY" ], "who": "Mexico hair color", "what": "Units, CWD in m aggregated by Company and Channel", "when": "AC vs PY", "source": "../scatter/scatter_bubble/scatter_small_multiples_chart_context.json" }, "context_summary": { "capability": "scatter.scatter", "grammar": "scatterChart", "metrics": null, "dimensions": "Company, Brand, Channel +3", "periods": "AC", "trace_widths": null, "source_reference": "scatter_small_multiples" }, "original_artifact_contract": { "capability_id": "scatter.scatter", "status": "context_only", "when_to_use": "scatter.scatter", "required_parameters": [ "dimensions" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "scatter", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "distribution / boxplot", "capability_id": "distribution.boxplot", "plugin_source": "distribution-analysis", "artifact_type": "html", "source": "../distribution/distribution/boxplot.html", "output": "distribution__boxplot.png", "sidecars": [ { "label": "source", "href": "../distribution/distribution/boxplot.html" }, { "label": "context", "href": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, { "label": "data", "href": "../distribution/distribution/distribution_summary.csv" }, { "label": "manifest", "href": "../distribution/distribution/source_pack/manifest.json" }, { "label": "recipe", "href": "../distribution/distribution/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Stripplot Small Multiples of Units by Company", "~Aug 2017 vs ~Aug 2016, through 2017 08 27" ], "who": "Mexico hair color", "what": "Stripplot Small Multiples of Units by Company", "when": "~Aug 2017 vs ~Aug 2016, through 2017 08 27", "source": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, "context_summary": { "capability": "distribution.boxplot", "grammar": "distribution.boxplot", "metrics": "Units", "dimensions": null, "periods": "~Aug-2016, ~Aug-2017", "trace_widths": null, "source_reference": "boxplot" }, "original_artifact_contract": { "capability_id": "distribution.boxplot", "status": "context_only", "when_to_use": "distribution.boxplot", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "boxplot", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "distribution / boxplot_small_multiples", "capability_id": "distribution.boxplot", "plugin_source": "distribution-analysis", "artifact_type": "html", "source": "../distribution/distribution/boxplot_small_multiples.html", "output": "distribution__boxplot_small_multiples.png", "sidecars": [ { "label": "source", "href": "../distribution/distribution/boxplot_small_multiples.html" }, { "label": "context", "href": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, { "label": "data", "href": "../distribution/distribution/distribution_summary.csv" }, { "label": "manifest", "href": "../distribution/distribution/source_pack/manifest.json" }, { "label": "recipe", "href": "../distribution/distribution/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Stripplot Small Multiples of Units by Company", "~Aug 2017 vs ~Aug 2016, through 2017 08 27" ], "who": "Mexico hair color", "what": "Stripplot Small Multiples of Units by Company", "when": "~Aug 2017 vs ~Aug 2016, through 2017 08 27", "source": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, "context_summary": { "capability": "distribution.boxplot", "grammar": "distribution.boxplot", "metrics": "Units", "dimensions": null, "periods": "~Aug-2016, ~Aug-2017", "trace_widths": null, "source_reference": "boxplot_small_multiples" }, "original_artifact_contract": { "capability_id": "distribution.boxplot", "status": "context_only", "when_to_use": "distribution.boxplot", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "boxplot", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "distribution / ecdf", "capability_id": "distribution.ecdf", "plugin_source": "distribution-analysis", "artifact_type": "html", "source": "../distribution/distribution/ecdf.html", "output": "distribution__ecdf.png", "sidecars": [ { "label": "source", "href": "../distribution/distribution/ecdf.html" }, { "label": "context", "href": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, { "label": "data", "href": "../distribution/distribution/distribution_summary.csv" }, { "label": "manifest", "href": "../distribution/distribution/source_pack/manifest.json" }, { "label": "recipe", "href": "../distribution/distribution/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Stripplot Small Multiples of Units by Company", "~Aug 2017 vs ~Aug 2016, through 2017 08 27" ], "who": "Mexico hair color", "what": "Stripplot Small Multiples of Units by Company", "when": "~Aug 2017 vs ~Aug 2016, through 2017 08 27", "source": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, "context_summary": { "capability": "distribution.ecdf", "grammar": "distribution.ecdf", "metrics": "Units", "dimensions": null, "periods": "~Aug-2016, ~Aug-2017", "trace_widths": null, "source_reference": "ecdf" }, "original_artifact_contract": { "capability_id": "distribution.ecdf", "status": "context_only", "when_to_use": "distribution.ecdf", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "ecdf", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "distribution / ecdf_small_multiples", "capability_id": "distribution.ecdf", "plugin_source": "distribution-analysis", "artifact_type": "html", "source": "../distribution/distribution/ecdf_small_multiples.html", "output": "distribution__ecdf_small_multiples.png", "sidecars": [ { "label": "source", "href": "../distribution/distribution/ecdf_small_multiples.html" }, { "label": "context", "href": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, { "label": "data", "href": "../distribution/distribution/distribution_summary.csv" }, { "label": "manifest", "href": "../distribution/distribution/source_pack/manifest.json" }, { "label": "recipe", "href": "../distribution/distribution/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Stripplot Small Multiples of Units by Company", "~Aug 2017 vs ~Aug 2016, through 2017 08 27" ], "who": "Mexico hair color", "what": "Stripplot Small Multiples of Units by Company", "when": "~Aug 2017 vs ~Aug 2016, through 2017 08 27", "source": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, "context_summary": { "capability": "distribution.ecdf", "grammar": "distribution.ecdf", "metrics": "Units", "dimensions": null, "periods": "~Aug-2016, ~Aug-2017", "trace_widths": null, "source_reference": "ecdf_small_multiples" }, "original_artifact_contract": { "capability_id": "distribution.ecdf", "status": "context_only", "when_to_use": "distribution.ecdf", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "ecdf", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "distribution / histogram", "capability_id": "distribution.histogram", "plugin_source": "distribution-analysis", "artifact_type": "html", "source": "../distribution/distribution/histogram.html", "output": "distribution__histogram.png", "sidecars": [ { "label": "source", "href": "../distribution/distribution/histogram.html" }, { "label": "context", "href": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, { "label": "data", "href": "../distribution/distribution/distribution_summary.csv" }, { "label": "manifest", "href": "../distribution/distribution/source_pack/manifest.json" }, { "label": "recipe", "href": "../distribution/distribution/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Stripplot Small Multiples of Units by Company", "~Aug 2017 vs ~Aug 2016, through 2017 08 27" ], "who": "Mexico hair color", "what": "Stripplot Small Multiples of Units by Company", "when": "~Aug 2017 vs ~Aug 2016, through 2017 08 27", "source": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, "context_summary": { "capability": "distribution.histogram", "grammar": "distribution.histogram", "metrics": "Units", "dimensions": null, "periods": "~Aug-2016, ~Aug-2017", "trace_widths": null, "source_reference": "histogram" }, "original_artifact_contract": { "capability_id": "distribution.histogram", "status": "context_only", "when_to_use": "distribution.histogram", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "histogram", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "distribution / histogram_small_multiples", "capability_id": "distribution.histogram", "plugin_source": "distribution-analysis", "artifact_type": "html", "source": "../distribution/distribution/histogram_small_multiples.html", "output": "distribution__histogram_small_multiples.png", "sidecars": [ { "label": "source", "href": "../distribution/distribution/histogram_small_multiples.html" }, { "label": "context", "href": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, { "label": "data", "href": "../distribution/distribution/distribution_summary.csv" }, { "label": "manifest", "href": "../distribution/distribution/source_pack/manifest.json" }, { "label": "recipe", "href": "../distribution/distribution/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Stripplot Small Multiples of Units by Company", "~Aug 2017 vs ~Aug 2016, through 2017 08 27" ], "who": "Mexico hair color", "what": "Stripplot Small Multiples of Units by Company", "when": "~Aug 2017 vs ~Aug 2016, through 2017 08 27", "source": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, "context_summary": { "capability": "distribution.histogram", "grammar": "distribution.histogram", "metrics": "Units", "dimensions": null, "periods": "~Aug-2016, ~Aug-2017", "trace_widths": null, "source_reference": "histogram_small_multiple..." }, "original_artifact_contract": { "capability_id": "distribution.histogram", "status": "context_only", "when_to_use": "distribution.histogram", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "histogram", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "distribution / kernel_density", "capability_id": "distribution.kernel_density", "plugin_source": "distribution-analysis", "artifact_type": "html", "source": "../distribution/distribution/kernel_density.html", "output": "distribution__kernel_density.png", "sidecars": [ { "label": "source", "href": "../distribution/distribution/kernel_density.html" }, { "label": "context", "href": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, { "label": "data", "href": "../distribution/distribution/distribution_summary.csv" }, { "label": "manifest", "href": "../distribution/distribution/source_pack/manifest.json" }, { "label": "recipe", "href": "../distribution/distribution/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Stripplot Small Multiples of Units by Company", "~Aug 2017 vs ~Aug 2016, through 2017 08 27" ], "who": "Mexico hair color", "what": "Stripplot Small Multiples of Units by Company", "when": "~Aug 2017 vs ~Aug 2016, through 2017 08 27", "source": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, "context_summary": { "capability": "distribution.kernel_density", "grammar": "distribution.kernel_density", "metrics": "Units", "dimensions": null, "periods": "~Aug-2016, ~Aug-2017", "trace_widths": null, "source_reference": "kernel_density" }, "original_artifact_contract": { "capability_id": "distribution.kernel_density", "status": "context_only", "when_to_use": "distribution.kernel_density", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "density", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "distribution / kernel_density_small_multiples", "capability_id": "distribution.kernel_density", "plugin_source": "distribution-analysis", "artifact_type": "html", "source": "../distribution/distribution/kernel_density_small_multiples.html", "output": "distribution__kernel_density_small_multiples.png", "sidecars": [ { "label": "source", "href": "../distribution/distribution/kernel_density_small_multiples.html" }, { "label": "context", "href": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, { "label": "data", "href": "../distribution/distribution/distribution_summary.csv" }, { "label": "manifest", "href": "../distribution/distribution/source_pack/manifest.json" }, { "label": "recipe", "href": "../distribution/distribution/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Stripplot Small Multiples of Units by Company", "~Aug 2017 vs ~Aug 2016, through 2017 08 27" ], "who": "Mexico hair color", "what": "Stripplot Small Multiples of Units by Company", "when": "~Aug 2017 vs ~Aug 2016, through 2017 08 27", "source": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, "context_summary": { "capability": "distribution.kernel_density", "grammar": "distribution.kernel_density", "metrics": "Units", "dimensions": null, "periods": "~Aug-2016, ~Aug-2017", "trace_widths": null, "source_reference": "kernel_density_small_mul..." }, "original_artifact_contract": { "capability_id": "distribution.kernel_density", "status": "context_only", "when_to_use": "distribution.kernel_density", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "density", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "distribution / stripplot", "capability_id": "distribution.stripplot", "plugin_source": "distribution-analysis", "artifact_type": "html", "source": "../distribution/distribution/stripplot.html", "output": "distribution__stripplot.png", "sidecars": [ { "label": "source", "href": "../distribution/distribution/stripplot.html" }, { "label": "context", "href": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, { "label": "data", "href": "../distribution/distribution/distribution_summary.csv" }, { "label": "manifest", "href": "../distribution/distribution/source_pack/manifest.json" }, { "label": "recipe", "href": "../distribution/distribution/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Stripplot Small Multiples of Units by Company", "~Aug 2017 vs ~Aug 2016, through 2017 08 27" ], "who": "Mexico hair color", "what": "Stripplot Small Multiples of Units by Company", "when": "~Aug 2017 vs ~Aug 2016, through 2017 08 27", "source": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, "context_summary": { "capability": "distribution.stripplot", "grammar": "distribution.stripplot", "metrics": "Units", "dimensions": null, "periods": "~Aug-2016, ~Aug-2017", "trace_widths": null, "source_reference": "stripplot" }, "original_artifact_contract": { "capability_id": "distribution.stripplot", "status": "context_only", "when_to_use": "distribution.stripplot", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "stripplot", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "distribution / stripplot_small_multiples", "capability_id": "distribution.stripplot", "plugin_source": "distribution-analysis", "artifact_type": "html", "source": "../distribution/distribution/stripplot_small_multiples.html", "output": "distribution__stripplot_small_multiples.png", "sidecars": [ { "label": "source", "href": "../distribution/distribution/stripplot_small_multiples.html" }, { "label": "context", "href": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, { "label": "data", "href": "../distribution/distribution/distribution_summary.csv" }, { "label": "manifest", "href": "../distribution/distribution/source_pack/manifest.json" }, { "label": "recipe", "href": "../distribution/distribution/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Stripplot Small Multiples of Units by Company", "~Aug 2017 vs ~Aug 2016, through 2017 08 27" ], "who": "Mexico hair color", "what": "Stripplot Small Multiples of Units by Company", "when": "~Aug 2017 vs ~Aug 2016, through 2017 08 27", "source": "../distribution/distribution/source_pack/contexts/distribution_context.json" }, "context_summary": { "capability": "distribution.stripplot", "grammar": "distribution.stripplot", "metrics": "Units", "dimensions": null, "periods": "~Aug-2016, ~Aug-2017", "trace_widths": null, "source_reference": "stripplot_small_multiple..." }, "original_artifact_contract": { "capability_id": "distribution.stripplot", "status": "context_only", "when_to_use": "distribution.stripplot", "required_parameters": [ "source_file", "metric" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "stripplot", "selector_level": "rendering_variant_choice", "variant_changes_capability_selection": false, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "set_overlap / set_overlap_small_multiples / upset_small_multiples", "capability_id": "set_overlap.upset_small_multiples", "plugin_source": "set-overlap-analysis", "artifact_type": "html", "source": "../set_overlap/set_overlap_small_multiples/upset_small_multiples.html", "output": "set_overlap__set_overlap_small_multiples__upset_small_multiples.png", "sidecars": [ { "label": "source", "href": "../set_overlap/set_overlap_small_multiples/upset_small_multiples.html" }, { "label": "context", "href": "../set_overlap/set_overlap_small_multiples/set_overlap_context.json" }, { "label": "data", "href": "../set_overlap/set_overlap_small_multiples/set_overlap_set_summary.csv" }, { "label": "manifest", "href": "../set_overlap/set_overlap_small_multiples/source_pack/manifest.json" }, { "label": "recipe", "href": "../set_overlap/set_overlap_small_multiples/used_recipe.json" } ], "title_context": { "lines": [ "Category market overlap", "UpSet small multiples: Product_Id overlap by Market", "All" ], "who": "Category market overlap", "what": "UpSet small multiples: Product_Id overlap by Market", "when": "All", "source": "../set_overlap/set_overlap_small_multiples/upset_small_multiples.html" }, "context_summary": { "capability": null, "grammar": null, "metrics": null, "dimensions": null, "periods": null, "trace_widths": null, "source_reference": null }, "original_artifact_contract": { "capability_id": "set_overlap.upset_small_multiples", "status": "context_only", "when_to_use": "set_overlap", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "small_multiples", "encoding_variant": "upset", "selector_level": "capability_choice", "variant_changes_capability_selection": true, "adds_parameter_roles": [ "panel_dimension" ], "variant_selection_cues": [ "question asks to split the same chart by a panel dimension" ] } }, { "label": "set_overlap / upset", "capability_id": "set_overlap.upset", "plugin_source": "set-overlap-analysis", "artifact_type": "html", "source": "../set_overlap/set_overlap/upset.html", "output": "set_overlap__upset.png", "sidecars": [ { "label": "source", "href": "../set_overlap/set_overlap/upset.html" }, { "label": "context", "href": "../set_overlap/set_overlap/set_overlap_context.json" }, { "label": "data", "href": "../set_overlap/set_overlap/set_overlap_set_summary.csv" }, { "label": "manifest", "href": "../set_overlap/set_overlap/source_pack/manifest.json" }, { "label": "recipe", "href": "../set_overlap/set_overlap/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Venn membership overlap", "Current reporting view" ], "who": "Mexico hair color", "what": "Venn membership overlap", "when": "Current reporting view", "source": "../set_overlap/set_overlap/set_overlap_context.json" }, "context_summary": { "capability": null, "grammar": null, "metrics": null, "dimensions": null, "periods": null, "trace_widths": null, "source_reference": null }, "original_artifact_contract": { "capability_id": "set_overlap.upset", "status": "context_only", "when_to_use": "set_overlap", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "chart_html", "layout_variant": "single", "encoding_variant": "upset", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "set_overlap / venn", "capability_id": "set_overlap.venn", "plugin_source": "set-overlap-analysis", "artifact_type": "png", "source": "../set_overlap/set_overlap/venn.png", "output": "set_overlap__venn.png", "sidecars": [ { "label": "source", "href": "../set_overlap/set_overlap/venn.png" }, { "label": "context", "href": "../set_overlap/set_overlap/set_overlap_context.json" }, { "label": "data", "href": "../set_overlap/set_overlap/set_overlap_set_summary.csv" }, { "label": "manifest", "href": "../set_overlap/set_overlap/source_pack/manifest.json" }, { "label": "recipe", "href": "../set_overlap/set_overlap/used_recipe.json" } ], "title_context": { "lines": [ "Mexico hair color", "Venn membership overlap", "Current reporting view" ], "who": "Mexico hair color", "what": "Venn membership overlap", "when": "Current reporting view", "source": "../set_overlap/set_overlap/set_overlap_context.json" }, "context_summary": { "capability": null, "grammar": null, "metrics": null, "dimensions": null, "periods": null, "trace_widths": null, "source_reference": null }, "original_artifact_contract": { "capability_id": "set_overlap.venn", "status": "context_only", "when_to_use": "set_overlap", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "png", "formats": [ "png" ] } ] }, "rendering_variant": { "output_form": "chart_png", "layout_variant": "single", "encoding_variant": "venn", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "default single-view rendering for the selected capability" ] } }, { "label": "funnel / funnel_stage_table", "capability_id": "funnel.stage_table", "plugin_source": "funnel-analysis", "artifact_type": "table", "source": "../funnel/funnel/funnel_stage_table.html", "output": "funnel__funnel_stage_table.png", "sidecars": [ { "label": "source", "href": "../funnel/funnel/funnel_stage_table.html" }, { "label": "context", "href": "../funnel/funnel/funnel_stage_table_chart_context.json" }, { "label": "data", "href": "../funnel/funnel/funnel_stage_table_chart_data.csv" }, { "label": "manifest", "href": "../funnel/funnel/source_pack/manifest.json" }, { "label": "recipe", "href": "../funnel/funnel/used_recipe.json" } ], "title_context": { "lines": [ "Baby CRM extract", "Lead readiness funnel in records", "Sequential gates" ], "who": "Baby CRM extract", "what": "Lead readiness funnel in records", "when": "Sequential gates", "source": "../funnel/funnel/funnel_stage_table_chart_context.json" }, "context_summary": { "capability": "funnel.stage_table", "grammar": "funnel.stage_table", "metrics": "Lead readiness funnel", "dimensions": null, "periods": null, "trace_widths": null, "source_reference": "funnel_stage_table" }, "original_artifact_contract": { "capability_id": "funnel.stage_table", "status": "context_only", "when_to_use": "funnel_stage_table", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "table_html", "layout_variant": "table", "encoding_variant": "table", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "table output for exact values or evidence rows", "default single-view rendering for the selected capability" ] } }, { "label": "statement / pnl_statement_table", "capability_id": "statement.pnl_table", "plugin_source": "statement-analysis", "artifact_type": "table", "source": "../statement/statement/pnl_statement_table.html", "output": "statement__pnl_statement_table.png", "sidecars": [ { "label": "source", "href": "../statement/statement/pnl_statement_table.html" }, { "label": "context", "href": "../statement/statement/pnl_statement_table_chart_context.json" }, { "label": "data", "href": "../statement/statement/pnl_statement_table_chart_data.csv" }, { "label": "manifest", "href": "../statement/statement/source_pack/manifest.json" }, { "label": "recipe", "href": "../statement/statement/used_recipe.json" } ], "title_context": { "lines": [ "SoftCons International Inc.", "Profit and loss statement in mUSD", "2012..2015 PL and AC (FC)" ], "who": "SoftCons International Inc.", "what": "Profit and loss statement in mUSD", "when": "2012..2015 PL and AC (FC)", "source": "../statement/statement/pnl_statement_table_chart_context.json" }, "context_summary": { "capability": "statement.pnl_table", "grammar": "statement.pnl_table", "metrics": null, "dimensions": null, "periods": null, "trace_widths": null, "source_reference": "pnl_statement_table" }, "original_artifact_contract": { "capability_id": "statement.pnl_table", "status": "context_only", "when_to_use": "pnl_statement_table", "required_parameters": [ "source_file" ], "optional_parameters": [], "outputs": [ { "artifact_type": "html", "formats": [ "html" ] } ] }, "rendering_variant": { "output_form": "table_html", "layout_variant": "table", "encoding_variant": "table", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "table output for exact values or evidence rows", "default single-view rendering for the selected capability" ] } }, { "label": "attributes / attribute_bridge_table", "capability_id": "attributes.attribute_bridge_table", "plugin_source": "attribute-tables", "artifact_type": "table", "source": "../attributes/attributes/attribute_bridge_table.html", "output": "attributes__attribute_bridge_table.png", "sidecars": [ { "label": "source", "href": "../attributes/attributes/attribute_bridge_table.html" }, { "label": "context", "href": "../attributes/attributes/attribute_bridge_table_chart_context.json" }, { "label": "data", "href": "../attributes/attributes/attribute_bridge_table_chart_data.csv" }, { "label": "manifest", "href": "../attributes/attributes/source_pack/manifest.json" }, { "label": "recipe", "href": "../attributes/attributes/attribute_table_catalog.json" } ], "title_context": { "lines": [ "Attribute evidence", "Attribute Bridge Table", "Current reporting view" ], "who": "Attribute evidence", "what": "Attribute Bridge Table", "when": "Current reporting view", "source": "../attributes/attributes/attribute_bridge_table_chart_context.json" }, "context_summary": { "capability": "attributes.attribute_bridge_table", "grammar": "attribute_bridge_table", "metrics": "current_n, current_share, current_delta +5", "dimensions": "signal_bundle, alignment", "periods": null, "trace_widths": null, "source_reference": "attribute_bridge_table" }, "original_artifact_contract": { "capability_id": "attributes.attribute_bridge_table", "plugin": "attribute-tables", "catalog_path": "modules/pdp/attribute_table_catalog.json", "status": "available", "when_to_use": "Use when the report needs to compare current winners with emerging signals and explicitly show alignment, divergence, or one-sided support.", "required_parameters": [ "package_dir" ], "optional_parameters": [ "output_dir", "table_keys" ], "outputs": [ { "artifact_type": "table", "formats": [ "csv", "html" ] }, { "artifact_type": "manifest", "formats": [ "json" ] } ], "execution_contract": { "entry_point": "modules.pdp.attribute_table_templates.build_attribute_tables_from_package", "cli": "scripts/build_attribute_table_artifacts.py", "required_parameters": [ "package_dir" ], "optional_parameters": [ "output_dir", "table_keys" ], "deterministic_boundary": "The table builder reads package CSVs, selects rows, formats values, writes CSV/HTML artifacts, and returns a manifest. The model chooses the table and interprets the rows, but does not compute or render the table." }, "object_type": "table" }, "rendering_variant": { "output_form": "table_html", "layout_variant": "table", "encoding_variant": "table", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "table output for exact values or evidence rows", "default single-view rendering for the selected capability" ] } }, { "label": "attributes / attribute_bundle_comparison_table", "capability_id": "attributes.attribute_bundle_comparison_table", "plugin_source": "attribute-tables", "artifact_type": "table", "source": "../attributes/attributes/attribute_bundle_comparison_table.html", "output": "attributes__attribute_bundle_comparison_table.png", "sidecars": [ { "label": "source", "href": "../attributes/attributes/attribute_bundle_comparison_table.html" }, { "label": "context", "href": "../attributes/attributes/attribute_bundle_comparison_table_chart_context.json" }, { "label": "data", "href": "../attributes/attributes/attribute_bundle_comparison_table_chart_data.csv" }, { "label": "manifest", "href": "../attributes/attributes/source_pack/manifest.json" }, { "label": "recipe", "href": "../attributes/attributes/attribute_table_catalog.json" } ], "title_context": { "lines": [ "Attribute evidence", "Attribute Bundle Comparison Table", "Current reporting view" ], "who": "Attribute evidence", "what": "Attribute Bundle Comparison Table", "when": "Current reporting view", "source": "../attributes/attributes/attribute_bundle_comparison_table_chart_context.json" }, "context_summary": { "capability": "attributes.attribute_bundle_comparison_table", "grammar": "attribute_bundle_comparison_table", "metrics": "focus_n, baseline_n, focus_share +4", "dimensions": "layer, comparison, signal_bundle", "periods": null, "trace_widths": null, "source_reference": "attribute_bundle_compari..." }, "original_artifact_contract": { "capability_id": "attributes.attribute_bundle_comparison_table", "plugin": "attribute-tables", "catalog_path": "modules/pdp/attribute_table_catalog.json", "status": "available", "when_to_use": "Use when the report needs exact bundle support for winning-now or emerging-signal rows, including focus/baseline counts, shares, delta, index, and brand breadth.", "required_parameters": [ "package_dir" ], "optional_parameters": [ "output_dir", "table_keys" ], "outputs": [ { "artifact_type": "table", "formats": [ "csv", "html" ] }, { "artifact_type": "manifest", "formats": [ "json" ] } ], "execution_contract": { "entry_point": "modules.pdp.attribute_table_templates.build_attribute_tables_from_package", "cli": "scripts/build_attribute_table_artifacts.py", "required_parameters": [ "package_dir" ], "optional_parameters": [ "output_dir", "table_keys" ], "deterministic_boundary": "The table builder reads package CSVs, selects rows, formats values, writes CSV/HTML artifacts, and returns a manifest. The model chooses the table and interprets the rows, but does not compute or render the table." }, "object_type": "table" }, "rendering_variant": { "output_form": "table_html", "layout_variant": "table", "encoding_variant": "table", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "table output for exact values or evidence rows", "default single-view rendering for the selected capability" ] } }, { "label": "attributes / product_signal_evidence_table", "capability_id": "attributes.product_signal_evidence_table", "plugin_source": "attribute-tables", "artifact_type": "table", "source": "../attributes/attributes/product_signal_evidence_table.html", "output": "attributes__product_signal_evidence_table.png", "sidecars": [ { "label": "source", "href": "../attributes/attributes/product_signal_evidence_table.html" }, { "label": "context", "href": "../attributes/attributes/product_signal_evidence_table_chart_context.json" }, { "label": "data", "href": "../attributes/attributes/product_signal_evidence_table_chart_data.csv" }, { "label": "manifest", "href": "../attributes/attributes/source_pack/manifest.json" }, { "label": "recipe", "href": "../attributes/attributes/attribute_table_catalog.json" } ], "title_context": { "lines": [ "Attribute evidence", "Product Signal Evidence Table", "Current reporting view" ], "who": "Attribute evidence", "what": "Product Signal Evidence Table", "when": "Current reporting view", "source": "../attributes/attributes/product_signal_evidence_table_chart_context.json" }, "context_summary": { "capability": "attributes.product_signal_evidence_table", "grammar": "product_signal_evidence_table", "metrics": "rating, reviews", "dimensions": "cohort, rank, brand +2", "periods": null, "trace_widths": null, "source_reference": "product_signal_evidence_..." }, "original_artifact_contract": { "capability_id": "attributes.product_signal_evidence_table", "plugin": "attribute-tables", "catalog_path": "modules/pdp/attribute_table_catalog.json", "status": "available", "when_to_use": "Use when the report needs product-level grounding for selected bundles, standout examples, or PDP/review reality checks; prefer image cards in the report narrative and this table as compact validation detail.", "required_parameters": [ "package_dir" ], "optional_parameters": [ "output_dir", "table_keys" ], "outputs": [ { "artifact_type": "table", "formats": [ "csv", "html" ] }, { "artifact_type": "manifest", "formats": [ "json" ] } ], "execution_contract": { "entry_point": "modules.pdp.attribute_table_templates.build_attribute_tables_from_package", "cli": "scripts/build_attribute_table_artifacts.py", "required_parameters": [ "package_dir" ], "optional_parameters": [ "output_dir", "table_keys" ], "deterministic_boundary": "The table builder reads package CSVs, selects rows, formats values, writes CSV/HTML artifacts, and returns a manifest. The model chooses the table and interprets the rows, but does not compute or render the table." }, "object_type": "table" }, "rendering_variant": { "output_form": "table_html", "layout_variant": "table", "encoding_variant": "table", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "table output for exact values or evidence rows", "default single-view rendering for the selected capability" ] } }, { "label": "attributes / rank_weighted_visibility_table", "capability_id": "attributes.rank_weighted_visibility_table", "plugin_source": "attribute-tables", "artifact_type": "table", "source": "../attributes/attributes/rank_weighted_visibility_table.html", "output": "attributes__rank_weighted_visibility_table.png", "sidecars": [ { "label": "source", "href": "../attributes/attributes/rank_weighted_visibility_table.html" }, { "label": "context", "href": "../attributes/attributes/rank_weighted_visibility_table_chart_context.json" }, { "label": "data", "href": "../attributes/attributes/rank_weighted_visibility_table_chart_data.csv" }, { "label": "manifest", "href": "../attributes/attributes/source_pack/manifest.json" }, { "label": "recipe", "href": "../attributes/attributes/attribute_table_catalog.json" } ], "title_context": { "lines": [ "Attribute evidence", "Rank Weighted Visibility Table", "Current reporting view" ], "who": "Attribute evidence", "what": "Rank Weighted Visibility Table", "when": "Current reporting view", "source": "../attributes/attributes/rank_weighted_visibility_table_chart_context.json" }, "context_summary": { "capability": "attributes.rank_weighted_visibility_table", "grammar": "rank_weighted_visibility_table", "metrics": "gross_weight, incremental, cumulative +3", "dimensions": "rank, lane", "periods": null, "trace_widths": null, "source_reference": "rank_weighted_visibility..." }, "original_artifact_contract": { "capability_id": "attributes.rank_weighted_visibility_table", "plugin": "attribute-tables", "catalog_path": "modules/pdp/attribute_table_catalog.json", "status": "available", "when_to_use": "Use when the report needs to ground claims about rank-weighted shelf visibility, incremental lane contribution, or robustness across alpha assumptions.", "required_parameters": [ "package_dir" ], "optional_parameters": [ "output_dir", "table_keys" ], "outputs": [ { "artifact_type": "table", "formats": [ "csv", "html" ] }, { "artifact_type": "manifest", "formats": [ "json" ] } ], "execution_contract": { "entry_point": "modules.pdp.attribute_table_templates.build_attribute_tables_from_package", "cli": "scripts/build_attribute_table_artifacts.py", "required_parameters": [ "package_dir" ], "optional_parameters": [ "output_dir", "table_keys" ], "deterministic_boundary": "The table builder reads package CSVs, selects rows, formats values, writes CSV/HTML artifacts, and returns a manifest. The model chooses the table and interprets the rows, but does not compute or render the table." }, "object_type": "table" }, "rendering_variant": { "output_form": "table_html", "layout_variant": "table", "encoding_variant": "table", "selector_level": "base_capability", "variant_changes_capability_selection": false, "adds_parameter_roles": [], "variant_selection_cues": [ "table output for exact values or evidence rows", "default single-view rendering for the selected capability" ] } } ], "role_registry": { "schema_version": "0.1", "purpose": "Canonical mechanical role vocabulary for chart selection. These roles constrain dataset/profile and plugin-parameter matching; they do not decide analysis validity.", "chart_roles": { "area_metric": { "role": "area_metric", "kinds": [ "metric" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.amount_column" ] } ], "used_by_capabilities": [ "mix.barmekko" ], "used_by_artifacts": [], "registry_status": "defined" }, "attribute_bundle": { "role": "attribute_bundle", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "package_contract", "parameters": [ "package_dir" ] } ], "used_by_capabilities": [ "attributes.attribute_bundle_comparison_table" ], "used_by_artifacts": [], "registry_status": "defined" }, "bridge_component_period": { "role": "bridge_component_period", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "derived_from_period", "role": "period_axis" } ], "used_by_capabilities": [ "period_comparison.horizontal_waterfall" ], "used_by_artifacts": [], "registry_status": "defined" }, "category": { "role": "category", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "collection", "paths": [ "mappings.dimensions" ] } ], "used_by_capabilities": [ "mix.bar", "mix.pareto", "mix.stacked_bar", "mix.stacked_bar_overlay", "mix.stacked_pareto" ], "used_by_artifacts": [], "registry_status": "defined" }, "child_driver": { "role": "child_driver", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "options.exploded_variance_bridge_child_dimension" ] } ], "used_by_capabilities": [ "variance.exploded_variance_bridge" ], "used_by_artifacts": [], "registry_status": "defined" }, "cohort_layer": { "role": "cohort_layer", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "package_contract", "parameters": [ "package_dir" ] } ], "used_by_capabilities": [ "attributes.attribute_bridge_table" ], "used_by_artifacts": [], "registry_status": "defined" }, "comparison_item": { "role": "comparison_item", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "collection", "paths": [ "mappings.dimensions" ] } ], "used_by_capabilities": [ "period_comparison.dot", "period_comparison.slope" ], "used_by_artifacts": [], "registry_status": "defined" }, "comparison_metric": { "role": "comparison_metric", "kinds": [ "metric" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.amount_column" ] }, { "kind": "explicit", "paths": [ "mappings.metric_column" ] }, { "kind": "contract", "parameters": [ "metric" ] } ], "used_by_capabilities": [ "mix.multitier_bar", "period_comparison.by_period", "period_comparison.comparison_table", "period_comparison.dot", "period_comparison.horizontal_waterfall", "period_comparison.multitier_column", "period_comparison.slope", "period_comparison.time_series_table", "period_comparison.trend" ], "used_by_artifacts": [], "registry_status": "defined" }, "comparison_series": { "role": "comparison_series", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "derived_from_period", "role": "period_axis" } ], "used_by_capabilities": [ "period_comparison.by_period", "period_comparison.multitier_column", "period_comparison.trend" ], "used_by_artifacts": [], "registry_status": "defined" }, "comparison_window": { "role": "comparison_window", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "derived_from_period", "role": "period_filter" } ], "used_by_capabilities": [ "period_comparison.comparison_table" ], "used_by_artifacts": [], "registry_status": "defined" }, "component_category": { "role": "component_category", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "collection", "paths": [ "mappings.dimensions" ] } ], "used_by_capabilities": [ "mix.stacked_bar" ], "used_by_artifacts": [], "registry_status": "defined" }, "component_dimension": { "role": "component_dimension", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "collection", "paths": [ "mappings.dimensions" ] } ], "used_by_capabilities": [ "mix.like_for_like_stacked_column", "mix.stacked_column", "mix.stacked_pareto" ], "used_by_artifacts": [], "registry_status": "defined" }, "component_root_cause_driver_sequence": { "role": "component_root_cause_driver_sequence", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "collection", "paths": [ "mappings.dimensions" ] } ], "used_by_capabilities": [ "variance.root_cause_component_bridge" ], "used_by_artifacts": [], "registry_status": "defined" }, "dimension_member": { "role": "dimension_member", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "options.total_by_dimension_bridge_dimension" ] }, { "kind": "collection", "paths": [ "mappings.dimensions" ] }, { "kind": "contract", "parameters": [ "dimension", "dimensions" ] } ], "used_by_capabilities": [ "mix.multitier_bar", "variance.total_by_dimension_bridge" ], "used_by_artifacts": [], "registry_status": "defined" }, "distribution_metric": { "role": "distribution_metric", "kinds": [ "metric" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.metric_column" ] }, { "kind": "contract", "parameters": [ "metric" ] } ], "used_by_capabilities": [ "distribution.boxplot", "distribution.ecdf", "distribution.histogram", "distribution.kernel_density", "distribution.stripplot" ], "used_by_artifacts": [], "registry_status": "defined" }, "drilldown_selection": { "role": "drilldown_selection", "kinds": [ "dimension", "variant" ], "parameter_candidates": [ { "kind": "compound", "paths": [ "options.root_cause_bridge_alternative_result", "options.root_cause_bridge_drilldown_rows" ] }, { "kind": "explicit", "paths": [ "options.exploded_variance_bridge_max_drilldowns" ] } ], "used_by_capabilities": [ "variance.root_cause_exploded_bridge" ], "used_by_artifacts": [ "variance / exploded_variance_bridge", "variance / root_cause_exploded_bridge" ], "registry_status": "defined" }, "first_active_cohort": { "role": "first_active_cohort", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "compound", "paths": [ "mappings.period_column", "mappings.dimensions", "options.period_selection", "options.derived_dimensions" ] } ], "used_by_capabilities": [ "mix.cohort_since_stacked_column" ], "used_by_artifacts": [], "registry_status": "defined" }, "height_category": { "role": "height_category", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "collection", "paths": [ "mappings.dimensions" ] } ], "used_by_capabilities": [ "mix.barmekko" ], "used_by_artifacts": [], "registry_status": "defined" }, "height_metric": { "role": "height_metric", "kinds": [], "parameter_candidates": [ { "kind": "compound", "paths": [ "mappings.amount_column", "mappings.width_metric_column" ] } ], "used_by_capabilities": [], "used_by_artifacts": [], "registry_status": "defined" }, "lost_or_last_active_cohort": { "role": "lost_or_last_active_cohort", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "compound", "paths": [ "mappings.period_column", "mappings.dimensions", "options.period_selection", "options.derived_dimensions" ] } ], "used_by_capabilities": [ "mix.cohort_lost_stacked_column" ], "used_by_artifacts": [], "registry_status": "defined" }, "optional_component_dimension": { "role": "optional_component_dimension", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "collection", "paths": [ "mappings.dimensions" ] } ], "used_by_capabilities": [ "mix.area" ], "used_by_artifacts": [], "registry_status": "defined" }, "optional_drilldown_selection": { "role": "optional_drilldown_selection", "kinds": [], "parameter_candidates": [ { "kind": "compound", "paths": [ "options.root_cause_bridge_alternative_result", "options.root_cause_bridge_drilldown_rows" ] } ], "used_by_capabilities": [], "used_by_artifacts": [], "registry_status": "defined" }, "optional_panel": { "role": "optional_panel", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.small_multiples_dimension" ] }, { "kind": "explicit", "paths": [ "options.small_multiples_dimension" ] }, { "kind": "explicit", "paths": [ "options.waterfall_small_multiples_dimension" ] } ], "used_by_capabilities": [ "mix.marimekko", "mix.multitier_bar", "scatter.bubble", "scatter.scatter" ], "used_by_artifacts": [], "registry_status": "defined" }, "ordered_stage": { "role": "ordered_stage", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "stage_table_mappings.stage_column" ] } ], "used_by_capabilities": [ "funnel.stage_table" ], "used_by_artifacts": [], "registry_status": "defined" }, "panel_dimension": { "role": "panel_dimension", "kinds": [ "variant" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.small_multiples_dimension" ] }, { "kind": "explicit", "paths": [ "options.small_multiples_dimension" ] }, { "kind": "explicit", "paths": [ "options.waterfall_small_multiples_dimension" ] } ], "used_by_capabilities": [], "used_by_artifacts": [ "distribution / boxplot_small_multiples", "distribution / ecdf_small_multiples", "distribution / histogram_small_multiples", "distribution / kernel_density_small_multiples", "distribution / stripplot_small_multiples", "mix_comparison / bar_small_multiples", "mix_comparison / line_small_multiples", "mix_comparison / mix_regular / stacked_column_small_multiples", "mix_comparison / multitier_bar_dimension_panels", "mix_comparison / multitier_bar_two_dimension", "mix_comparison / related_metrics_bar_small_multiples", "mix_current / barmekko_small_multiples", "mix_current / marimekko_small_multiples", "mix_current / stacked_bar_small_multiples", "period / year_over_year_by_recency_window_small_multiples", "period / year_over_year_column_small_multiples", "period / year_over_year_dot_small_multiples", "period / year_over_year_slope_small_multiples", "period / year_over_year_small_multiples", "period / year_over_year_waterfall_small_multiples", "scatter / scatter_bubble / bubble_small_multiples", "scatter / scatter_bubble / scatter_small_multiples", "set_overlap / set_overlap_small_multiples / upset_small_multiples", "variance / waterfall_small_multiples" ], "registry_status": "defined" }, "panel_or_segment": { "role": "panel_or_segment", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.small_multiples_dimension" ] }, { "kind": "collection", "paths": [ "mappings.dimensions" ] } ], "used_by_capabilities": [ "set_overlap.upset_small_multiples" ], "used_by_artifacts": [], "registry_status": "defined" }, "parent_driver": { "role": "parent_driver", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "options.exploded_variance_bridge_parent_dimension" ] } ], "used_by_capabilities": [ "variance.exploded_variance_bridge" ], "used_by_artifacts": [], "registry_status": "defined" }, "period_axis": { "role": "period_axis", "kinds": [ "period" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.date_column" ] }, { "kind": "explicit", "paths": [ "mappings.period_column" ] }, { "kind": "explicit", "paths": [ "options.period_window" ] }, { "kind": "explicit", "paths": [ "periods" ] } ], "used_by_capabilities": [ "mix.area", "mix.cohort_lost_stacked_column", "mix.cohort_since_stacked_column", "mix.column", "mix.column_overlay", "mix.like_for_like_column", "mix.like_for_like_stacked_column", "mix.multitier_bar", "mix.stacked_column", "mix.timeline", "period_comparison.by_period", "period_comparison.dot", "period_comparison.horizontal_waterfall", "period_comparison.multitier_column", "period_comparison.slope", "period_comparison.time_series_table", "period_comparison.trend", "statement.pnl_table" ], "used_by_artifacts": [], "registry_status": "defined" }, "period_filter": { "role": "period_filter", "kinds": [ "period" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.period_column" ] }, { "kind": "explicit", "paths": [ "mappings.date_column" ] }, { "kind": "explicit", "paths": [ "mappings.baseline_period" ] }, { "kind": "explicit", "paths": [ "mappings.comparison_period" ] }, { "kind": "explicit", "paths": [ "options.selected_period" ] }, { "kind": "explicit", "paths": [ "options.selected_periods" ] }, { "kind": "explicit", "paths": [ "options.period_window" ] }, { "kind": "explicit", "paths": [ "periods" ] } ], "used_by_capabilities": [ "distribution.boxplot", "distribution.ecdf", "distribution.histogram", "distribution.kernel_density", "distribution.stripplot", "mix.bar", "mix.barmekko", "mix.marimekko", "mix.pareto", "mix.stacked_bar", "mix.stacked_bar_overlay", "mix.stacked_pareto", "period_comparison.comparison_table", "scatter.bubble", "scatter.scatter", "set_overlap.upset", "set_overlap.upset_small_multiples", "set_overlap.venn", "variance.exploded_variance_bridge", "variance.price_volume_mix", "variance.root_cause_component_bridge", "variance.root_cause_exploded_bridge", "variance.root_cause_total_bridge", "variance.scenario_bridge", "variance.total_by_dimension_bridge" ], "used_by_artifacts": [], "registry_status": "defined" }, "period_or_scenario_pair": { "role": "period_or_scenario_pair", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "derived_from_period", "role": "period_filter" } ], "used_by_capabilities": [ "variance.price_volume_mix" ], "used_by_artifacts": [], "registry_status": "defined" }, "point_dimension": { "role": "point_dimension", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.dot_dimension" ] } ], "used_by_capabilities": [ "scatter.bubble", "scatter.scatter" ], "used_by_artifacts": [], "registry_status": "defined" }, "price_or_rate_metric": { "role": "price_or_rate_metric", "kinds": [], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.price_column" ] }, { "kind": "explicit", "paths": [ "mappings.rate_column" ] }, { "kind": "explicit", "paths": [ "mappings.price_or_rate_metric_column" ] }, { "kind": "compound", "paths": [ "mappings.amount_column", "mappings.units_column" ] } ], "used_by_capabilities": [], "used_by_artifacts": [], "registry_status": "defined" }, "primary_additive_metric": { "role": "primary_additive_metric", "kinds": [], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.amount_column" ] }, { "kind": "explicit", "paths": [ "mappings.source_amount_column" ] }, { "kind": "contract", "parameters": [ "metric" ] } ], "used_by_capabilities": [], "used_by_artifacts": [], "registry_status": "defined" }, "primary_metric": { "role": "primary_metric", "kinds": [ "metric" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.amount_column" ] }, { "kind": "explicit", "paths": [ "mappings.metric_column" ] }, { "kind": "explicit", "paths": [ "mappings.source_amount_column" ] }, { "kind": "contract", "parameters": [ "metric" ] } ], "used_by_capabilities": [ "mix.area", "mix.bar", "mix.cohort_lost_stacked_column", "mix.cohort_since_stacked_column", "mix.column", "mix.column_overlay", "mix.like_for_like_column", "mix.like_for_like_stacked_column", "mix.marimekko", "mix.pareto", "mix.stacked_bar", "mix.stacked_bar_overlay", "mix.stacked_column", "mix.stacked_pareto", "mix.timeline" ], "used_by_artifacts": [], "registry_status": "defined" }, "product": { "role": "product", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "package_contract", "parameters": [ "package_dir" ] } ], "used_by_capabilities": [ "attributes.product_signal_evidence_table" ], "used_by_artifacts": [], "registry_status": "defined" }, "rank_or_lane": { "role": "rank_or_lane", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "package_contract", "parameters": [ "package_dir" ] } ], "used_by_capabilities": [ "attributes.rank_weighted_visibility_table" ], "used_by_artifacts": [], "registry_status": "defined" }, "related_marker_metric": { "role": "related_marker_metric", "kinds": [ "metric", "variant" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.related_marker_metric_column" ] }, { "kind": "explicit", "paths": [ "mappings.margin_percent_column" ] }, { "kind": "explicit", "paths": [ "mappings.margin_column" ] }, { "kind": "compound", "paths": [ "mappings.amount_column", "options.period_selection" ] }, { "kind": "contract", "parameters": [ "related_marker_metric" ] } ], "used_by_capabilities": [ "mix.column_overlay", "mix.stacked_bar_overlay" ], "used_by_artifacts": [ "mix_comparison / mix_comparison_column_total / column_total_with_overlay", "mix_comparison / related_metrics_bar", "mix_comparison / related_metrics_bar_small_multiples" ], "registry_status": "defined" }, "root_cause_driver_sequence": { "role": "root_cause_driver_sequence", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "collection", "paths": [ "mappings.dimensions" ] } ], "used_by_capabilities": [ "variance.root_cause_exploded_bridge", "variance.root_cause_total_bridge" ], "used_by_artifacts": [], "registry_status": "defined" }, "set_membership_fields": { "role": "set_membership_fields", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "compound", "paths": [ "mappings.item_column", "mappings.set_column" ] } ], "used_by_capabilities": [ "set_overlap.upset", "set_overlap.upset_small_multiples" ], "used_by_artifacts": [], "registry_status": "defined" }, "signal_bundle": { "role": "signal_bundle", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "package_contract", "parameters": [ "package_dir" ] } ], "used_by_capabilities": [ "attributes.attribute_bridge_table", "attributes.product_signal_evidence_table" ], "used_by_artifacts": [], "registry_status": "defined" }, "size_metric": { "role": "size_metric", "kinds": [ "metric" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.bubble_size_metric_column" ] } ], "used_by_capabilities": [ "scatter.bubble" ], "used_by_artifacts": [], "registry_status": "defined" }, "stable_population_flag": { "role": "stable_population_flag", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "compound", "paths": [ "mappings.period_column", "mappings.dimensions", "options.period_selection", "options.like_for_like" ] } ], "used_by_capabilities": [ "mix.like_for_like_column", "mix.like_for_like_stacked_column" ], "used_by_artifacts": [], "registry_status": "defined" }, "stack_category": { "role": "stack_category", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "collection", "paths": [ "mappings.dimensions" ] } ], "used_by_capabilities": [ "mix.marimekko" ], "used_by_artifacts": [], "registry_status": "defined" }, "stage_pass_count": { "role": "stage_pass_count", "kinds": [ "metric" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "stage_table_mappings.pass_count_column" ] } ], "used_by_capabilities": [ "funnel.stage_table" ], "used_by_artifacts": [], "registry_status": "defined" }, "stage_start_count": { "role": "stage_start_count", "kinds": [ "metric" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "stage_table_mappings.start_count_column" ] } ], "used_by_capabilities": [ "funnel.stage_table" ], "used_by_artifacts": [], "registry_status": "defined" }, "statement_line_item": { "role": "statement_line_item", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.row_key_column" ] } ], "used_by_capabilities": [ "statement.pnl_table" ], "used_by_artifacts": [], "registry_status": "defined" }, "statement_scenario": { "role": "statement_scenario", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.scenario_column" ] } ], "used_by_capabilities": [ "statement.pnl_table" ], "used_by_artifacts": [], "registry_status": "defined" }, "statement_structure": { "role": "statement_structure", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "compound", "paths": [ "statement_rows", "periods", "scenarios_by_period" ] } ], "used_by_capabilities": [ "statement.pnl_table" ], "used_by_artifacts": [], "registry_status": "defined" }, "statement_value": { "role": "statement_value", "kinds": [ "metric" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.value_column" ] } ], "used_by_capabilities": [ "statement.pnl_table" ], "used_by_artifacts": [], "registry_status": "defined" }, "two_or_three_set_membership_fields": { "role": "two_or_three_set_membership_fields", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "compound", "paths": [ "mappings.item_column", "mappings.set_column" ] } ], "used_by_capabilities": [ "set_overlap.venn" ], "used_by_artifacts": [], "registry_status": "defined" }, "value_metric": { "role": "value_metric", "kinds": [ "metric" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.amount_column" ] } ], "used_by_capabilities": [ "variance.price_volume_mix", "variance.root_cause_component_bridge" ], "used_by_artifacts": [], "registry_status": "defined" }, "variance_metric": { "role": "variance_metric", "kinds": [ "metric" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.amount_column" ] }, { "kind": "contract", "parameters": [ "metric" ] } ], "used_by_capabilities": [ "variance.exploded_variance_bridge", "variance.root_cause_exploded_bridge", "variance.root_cause_total_bridge", "variance.scenario_bridge", "variance.total_by_dimension_bridge" ], "used_by_artifacts": [], "registry_status": "defined" }, "variance_step": { "role": "variance_step", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "derived_from_period", "role": "period_filter" } ], "used_by_capabilities": [ "variance.scenario_bridge" ], "used_by_artifacts": [], "registry_status": "defined" }, "volume_metric": { "role": "volume_metric", "kinds": [ "metric" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.units_column" ] }, { "kind": "explicit", "paths": [ "mappings.width_metric_column" ] } ], "used_by_capabilities": [ "variance.price_volume_mix", "variance.root_cause_component_bridge" ], "used_by_artifacts": [], "registry_status": "defined" }, "width_category": { "role": "width_category", "kinds": [ "dimension" ], "parameter_candidates": [ { "kind": "collection", "paths": [ "mappings.dimensions" ] } ], "used_by_capabilities": [ "mix.barmekko", "mix.marimekko" ], "used_by_artifacts": [], "registry_status": "defined" }, "width_metric": { "role": "width_metric", "kinds": [ "metric" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.width_metric_column" ] }, { "kind": "explicit", "paths": [ "mappings.units_column" ] } ], "used_by_capabilities": [ "mix.barmekko" ], "used_by_artifacts": [], "registry_status": "defined" }, "x_metric": { "role": "x_metric", "kinds": [ "metric" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.x_metric_column" ] } ], "used_by_capabilities": [ "scatter.bubble", "scatter.scatter" ], "used_by_artifacts": [], "registry_status": "defined" }, "y_metric": { "role": "y_metric", "kinds": [ "metric" ], "parameter_candidates": [ { "kind": "explicit", "paths": [ "mappings.y_metric_column" ] } ], "used_by_capabilities": [ "scatter.bubble", "scatter.scatter" ], "used_by_artifacts": [], "registry_status": "defined" } }, "profile_roles": { "period": { "description": "Dataset column that can order or filter observations by time or period.", "produced_by": "dataset_profile.roles.period" }, "metric": { "description": "Dataset column or derived metric candidate usable as a numeric measure.", "produced_by": "dataset_profile.roles.metric and dataset_profile.metric_classes" }, "dimension": { "description": "Dataset column usable for grouping, ranking, panels, or composition.", "produced_by": "dataset_profile.roles.dimension" }, "identifier": { "description": "Dataset column that mechanically identifies entities such as products or customers.", "produced_by": "dataset_profile.roles.identifier" }, "direct_dimension": { "description": "Categorical grouping candidate; not a semantic endorsement.", "produced_by": "dataset_profile.role_candidates.direct_dimension" }, "entity_key": { "description": "Entity candidate for cohorts, like-for-like populations, or set membership derivation.", "produced_by": "dataset_profile.role_candidates.entity_key" }, "ordered_stage": { "description": "Ordered funnel stage candidate.", "produced_by": "dataset_profile.role_candidates.ordered_stage" }, "rank_or_lane": { "description": "Rank, lane, band, bucket, or tier candidate.", "produced_by": "dataset_profile.role_candidates.rank_or_lane" }, "set_dimension": { "description": "Low-cardinality set/group candidate for overlap analysis.", "produced_by": "dataset_profile.role_candidates.set_dimension" }, "set_item": { "description": "Item/entity candidate for set membership aggregation.", "produced_by": "dataset_profile.role_candidates.set_item" }, "statement_line_item": { "description": "Financial statement line item candidate.", "produced_by": "dataset_profile.role_candidates.statement_line_item" }, "statement_scenario": { "description": "Scenario column candidate for structured statement values.", "produced_by": "dataset_profile.role_candidates.statement_scenario" } }, "capability_parameter_overrides": { "set_overlap.upset_small_multiples": { "panel_or_segment": [ { "kind": "runtime_contract", "paths": [ "options.small_multiples_dimension" ], "verified_by": "plugins/set-overlap-analysis/scripts/set_overlap_core.py" } ] }, "funnel.stage_table": { "stage_start_count": [ { "kind": "runtime_contract", "paths": [ "stage_table_mappings.start_count_column" ], "verified_by": "plugins/funnel-analysis/scripts/funnel_core.py:compute_funnel_rows_from_stage_table" } ], "stage_pass_count": [ { "kind": "runtime_contract", "paths": [ "stage_table_mappings.pass_count_column" ], "verified_by": "plugins/funnel-analysis/scripts/funnel_core.py:compute_funnel_rows_from_stage_table" } ], "ordered_stage": [ { "kind": "runtime_contract", "paths": [ "stage_table_mappings.stage_column" ], "verified_by": "plugins/funnel-analysis/scripts/funnel_core.py:compute_funnel_rows_from_stage_table" } ] }, "statement.pnl_table": { "period_axis": [ { "kind": "runtime_contract", "paths": [ "mappings.period_column" ], "verified_by": "plugins/statement-analysis/scripts/statement_core.py:_read_values" } ], "statement_value": [ { "kind": "runtime_contract", "paths": [ "mappings.value_column" ], "verified_by": "plugins/statement-analysis/scripts/statement_core.py:_read_values" } ], "statement_line_item": [ { "kind": "runtime_contract", "paths": [ "mappings.row_key_column" ], "verified_by": "plugins/statement-analysis/scripts/statement_core.py:_read_values" } ], "statement_scenario": [ { "kind": "runtime_contract", "paths": [ "mappings.scenario_column" ], "verified_by": "plugins/statement-analysis/scripts/statement_core.py:_read_values" } ], "statement_structure": [ { "kind": "runtime_contract", "paths": [ "statement_rows", "periods", "scenarios_by_period" ], "verified_by": "plugins/statement-analysis/scripts/statement_core.py:_validate_recipe" } ] }, "mix.area": { "period_axis": [ { "kind": "runtime_contract", "paths": [ "mappings.date_column", "mappings.period_column" ], "verified_by": "plugins/mix-contribution-analysis/scripts/mix_core.py:prepare_canonical_frame" } ] }, "mix.cohort_lost_stacked_column": { "period_axis": [ { "kind": "runtime_contract", "paths": [ "mappings.date_column", "mappings.period_column" ], "verified_by": "plugins/mix-contribution-analysis/scripts/mix_core.py:prepare_canonical_frame" } ], "lost_or_last_active_cohort": [ { "kind": "runtime_contract", "paths": [ "mappings.period_column", "mappings.dimensions", "options.period_selection", "options.derived_dimensions" ], "verified_by": "plugins/_shared/vendor/modules/chart_harness/period_derivations.py" } ] }, "mix.cohort_since_stacked_column": { "period_axis": [ { "kind": "runtime_contract", "paths": [ "mappings.date_column", "mappings.period_column" ], "verified_by": "plugins/mix-contribution-analysis/scripts/mix_core.py:prepare_canonical_frame" } ], "first_active_cohort": [ { "kind": "runtime_contract", "paths": [ "mappings.period_column", "mappings.dimensions", "options.period_selection", "options.derived_dimensions" ], "verified_by": "plugins/_shared/vendor/modules/chart_harness/period_derivations.py" } ] }, "mix.column": { "period_axis": [ { "kind": "runtime_contract", "paths": [ "mappings.date_column", "mappings.period_column" ], "verified_by": "plugins/mix-contribution-analysis/scripts/mix_core.py:prepare_canonical_frame" } ] }, "mix.column_overlay": { "period_axis": [ { "kind": "runtime_contract", "paths": [ "mappings.date_column", "mappings.period_column" ], "verified_by": "plugins/mix-contribution-analysis/scripts/mix_core.py:prepare_canonical_frame" } ] }, "mix.like_for_like_column": { "period_axis": [ { "kind": "runtime_contract", "paths": [ "mappings.date_column", "mappings.period_column" ], "verified_by": "plugins/mix-contribution-analysis/scripts/mix_core.py:prepare_canonical_frame" } ], "stable_population_flag": [ { "kind": "runtime_contract", "paths": [ "mappings.period_column", "mappings.dimensions", "options.period_selection", "options.like_for_like" ], "verified_by": "plugins/_shared/vendor/modules/chart_harness/period_derivations.py" } ] }, "mix.like_for_like_stacked_column": { "period_axis": [ { "kind": "runtime_contract", "paths": [ "mappings.date_column", "mappings.period_column" ], "verified_by": "plugins/mix-contribution-analysis/scripts/mix_core.py:prepare_canonical_frame" } ], "stable_population_flag": [ { "kind": "runtime_contract", "paths": [ "mappings.period_column", "mappings.dimensions", "options.period_selection", "options.like_for_like" ], "verified_by": "plugins/_shared/vendor/modules/chart_harness/period_derivations.py" } ] }, "mix.multitier_bar": { "period_axis": [ { "kind": "runtime_contract", "paths": [ "mappings.date_column", "mappings.period_column" ], "verified_by": "plugins/mix-contribution-analysis/scripts/mix_core.py:prepare_canonical_frame" } ] }, "mix.stacked_column": { "period_axis": [ { "kind": "runtime_contract", "paths": [ "mappings.date_column", "mappings.period_column" ], "verified_by": "plugins/mix-contribution-analysis/scripts/mix_core.py:prepare_canonical_frame" } ] }, "mix.timeline": { "period_axis": [ { "kind": "runtime_contract", "paths": [ "mappings.date_column", "mappings.period_column" ], "verified_by": "plugins/mix-contribution-analysis/scripts/mix_core.py:prepare_canonical_frame" } ] }, "mix.barmekko": { "area_metric": [ { "kind": "runtime_contract", "paths": [ "mappings.amount_column" ], "verified_by": "plugins/mix-contribution-analysis/scripts/mix_core.py:prepare_canonical_frame" } ], "width_metric": [ { "kind": "runtime_contract", "paths": [ "mappings.width_metric_column" ], "verified_by": "plugins/mix-contribution-analysis/scripts/mix_core.py:prepare_canonical_frame" } ] }, "variance.exploded_variance_bridge": { "period_filter": [ { "kind": "runtime_contract", "paths": [ "mappings.period_column", "mappings.baseline_period", "mappings.comparison_period" ], "verified_by": "plugins/variance-analysis/scripts/variance_core.py:validate_recipe" } ] }, "variance.price_volume_mix": { "period_filter": [ { "kind": "runtime_contract", "paths": [ "mappings.period_column", "mappings.baseline_period", "mappings.comparison_period" ], "verified_by": "plugins/variance-analysis/scripts/variance_core.py:validate_recipe" } ] }, "variance.root_cause_component_bridge": { "period_filter": [ { "kind": "runtime_contract", "paths": [ "mappings.period_column", "mappings.baseline_period", "mappings.comparison_period" ], "verified_by": "plugins/variance-analysis/scripts/variance_core.py:validate_recipe" } ] }, "variance.root_cause_exploded_bridge": { "period_filter": [ { "kind": "runtime_contract", "paths": [ "mappings.period_column", "mappings.baseline_period", "mappings.comparison_period" ], "verified_by": "plugins/variance-analysis/scripts/variance_core.py:validate_recipe" } ] }, "variance.root_cause_total_bridge": { "period_filter": [ { "kind": "runtime_contract", "paths": [ "mappings.period_column", "mappings.baseline_period", "mappings.comparison_period" ], "verified_by": "plugins/variance-analysis/scripts/variance_core.py:validate_recipe" } ] }, "variance.scenario_bridge": { "period_filter": [ { "kind": "runtime_contract", "paths": [ "mappings.period_column", "mappings.baseline_period", "mappings.comparison_period" ], "verified_by": "plugins/variance-analysis/scripts/variance_core.py:validate_recipe" } ] }, "variance.total_by_dimension_bridge": { "period_filter": [ { "kind": "runtime_contract", "paths": [ "mappings.period_column", "mappings.baseline_period", "mappings.comparison_period" ], "verified_by": "plugins/variance-analysis/scripts/variance_core.py:validate_recipe" } ] } }, "counts": { "chart_roles": 58, "profile_roles": 12, "used_chart_roles": 54, "chart_roles_missing_mapping": 0 } }, "review_iterations": [ { "iteration": 1, "looked_for": "Whether artifact entries and capability semantics were mixed.", "correction": "Split generated artifacts from capability records." }, { "iteration": 2, "looked_for": "Tautological when-to-use values.", "correction": "Capability records now use best_when and avoid_when; artifact fallback text is not used for selection." }, { "iteration": 3, "looked_for": "Whether line/trend is represented as a period-axis chart.", "correction": "period_comparison.trend has visual_grammar=line_time_series and period_semantics.role=axis." }, { "iteration": 4, "looked_for": "Scatter/bubble period leakage.", "correction": "scatter capabilities use period_semantics.role=filter and supports_period_axis=false." }, { "iteration": 5, "looked_for": "Different objectives among period charts.", "correction": "Added selection_emphasis values for trajectory, gap scan, exact values, endpoint change, and reconciliation." }, { "iteration": 6, "looked_for": "Bar-family ambiguity.", "correction": "Separated ranked bar, stacked composition, related metric overlay, and hierarchical multitier grammar." }, { "iteration": 7, "looked_for": "Distribution chart distinctions.", "correction": "Separated frequency shape, spread summary, individual observations, cumulative distribution, and smoothed density." }, { "iteration": 8, "looked_for": "Variance chart distinctions.", "correction": "Separated scenario bridge, dimension bridge, parent-child bridge, root-cause bridges, and PVM ladder." }, { "iteration": 9, "looked_for": "Whether all existing artifacts still map to a capability.", "correction": "Preserved every gallery item as an example under its capability." }, { "iteration": 10, "looked_for": "Whether the result can distinguish valid alternatives rather than choose one chart per question.", "correction": "Added competing_capability_ids and selection_emphasis so broad tasks can have multiple valid treatments." } ], "semantic_probes": [ { "probe_id": "monthly_trend_shape", "question": "Show how monthly sales moved over time.", "task_id": "time_and_period_movement", "status": "pass", "required_emphases": [ "trajectory_shape", "single_metric_trend_shape" ], "candidate_capability_ids": [ "period_comparison.trend", "mix.timeline" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "monthly_exact_values", "question": "Show exact monthly values and deltas for citation.", "task_id": "time_and_period_movement", "status": "pass", "required_emphases": [ "exact_values" ], "candidate_capability_ids": [ "period_comparison.time_series_table" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "monthly_reconciliation", "question": "Explain how monthly variances add up to the total change.", "task_id": "time_and_period_movement", "status": "pass", "required_emphases": [ "additive_reconciliation" ], "candidate_capability_ids": [ "period_comparison.horizontal_waterfall" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "one_month_rank", "question": "Compare brands in one selected month.", "task_id": "ranking_and_comparison", "status": "pass", "required_emphases": [ "ranked_single_metric_comparison", "ranked_contribution_and_cumulative_share" ], "candidate_capability_ids": [ "mix.bar", "mix.pareto" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "two_metric_relationship", "question": "Show the relationship between sales and distribution.", "task_id": "metric_relationship", "status": "pass", "required_emphases": [ "relationship_between_two_metrics", "two_metric_relationship_plus_size" ], "candidate_capability_ids": [ "scatter.scatter", "scatter.bubble" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "composition_shift", "question": "Show how mix composition changed across periods.", "task_id": "composition_and_mix", "status": "pass", "required_emphases": [ "composition_change_over_periods", "trend_with_cumulative_or_share_area" ], "candidate_capability_ids": [ "mix.stacked_column", "mix.area" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "distribution_shape", "question": "Show the distribution of unit price.", "task_id": "distribution", "status": "pass", "required_emphases": [ "frequency_shape", "spread_and_outliers_summary", "individual_observations" ], "candidate_capability_ids": [ "distribution.histogram", "distribution.boxplot", "distribution.stripplot" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "variance_reconciliation", "question": "Reconcile total movement from baseline to current with a plain bridge.", "task_id": "variance_and_bridge", "status": "pass", "required_emphases": [ "scenario_reconciliation" ], "candidate_capability_ids": [ "variance.scenario_bridge" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "variance_dimension_split", "question": "Which categories account for the total variance?", "task_id": "variance_and_bridge", "status": "pass", "required_emphases": [ "total_delta_split_by_dimension" ], "candidate_capability_ids": [ "variance.total_by_dimension_bridge" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "variance_parent_child_drilldown", "question": "Which categories drove variance, and which brands explain the selected category moves?", "task_id": "variance_and_bridge", "status": "pass", "required_emphases": [ "parent_bridge_with_child_drilldowns" ], "candidate_capability_ids": [ "variance.exploded_variance_bridge" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "variance_root_cause_total", "question": "Which ordered root-cause path explains the total movement?", "task_id": "variance_and_bridge", "status": "pass", "required_emphases": [ "root_cause_total_movement" ], "candidate_capability_ids": [ "variance.root_cause_total_bridge" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "variance_root_cause_exploded", "question": "Which ordered root-cause path explains the total movement, and what explains the selected root-cause drivers?", "task_id": "variance_and_bridge", "status": "pass", "required_emphases": [ "root_cause_path_with_nested_drilldowns" ], "candidate_capability_ids": [ "variance.root_cause_exploded_bridge" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "variance_root_cause_component", "question": "Which dimension combinations explain the price component of sales movement?", "task_id": "variance_and_bridge", "status": "pass", "required_emphases": [ "component_level_root_cause" ], "candidate_capability_ids": [ "variance.root_cause_component_bridge" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "variance_pvm", "question": "How much of the value movement is due to price, units, and mix?", "task_id": "variance_and_bridge", "status": "pass", "required_emphases": [ "pvm_decomposition_comparison" ], "candidate_capability_ids": [ "variance.price_volume_mix" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "set_intersections", "question": "Show overlaps across several sets.", "task_id": "set_overlap", "status": "pass", "required_emphases": [ "many_set_intersections" ], "candidate_capability_ids": [ "set_overlap.upset" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] }, { "probe_id": "product_evidence_table", "question": "Show product-level evidence for selected attribute bundles.", "task_id": "evidence_and_reporting_tables", "status": "pass", "required_emphases": [ "product_level_grounding" ], "candidate_capability_ids": [ "attributes.product_signal_evidence_table" ], "missing_required_capability_ids": [], "present_forbidden_capability_ids": [], "missing_required_emphases": [] } ], "selector_audit": { "capabilities_checked": 48, "missing_selection_contract": [], "duplicate_selector_signatures": [], "pairwise_ambiguity": { "signature_groups": [ { "signature": { "analysis_task_ids": [ "cohort_and_population" ], "period_role": "axis", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume" ] ], "dimension_count": 0, "dimension_resolution_types": [ "derived_from_entity_period" ] }, "capability_ids": [ "mix.cohort_lost_stacked_column", "mix.cohort_since_stacked_column", "mix.like_for_like_column" ], "pair_count": 3 }, { "signature": { "analysis_task_ids": [ "composition_and_mix" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume" ] ], "dimension_count": 2, "dimension_resolution_types": [ "direct_dimension", "direct_dimension" ] }, "capability_ids": [ "mix.marimekko", "mix.stacked_bar", "mix.stacked_pareto" ], "pair_count": 3 }, { "signature": { "analysis_task_ids": [ "distribution" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [] }, "capability_ids": [ "distribution.boxplot", "distribution.ecdf", "distribution.histogram", "distribution.kernel_density", "distribution.stripplot" ], "pair_count": 10 }, { "signature": { "analysis_task_ids": [ "ranking_and_comparison" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume" ] ], "dimension_count": 1, "dimension_resolution_types": [ "direct_dimension" ] }, "capability_ids": [ "mix.bar", "mix.pareto" ], "pair_count": 1 }, { "signature": { "analysis_task_ids": [ "set_overlap" ], "period_role": "filter", "source_metric_count": 0, "source_metric_class_groups": [], "dimension_count": 0, "dimension_resolution_types": [ "derived_set_membership" ] }, "capability_ids": [ "set_overlap.upset", "set_overlap.venn" ], "pair_count": 1 }, { "signature": { "analysis_task_ids": [ "time_and_period_movement" ], "period_role": "axis", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [ "derived_from_period_pair" ] }, "capability_ids": [ "period_comparison.by_period", "period_comparison.multitier_column", "period_comparison.trend" ], "pair_count": 3 }, { "signature": { "analysis_task_ids": [ "time_and_period_movement" ], "period_role": "axis", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume" ] ], "dimension_count": 0, "dimension_resolution_types": [] }, "capability_ids": [ "mix.column", "mix.timeline" ], "pair_count": 1 } ], "high_overlap_pair_count": 22, "resolved_pair_count": 22, "unresolved_pair_count": 0, "unresolved_pairs": [], "high_overlap_pairs": [ { "capability_ids": [ "mix.cohort_lost_stacked_column", "mix.cohort_since_stacked_column" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "cohort_and_population" ], "period_role": "axis", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume" ] ], "dimension_count": 0, "dimension_resolution_types": [ "derived_from_entity_period" ] }, "selection_emphases": { "mix.cohort_lost_stacked_column": "lost_cohort_contribution", "mix.cohort_since_stacked_column": "since_cohort_contribution" }, "structured_decision_cues": { "mix.cohort_lost_stacked_column": { "primary_decision_cue": "Question asks how much contribution comes from entities by last active or lost cohort.", "requires_question_focus": [ "lost_cohort", "entity_population_change" ], "forbidden_question_focus": [ "since_cohort", "like_for_like_population", "composition_only" ] }, "mix.cohort_since_stacked_column": { "primary_decision_cue": "Question asks how much contribution comes from entities by first active or since cohort.", "requires_question_focus": [ "since_cohort", "entity_population_change" ], "forbidden_question_focus": [ "lost_cohort", "like_for_like_population", "period_gap" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "mix.cohort_lost_stacked_column", "mix.like_for_like_column" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "cohort_and_population" ], "period_role": "axis", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume" ] ], "dimension_count": 0, "dimension_resolution_types": [ "derived_from_entity_period" ] }, "selection_emphases": { "mix.cohort_lost_stacked_column": "lost_cohort_contribution", "mix.like_for_like_column": "same_population_total_change" }, "structured_decision_cues": { "mix.cohort_lost_stacked_column": { "primary_decision_cue": "Question asks how much contribution comes from entities by last active or lost cohort.", "requires_question_focus": [ "lost_cohort", "entity_population_change" ], "forbidden_question_focus": [ "since_cohort", "like_for_like_population", "composition_only" ] }, "mix.like_for_like_column": { "primary_decision_cue": "Question asks for total change among the same entities present in both periods.", "requires_question_focus": [ "like_for_like_population", "total_change" ], "forbidden_question_focus": [ "like_for_like_composition", "cohort_change", "all_population_total" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "mix.cohort_since_stacked_column", "mix.like_for_like_column" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "cohort_and_population" ], "period_role": "axis", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume" ] ], "dimension_count": 0, "dimension_resolution_types": [ "derived_from_entity_period" ] }, "selection_emphases": { "mix.cohort_since_stacked_column": "since_cohort_contribution", "mix.like_for_like_column": "same_population_total_change" }, "structured_decision_cues": { "mix.cohort_since_stacked_column": { "primary_decision_cue": "Question asks how much contribution comes from entities by first active or since cohort.", "requires_question_focus": [ "since_cohort", "entity_population_change" ], "forbidden_question_focus": [ "lost_cohort", "like_for_like_population", "period_gap" ] }, "mix.like_for_like_column": { "primary_decision_cue": "Question asks for total change among the same entities present in both periods.", "requires_question_focus": [ "like_for_like_population", "total_change" ], "forbidden_question_focus": [ "like_for_like_composition", "cohort_change", "all_population_total" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "mix.marimekko", "mix.stacked_bar" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "composition_and_mix" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume" ] ], "dimension_count": 2, "dimension_resolution_types": [ "direct_dimension", "direct_dimension" ] }, "selection_emphases": { "mix.marimekko": "two_dimension_share_and_size", "mix.stacked_bar": "composition_within_ranked_totals" }, "structured_decision_cues": { "mix.marimekko": { "primary_decision_cue": "Question asks for composition across two categorical dimensions using segment share and size.", "requires_question_focus": [ "two_dimension_share", "composition_size" ], "forbidden_question_focus": [ "width_height_metrics", "single_metric_rank", "period_variance" ] }, "mix.stacked_bar": { "primary_decision_cue": "Question asks for composition within ranked category totals.", "requires_question_focus": [ "ranked_composition", "stacked_total" ], "forbidden_question_focus": [ "single_metric_rank", "secondary_metric_marker", "period_delta" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "mix.marimekko", "mix.stacked_pareto" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "composition_and_mix" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume" ] ], "dimension_count": 2, "dimension_resolution_types": [ "direct_dimension", "direct_dimension" ] }, "selection_emphases": { "mix.marimekko": "two_dimension_share_and_size", "mix.stacked_pareto": "concentration_with_component_breakdown" }, "structured_decision_cues": { "mix.marimekko": { "primary_decision_cue": "Question asks for composition across two categorical dimensions using segment share and size.", "requires_question_focus": [ "two_dimension_share", "composition_size" ], "forbidden_question_focus": [ "width_height_metrics", "single_metric_rank", "period_variance" ] }, "mix.stacked_pareto": { "primary_decision_cue": "Question asks for concentration and component breakdown together.", "requires_question_focus": [ "pareto_concentration", "component_breakdown" ], "forbidden_question_focus": [ "pareto_only", "stacked_total_only", "metric_relationship" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "mix.stacked_bar", "mix.stacked_pareto" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "composition_and_mix" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume" ] ], "dimension_count": 2, "dimension_resolution_types": [ "direct_dimension", "direct_dimension" ] }, "selection_emphases": { "mix.stacked_bar": "composition_within_ranked_totals", "mix.stacked_pareto": "concentration_with_component_breakdown" }, "structured_decision_cues": { "mix.stacked_bar": { "primary_decision_cue": "Question asks for composition within ranked category totals.", "requires_question_focus": [ "ranked_composition", "stacked_total" ], "forbidden_question_focus": [ "single_metric_rank", "secondary_metric_marker", "period_delta" ] }, "mix.stacked_pareto": { "primary_decision_cue": "Question asks for concentration and component breakdown together.", "requires_question_focus": [ "pareto_concentration", "component_breakdown" ], "forbidden_question_focus": [ "pareto_only", "stacked_total_only", "metric_relationship" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "distribution.boxplot", "distribution.ecdf" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "distribution" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [] }, "selection_emphases": { "distribution.boxplot": "spread_and_outliers_summary", "distribution.ecdf": "cumulative_distribution_and_percentiles" }, "structured_decision_cues": { "distribution.boxplot": { "primary_decision_cue": "Question asks for spread, quartiles, or outliers in numeric observations.", "requires_question_focus": [ "distribution_spread", "outliers" ], "forbidden_question_focus": [ "individual_observations", "smoothed_density", "cumulative_distribution" ] }, "distribution.ecdf": { "primary_decision_cue": "Question asks for cumulative share below thresholds or percentile reading.", "requires_question_focus": [ "cumulative_distribution", "percentile_threshold" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "individual_observations" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "distribution.boxplot", "distribution.histogram" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "distribution" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [] }, "selection_emphases": { "distribution.boxplot": "spread_and_outliers_summary", "distribution.histogram": "frequency_shape" }, "structured_decision_cues": { "distribution.boxplot": { "primary_decision_cue": "Question asks for spread, quartiles, or outliers in numeric observations.", "requires_question_focus": [ "distribution_spread", "outliers" ], "forbidden_question_focus": [ "individual_observations", "smoothed_density", "cumulative_distribution" ] }, "distribution.histogram": { "primary_decision_cue": "Question asks for frequency distribution shape using binned observations.", "requires_question_focus": [ "frequency_bins", "distribution_shape" ], "forbidden_question_focus": [ "individual_observations", "cumulative_distribution", "smoothed_density" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "distribution.boxplot", "distribution.kernel_density" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "distribution" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [] }, "selection_emphases": { "distribution.boxplot": "spread_and_outliers_summary", "distribution.kernel_density": "smoothed_distribution_shape" }, "structured_decision_cues": { "distribution.boxplot": { "primary_decision_cue": "Question asks for spread, quartiles, or outliers in numeric observations.", "requires_question_focus": [ "distribution_spread", "outliers" ], "forbidden_question_focus": [ "individual_observations", "smoothed_density", "cumulative_distribution" ] }, "distribution.kernel_density": { "primary_decision_cue": "Question asks for smoothed distribution shape rather than bins or points.", "requires_question_focus": [ "smoothed_density", "distribution_shape" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "cumulative_distribution" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "distribution.boxplot", "distribution.stripplot" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "distribution" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [] }, "selection_emphases": { "distribution.boxplot": "spread_and_outliers_summary", "distribution.stripplot": "individual_observations" }, "structured_decision_cues": { "distribution.boxplot": { "primary_decision_cue": "Question asks for spread, quartiles, or outliers in numeric observations.", "requires_question_focus": [ "distribution_spread", "outliers" ], "forbidden_question_focus": [ "individual_observations", "smoothed_density", "cumulative_distribution" ] }, "distribution.stripplot": { "primary_decision_cue": "Question asks to see individual numeric observations and point-level outliers.", "requires_question_focus": [ "individual_observations", "point_outliers" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "smoothed_density" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "distribution.ecdf", "distribution.histogram" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "distribution" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [] }, "selection_emphases": { "distribution.ecdf": "cumulative_distribution_and_percentiles", "distribution.histogram": "frequency_shape" }, "structured_decision_cues": { "distribution.ecdf": { "primary_decision_cue": "Question asks for cumulative share below thresholds or percentile reading.", "requires_question_focus": [ "cumulative_distribution", "percentile_threshold" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "individual_observations" ] }, "distribution.histogram": { "primary_decision_cue": "Question asks for frequency distribution shape using binned observations.", "requires_question_focus": [ "frequency_bins", "distribution_shape" ], "forbidden_question_focus": [ "individual_observations", "cumulative_distribution", "smoothed_density" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "distribution.ecdf", "distribution.kernel_density" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "distribution" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [] }, "selection_emphases": { "distribution.ecdf": "cumulative_distribution_and_percentiles", "distribution.kernel_density": "smoothed_distribution_shape" }, "structured_decision_cues": { "distribution.ecdf": { "primary_decision_cue": "Question asks for cumulative share below thresholds or percentile reading.", "requires_question_focus": [ "cumulative_distribution", "percentile_threshold" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "individual_observations" ] }, "distribution.kernel_density": { "primary_decision_cue": "Question asks for smoothed distribution shape rather than bins or points.", "requires_question_focus": [ "smoothed_density", "distribution_shape" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "cumulative_distribution" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "distribution.ecdf", "distribution.stripplot" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "distribution" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [] }, "selection_emphases": { "distribution.ecdf": "cumulative_distribution_and_percentiles", "distribution.stripplot": "individual_observations" }, "structured_decision_cues": { "distribution.ecdf": { "primary_decision_cue": "Question asks for cumulative share below thresholds or percentile reading.", "requires_question_focus": [ "cumulative_distribution", "percentile_threshold" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "individual_observations" ] }, "distribution.stripplot": { "primary_decision_cue": "Question asks to see individual numeric observations and point-level outliers.", "requires_question_focus": [ "individual_observations", "point_outliers" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "smoothed_density" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "distribution.histogram", "distribution.kernel_density" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "distribution" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [] }, "selection_emphases": { "distribution.histogram": "frequency_shape", "distribution.kernel_density": "smoothed_distribution_shape" }, "structured_decision_cues": { "distribution.histogram": { "primary_decision_cue": "Question asks for frequency distribution shape using binned observations.", "requires_question_focus": [ "frequency_bins", "distribution_shape" ], "forbidden_question_focus": [ "individual_observations", "cumulative_distribution", "smoothed_density" ] }, "distribution.kernel_density": { "primary_decision_cue": "Question asks for smoothed distribution shape rather than bins or points.", "requires_question_focus": [ "smoothed_density", "distribution_shape" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "cumulative_distribution" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "distribution.histogram", "distribution.stripplot" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "distribution" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [] }, "selection_emphases": { "distribution.histogram": "frequency_shape", "distribution.stripplot": "individual_observations" }, "structured_decision_cues": { "distribution.histogram": { "primary_decision_cue": "Question asks for frequency distribution shape using binned observations.", "requires_question_focus": [ "frequency_bins", "distribution_shape" ], "forbidden_question_focus": [ "individual_observations", "cumulative_distribution", "smoothed_density" ] }, "distribution.stripplot": { "primary_decision_cue": "Question asks to see individual numeric observations and point-level outliers.", "requires_question_focus": [ "individual_observations", "point_outliers" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "smoothed_density" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "distribution.kernel_density", "distribution.stripplot" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "distribution" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [] }, "selection_emphases": { "distribution.kernel_density": "smoothed_distribution_shape", "distribution.stripplot": "individual_observations" }, "structured_decision_cues": { "distribution.kernel_density": { "primary_decision_cue": "Question asks for smoothed distribution shape rather than bins or points.", "requires_question_focus": [ "smoothed_density", "distribution_shape" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "cumulative_distribution" ] }, "distribution.stripplot": { "primary_decision_cue": "Question asks to see individual numeric observations and point-level outliers.", "requires_question_focus": [ "individual_observations", "point_outliers" ], "forbidden_question_focus": [ "frequency_bins", "spread_outliers", "smoothed_density" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "mix.bar", "mix.pareto" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "ranking_and_comparison" ], "period_role": "filter", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume" ] ], "dimension_count": 1, "dimension_resolution_types": [ "direct_dimension" ] }, "selection_emphases": { "mix.bar": "ranked_single_metric_comparison", "mix.pareto": "ranked_contribution_and_cumulative_share" }, "structured_decision_cues": { "mix.bar": { "primary_decision_cue": "Question asks to rank categories by one selected metric in a scope.", "requires_question_focus": [ "single_metric_rank", "category_comparison" ], "forbidden_question_focus": [ "composition", "period_delta", "pareto_concentration" ] }, "mix.pareto": { "primary_decision_cue": "Question asks which few items explain most of the total using cumulative share.", "requires_question_focus": [ "pareto_concentration", "cumulative_share" ], "forbidden_question_focus": [ "component_breakdown", "single_metric_rank", "time_trend" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "set_overlap.upset", "set_overlap.venn" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "set_overlap" ], "period_role": "filter", "source_metric_count": 0, "source_metric_class_groups": [], "dimension_count": 0, "dimension_resolution_types": [ "derived_set_membership" ] }, "selection_emphases": { "set_overlap.upset": "many_set_intersections", "set_overlap.venn": "simple_two_or_three_set_overlap" }, "structured_decision_cues": { "set_overlap.upset": { "primary_decision_cue": "Question asks for intersection patterns across several sets.", "requires_question_focus": [ "many_set_intersections", "set_membership" ], "forbidden_question_focus": [ "simple_set_overlap", "set_overlap_panels", "distribution_shape" ] }, "set_overlap.venn": { "primary_decision_cue": "Question asks for simple overlap among two or three sets.", "requires_question_focus": [ "simple_set_overlap", "two_or_three_sets" ], "forbidden_question_focus": [ "many_set_intersections", "set_overlap_panels", "metric_relationship" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "period_comparison.by_period", "period_comparison.multitier_column" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "time_and_period_movement" ], "period_role": "axis", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [ "derived_from_period_pair" ] }, "selection_emphases": { "period_comparison.by_period": "period_by_period_gap", "period_comparison.multitier_column": "compact_side_by_side_period_comparison" }, "structured_decision_cues": { "period_comparison.by_period": { "primary_decision_cue": "Question asks for weekly-average current-vs-baseline gaps across overlapping recency windows, not individual calendar months.", "requires_question_focus": [ "period_gap", "current_vs_baseline_by_period" ], "forbidden_question_focus": [ "trajectory_shape", "bridge_reconciliation", "exact_period_values" ] }, "period_comparison.multitier_column": { "primary_decision_cue": "Question asks for compact side-by-side current and baseline period columns.", "requires_question_focus": [ "side_by_side_periods", "current_vs_baseline_values" ], "forbidden_question_focus": [ "trajectory_shape", "exact_period_values", "bridge_reconciliation" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "period_comparison.by_period", "period_comparison.trend" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "time_and_period_movement" ], "period_role": "axis", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [ "derived_from_period_pair" ] }, "selection_emphases": { "period_comparison.by_period": "period_by_period_gap", "period_comparison.trend": "trajectory_shape" }, "structured_decision_cues": { "period_comparison.by_period": { "primary_decision_cue": "Question asks for weekly-average current-vs-baseline gaps across overlapping recency windows, not individual calendar months.", "requires_question_focus": [ "period_gap", "current_vs_baseline_by_period" ], "forbidden_question_focus": [ "trajectory_shape", "bridge_reconciliation", "exact_period_values" ] }, "period_comparison.trend": { "primary_decision_cue": "Question asks for ordered period trajectory: acceleration, reversal, narrowing, widening, or seasonality.", "requires_question_focus": [ "trajectory_shape", "current_vs_baseline_period_axis" ], "forbidden_question_focus": [ "exact_period_values", "bridge_reconciliation", "endpoint_change" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "period_comparison.multitier_column", "period_comparison.trend" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "time_and_period_movement" ], "period_role": "axis", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume", "index", "numeric_observation", "rate", "score", "share" ] ], "dimension_count": 0, "dimension_resolution_types": [ "derived_from_period_pair" ] }, "selection_emphases": { "period_comparison.multitier_column": "compact_side_by_side_period_comparison", "period_comparison.trend": "trajectory_shape" }, "structured_decision_cues": { "period_comparison.multitier_column": { "primary_decision_cue": "Question asks for compact side-by-side current and baseline period columns.", "requires_question_focus": [ "side_by_side_periods", "current_vs_baseline_values" ], "forbidden_question_focus": [ "trajectory_shape", "exact_period_values", "bridge_reconciliation" ] }, "period_comparison.trend": { "primary_decision_cue": "Question asks for ordered period trajectory: acceleration, reversal, narrowing, widening, or seasonality.", "requires_question_focus": [ "trajectory_shape", "current_vs_baseline_period_axis" ], "forbidden_question_focus": [ "exact_period_values", "bridge_reconciliation", "endpoint_change" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } }, { "capability_ids": [ "mix.column", "mix.timeline" ], "status": "resolved", "issues": [], "signature": { "analysis_task_ids": [ "time_and_period_movement" ], "period_role": "axis", "source_metric_count": 1, "source_metric_class_groups": [ [ "additive_count", "additive_value", "additive_volume" ] ], "dimension_count": 0, "dimension_resolution_types": [] }, "selection_emphases": { "mix.column": "total_metric_by_period_or_scope", "mix.timeline": "single_metric_trend_shape" }, "structured_decision_cues": { "mix.column": { "primary_decision_cue": "Question asks for total metric columns by period or selected scope without composition.", "requires_question_focus": [ "total_metric", "column_summary" ], "forbidden_question_focus": [ "composition", "single_line_trend", "secondary_metric_marker" ] }, "mix.timeline": { "primary_decision_cue": "Question asks for one metric's trend path across ordered periods without AC/PY comparison.", "requires_question_focus": [ "single_line_trend", "ordered_periods" ], "forbidden_question_focus": [ "current_vs_baseline", "composition_over_time", "exact_period_values" ] } }, "relationship_evidence": { "explicit_competitor_link": true, "negative_example_link": true, "ambiguous_example_link": true } } ], "result": "pass" }, "generated_manifest_only_capabilities": [], "result": "pass" }, "validation_issues": [] }