nodes.gold_api_views

nodes.gold_api_views

Gold Layer API Views Hamilton Nodes

Visualization API nodes that provide stable, canonical views of Gold data.

These nodes act as the contract layer between Gold analytics and visualization code. All viz nodes should depend on these views instead of directly consuming operator_petrinex_emissions, companies_rankings, operator_decision_metrics, etc.

Benefits: - Year filtering happens once, consistently - Column schemas are guaranteed (no defensive coding in viz) - Unit conversions are standardized - Multi-source joins are handled here, not in every viz node

All functions are Hamilton nodes tagged with layer=‘gold’ and domain=‘api’.

Functions

Name	Description
operator_parent_viz_view	Parent-level operator-year view for visualizations.
operator_viz_view	Build canonical operator-year view for all operator-level visualizations.

operator_parent_viz_view

nodes.gold_api_views.operator_parent_viz_view(
    operator_parent_emissions: pd.DataFrame,
    companies_parent_rankings: pd.DataFrame,
    operator_parent_decision_metrics: pd.DataFrame,
    scenario_results: pd.DataFrame | None = None,
    target_year: int = 2023,
)

Parent-level operator-year view for visualizations.

Args: operator_parent_emissions: Parent-level emissions data companies_parent_rankings: Parent-level rankings operator_parent_decision_metrics: Parent-level decision metrics scenario_results: Optional scenario analysis results target_year: Year to filter

Returns: DataFrame with standardized columns and units (parent-level)

operator_viz_view

nodes.gold_api_views.operator_viz_view(
    operator_petrinex_emissions: pd.DataFrame,
    companies_rankings: pd.DataFrame,
    operator_decision_metrics: pd.DataFrame,
    operator_reduction_predictions_from_parquet: pd.DataFrame,
    scenario_results: pd.DataFrame | None = None,
    operator_intensity_predictions: pd.DataFrame | None = None,
    operator_opportunity_predictions: pd.DataFrame | None = None,
    target_year: int = 2023,
)

Build canonical operator-year view for all operator-level visualizations.

Args: operator_petrinex_emissions: Base operator-year emissions companies_rankings: Operator rankings operator_decision_metrics: Decision metrics operator_reduction_predictions_from_parquet: ML reduction predictions (auto-loaded from parquet) scenario_results: Optional scenario analysis results operator_intensity_predictions: Optional ML intensity predictions operator_opportunity_predictions: Optional ML opportunity predictions target_year: Year to filter

Returns: DataFrame with standardized columns and units

Note: ML predictions are optional - if parquet file doesn’t exist, loader returns empty DataFrame and predicted_reduction_t will be NaN in output.