Plot Services¶

def generate_plot(
    self,
    use_case_id: str,
    data: pd.DataFrame,
    filters: Optional[Dict[str, Any]] = None,
    customizations: Optional[Any] = None,
    force_refresh: bool = False,
) -> go.Figure:
    """
    Generate plot for given use case with caching.

    Pipeline:
    1. Load configuration from YAML
    2. Generate cache keys
    3. Check graph cache
    4. If miss: Create strategy and generate plot
    5. Cache result
    6. Return figure

    Parameters
    ----------
    use_case_id : str
        Use case identifier (e.g., "UC-2.1").
    data : pd.DataFrame
        Input data.
    filters : Optional[Dict[str, Any]], default=None
        Filters to apply (e.g., {"uc-2-1-range-slider": [10, 50]}).
    customizations : Optional[Any], default=None
        Additional customizations (future feature).
    force_refresh : bool, default=False
        Force cache refresh.

    Returns
    -------
    go.Figure
        Generated Plotly figure.

    Raises
    ------
    ValueError
        If data validation fails.
    FileNotFoundError
        If configuration file not found.

    Examples
    --------
    >>> service = PlotService()
    >>> fig = service.generate_plot("UC-2.1", df)
    >>> fig.layout.height
    500
    """
    start_time = time.time()
    logger.info(f"Generating plot for {use_case_id}")

    # 1. Load configuration (force reload if force_refresh is True)
    config = self.config_loader.load_config(use_case_id, force_reload=force_refresh)
    perf_config = config.get("performance", {})
    cache_config = perf_config.get("cache", {})

    # 2. Generate cache keys
    data_hash = self._generate_data_hash(data)
    filters_hash = self._generate_filters_hash(filters) if filters else "no_filters"

    # Generate cache key (needed for both checking and storing)
    graph_cache_key = self._get_cache_key(config, "graph", data_hash, filters_hash)

    # 3. Check if caching is enabled
    if cache_config.get("enabled", True) and not force_refresh:
        # Check graph cache (fastest)
        cached_figure = self.cache_manager.get_cached_graph(graph_cache_key)
        if cached_figure:
            cache_time = time.time() - start_time
            logger.info(
                f"Cache HIT (graph) for {use_case_id}: " f"{cache_time:.3f}s"
            )
            return cached_figure

        logger.debug(f"Cache MISS (graph) for {use_case_id}")

    # 4. Create strategy via factory
    strategy = self.factory.create_strategy(config)

    # 5. Generate plot (includes validation, processing, filtering)
    try:
        figure = strategy.generate_plot(
            data, filters=filters, customizations=customizations
        )

        # 6. Cache the figure
        if cache_config.get("enabled", True):
            ttl = self._get_cache_ttl(cache_config, "graph")
            # Note: ttl is not used by current GraphCacheManager
            # (it uses global TTL), but we pass metadata
            metadata = {"use_case_id": use_case_id, "filters": filters, "ttl": ttl}
            self.cache_manager.cache_graph(
                graph_cache_key, figure, metadata=metadata
            )
            logger.debug(f"Cached graph for {use_case_id} (TTL: {ttl}s)")

        total_time = time.time() - start_time
        logger.info(f"Plot generated for {use_case_id}: {total_time:.3f}s")

        return figure

    except Exception as e:
        logger.error(f"Error generating plot for {use_case_id}: {e}", exc_info=True)
        raise

def clear_cache(self, use_case_id: Optional[str] = None) -> None:
    """
    Clear cache for specific use case or all.

    Parameters
    ----------
    use_case_id : Optional[str], default=None
        Use case ID to clear. If None, clears all.
    """
    if use_case_id:
        # Clear specific use case (would need pattern matching)
        logger.info(f"Clearing cache for {use_case_id}")
    else:
        self.cache_manager.clear()
        logger.info("Cleared all plot caches")

