UpSet Plot Strategy¶

def generate(self, data: pd.DataFrame) -> go.Figure:
    """
    Generate UpSet plot from data.

    Validates data, cleans it, builds category sets, creates UpSet plot,
    and converts to Plotly format.

    Parameters
    ----------
    data : pd.DataFrame
        DataFrame containing entity and category columns.

    Returns
    -------
    go.Figure
        Plotly figure object containing the UpSet visualization.

    Raises
    ------
    ValueError
        If data is empty or required columns are missing.
    """
    logger.info(
        "Generating UpSet plot",
        extra={
            "entity_col": self.entity_column,
            "category_col": self.category_column,
            "rows": len(data),
        },
    )

    # Validate data
    self._validate_data(data)

    # Clean and prepare data
    df_clean = self._clean_data(data)

    # Build sets for each category
    category_sets = self._build_category_sets(df_clean)

    # Generate UpSet data structure
    upset_data = from_contents(category_sets)

    # Create UpSet plot (matplotlib)
    upset_plot = self._create_upset_plot(upset_data)

    # Convert to Plotly
    fig = self._convert_to_plotly(upset_plot, category_sets)

    # Apply layout
    self._apply_layout(fig)

    logger.info(
        "UpSet plot generated successfully",
        extra={
            "categories": len(category_sets),
            "total_intersections": len(upset_data),
        },
    )

    return fig

def validate_data(self, df: pd.DataFrame) -> None:
    """
    Validate input data (required by BasePlotStrategy).

    This method wraps the internal _validate_data method to comply
    with the abstract base class interface.

    Parameters
    ----------
    df : pd.DataFrame
        Input data to validate.

    Raises
    ------
    ValueError
        If validation fails.
    """
    self._validate_data(df)

def process_data(self, df: pd.DataFrame) -> pd.DataFrame:
    """
    Process and transform data for visualization.

    This method cleans the data and builds category sets, then
    returns the cleaned DataFrame ready for visualization.

    Parameters
    ----------
    df : pd.DataFrame
        Input data.

    Returns
    -------
    pd.DataFrame
        Processed data ready for visualization.
    """
    # Clean data
    df_clean = self._clean_data(df)

    # Store category sets for use in create_figure
    self._category_sets = self._build_category_sets(df_clean)

    return df_clean

def create_figure(self, processed_df: pd.DataFrame) -> go.Figure:
    """
    Create Plotly figure from processed data.

    This method generates the UpSet plot using the previously
    built category sets.

    Parameters
    ----------
    processed_df : pd.DataFrame
        Processed data (not directly used, category sets are used).

    Returns
    -------
    go.Figure
        Configured Plotly figure with UpSet visualization.
    """
    # Generate UpSet data structure
    upset_data = from_contents(self._category_sets)

    # Create UpSet plot (matplotlib)
    upset_plot = self._create_upset_plot(upset_data)

    # Convert to Plotly
    fig = self._convert_to_plotly(upset_plot, self._category_sets)

    # Apply layout
    self._apply_layout(fig)

    return fig

def apply_filters(
    self, df: pd.DataFrame, filters: Optional[Dict[str, Any]] = None
) -> pd.DataFrame:
    """
    Apply filters to data.

    This is a common implementation that can be overridden
    by subclasses if needed.

    Parameters
    ----------
    df : pd.DataFrame
        Data to filter.
    filters : Optional[Dict[str, Any]], default=None
        Filter specifications.

    Returns
    -------
    pd.DataFrame
        Filtered data.
    """
    import logging

    logger = logging.getLogger(__name__)

    if not filters:
        logger.debug("No filters provided, returning original data")
        return df

    logger.info(
        f"Applying filters - Input shape: {df.shape}, "
        f"Columns: {df.columns.tolist()}"
    )
    logger.info(f"Filters to apply: {filters}")

    filtered_df = df.copy()

    # Get filter configurations
    filter_configs = self.config.get("filters", [])

    for filter_config in filter_configs:
        filter_id = filter_config.get("filter_id")
        filter_type = filter_config.get("type")

        if filter_id not in filters:
            continue

        filter_value = filters[filter_id]
        data_binding = filter_config.get("data_binding", {})
        column = data_binding.get("column")

        if not column or column not in filtered_df.columns:
            logger.warning(
                f"Filter '{filter_id}': Column '{column}' not found. "
                f"Available: {filtered_df.columns.tolist()}"
            )
            continue

        # Apply range filter
        if filter_type == "range" and isinstance(filter_value, list):
            min_val, max_val = filter_value
            logger.info(
                f"Applying range filter on '{column}': " f"[{min_val}, {max_val}]"
            )
            filtered_df = filtered_df[
                (filtered_df[column] >= min_val) & (filtered_df[column] <= max_val)
            ]
            logger.info(f"After filter: {len(filtered_df)} rows remaining")

    logger.info(f"Final filtered shape: {filtered_df.shape}")
    return filtered_df

def apply_customizations(
    self, fig: go.Figure, customizations: Optional[Any] = None
) -> go.Figure:
    """
    Apply custom styling to figure.

    This is a hook for future customization features
    (FLEXIVEL and FLEXIVEL2).

    Parameters
    ----------
    fig : go.Figure
        Base figure.
    customizations : Optional[Any], default=None
        Customization specifications.

    Returns
    -------
    go.Figure
        Customized figure.
    """
    # Hook for future implementation
    return fig

def generate_plot(
    self,
    data: pd.DataFrame,
    filters: Optional[Dict[str, Any]] = None,
    customizations: Optional[Any] = None,
) -> go.Figure:
    """
    Generate complete plot (Template Method).

    This method orchestrates the entire plot generation process:
    1. Validate input data
    2. Process data
    3. Apply filters
    4. Create figure
    5. Apply customizations

    Parameters
    ----------
    data : pd.DataFrame
        Input data.
    filters : Optional[Dict[str, Any]], default=None
        Filters to apply.
    customizations : Optional[Any], default=None
        Customizations to apply.

    Returns
    -------
    go.Figure
        Complete Plotly figure.

    Raises
    ------
    ValueError
        If validation fails.
    """
    # 1. Validate
    self.validate_data(data)

    # 2. Process
    processed_df = self.process_data(data)

    # 3. Filter
    filtered_df = self.apply_filters(processed_df, filters)

    # 4. Create figure
    figure = self.create_figure(filtered_df)

    # 5. Apply customizations (hook for future)
    figure = self.apply_customizations(figure, customizations)

    return figure