def create_strategy(self, config: Dict[str, Any]) -> BasePlotStrategy:
    """
    Create strategy instance from configuration.

    Parameters
    ----------
    config : Dict[str, Any]
        Complete configuration dictionary (must contain
        visualization.strategy: str)

    Returns
    -------
    BasePlotStrategy
        Instantiated strategy

    Raises
    ------
    ValueError
        If strategy name not found in registry
    KeyError
        If configuration missing required keys
    """
    # Get strategy name from config
    viz_config = config.get("visualization", {})
    strategy_name = viz_config.get("strategy")

    if not strategy_name:
        raise ValueError("Configuration missing 'visualization.strategy' key")

    # Lookup strategy class
    strategy_class = self._strategy_registry.get(strategy_name)

    if not strategy_class:
        available = list(self._strategy_registry.keys())
        raise ValueError(
            f"Unknown strategy: '{strategy_name}'. "
            f"Available strategies: {available}"
        )

    # Instantiate and return
    strategy = strategy_class(config)

    use_case_id = config.get("metadata", {}).get("use_case_id", "unknown")
    logger.info(f"Created {strategy_name} for {use_case_id}")

    return strategy

def register_strategy(self, name: str, strategy_class: type) -> None:
    """
    Register new strategy class.

    Allows dynamic registration of strategies at runtime.

    Parameters
    ----------
    name : str
        Strategy name (used in YAML config)
    strategy_class : type
        Strategy class (must inherit from BasePlotStrategy)
    """
    if not issubclass(strategy_class, BasePlotStrategy):
        raise TypeError(f"{strategy_class} must inherit from BasePlotStrategy")

    self._strategy_registry[name] = strategy_class
    logger.info(f"Registered strategy: {name}")

def get_available_strategies(self) -> list:
    """
    Get list of available strategy names.

    Returns
    -------
    list
        List of registered strategy names.
    """
    return list(self._strategy_registry.keys())

def load_config(
    self, use_case_id: str, force_reload: bool = False
) -> Dict[str, Any]:
    """
    Load configuration for given use case.

    Configuration file naming convention:
    - UC-2.1 -> module2/uc_2_1_config.yaml
    - UC-3.4 -> module3/uc_3_4_config.yaml

    Parameters
    ----------
    use_case_id : str
        Use case identifier (e.g., "UC-2.1")
    force_reload : bool, default=False
        Force reload from file (bypass cache)

    Returns
    -------
    Dict[str, Any]
        Configuration dictionary

    Raises
    ------
    FileNotFoundError
        If configuration file not found
    ValueError
        If YAML is invalid
    """
    # Check cache
    if use_case_id in self._cache and not force_reload:
        logger.debug(f"Cache HIT for config: {use_case_id}")
        return self._cache[use_case_id]

    logger.debug(f"Cache MISS for config: {use_case_id}")

    # Parse use case ID to get module and file name
    # UC-2.1 -> module2, uc_2_1_config.yaml
    # UC-3.2 -> module3, uc_3_2_config.yaml

    # Remove 'UC-' prefix and split by '.'
    if not use_case_id.startswith("UC-"):
        raise ValueError(
            f"Invalid use case ID format: {use_case_id}. "
            f"Expected format: UC-X.Y"
        )

    # Extract module and subcase numbers
    # "UC-2.1" -> "2.1" -> ["2", "1"]
    id_part = use_case_id.replace("UC-", "")
    parts = id_part.split(".")

    if len(parts) != 2:
        raise ValueError(
            f"Invalid use case ID format: {use_case_id}. "
            f"Expected format: UC-X.Y"
        )

    module_num = parts[0]  # "2"
    sub_case = parts[1]  # "1"

    # Build file path
    # module2/uc_2_1_config.yaml
    module_dir = f"module{module_num}"
    filename = f"uc_{module_num}_{sub_case}_config.yaml"
    config_path = self.config_dir / module_dir / filename

    logger.debug(f"Looking for config: {use_case_id} -> {config_path}")

    # Load YAML
    if not config_path.exists():
        raise FileNotFoundError(f"Configuration file not found: {config_path}")

    try:
        with open(config_path, "r", encoding="utf-8") as f:
            config = yaml.safe_load(f)

        # Cache and return
        self._cache[use_case_id] = config
        logger.info(f"Loaded configuration for {use_case_id}")

        return config

    except yaml.YAMLError as e:
        raise ValueError(f"Invalid YAML in {config_path}: {e}")

def clear_cache(self) -> None:
    """Clear configuration cache."""
    self._cache.clear()
    logger.info("Configuration cache cleared")

def get_cached_keys(self) -> list:
    """
    Get list of cached use case IDs.

    Returns
    -------
    list
        List of cached use case IDs.
    """
    return list(self._cache.keys())