xplia 1.0.1__py3-none-any.whl

xplia/visualizations/base.py

@@ -0,0 +1,256 @@
+"""
+Classes de base pour les visualisations XPLIA
+============================================
+
+Ce module définit les classes de base pour les visualiseurs de XPLIA,
+assurant une interface cohérente pour toutes les visualisations.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional, List, Union
+import logging
+
+from ..core.enums import AudienceLevel
+from ..core.models import ExplanationResult
+
+
+class VisualizerBase(ABC):
+    """
+    Classe de base abstraite pour tous les visualiseurs XPLIA.
+    
+    Cette classe définit l'interface commune que tous les visualiseurs doivent implémenter,
+    garantissant une expérience cohérente pour l'utilisateur final.
+    
+    Attributs:
+        _logger: Logger pour la traçabilité
+        _supported_libraries: Bibliothèques de visualisation supportées
+        _default_library: Bibliothèque de visualisation par défaut
+        _theme: Thème de visualisation
+        _color_palette: Palette de couleurs
+        _interactive: Si les visualisations doivent être interactives
+    """
+    
+    def __init__(self, library: str = "plotly", theme: str = "light", 
+                 color_palette: Optional[List[str]] = None, interactive: bool = True):
+        """
+        Initialise le visualiseur.
+        
+        Args:
+            library: Bibliothèque de visualisation à utiliser ('plotly', 'matplotlib', 'd3')
+            theme: Thème de visualisation ('light', 'dark', 'corporate', etc.)
+            color_palette: Palette de couleurs personnalisée
+            interactive: Si les visualisations doivent être interactives
+        """
+        self._logger = logging.getLogger(__name__)
+        self._supported_libraries = ["plotly", "matplotlib", "d3"]
+        self._default_library = "plotly"
+        
+        # Vérifier si la bibliothèque demandée est supportée
+        if library not in self._supported_libraries:
+            self._logger.warning(f"Bibliothèque {library} non supportée. Utilisation de {self._default_library}.")
+            self._library = self._default_library
+        else:
+            self._library = library
+        
+        self._theme = theme
+        self._color_palette = color_palette or [
+            "#636EFA", "#EF553B", "#00CC96", "#AB63FA", "#FFA15A", 
+            "#19D3F3", "#FF6692", "#B6E880", "#FF97FF", "#FECB52"
+        ]
+        self._interactive = interactive
+    
+    @abstractmethod
+    def visualize(self, explanation_result: ExplanationResult, audience_level: AudienceLevel = AudienceLevel.TECHNICAL, **kwargs) -> Any:
+        """
+        Génère une visualisation à partir d'un résultat d'explication.
+        
+        Args:
+            explanation_result: Résultat d'explication à visualiser
+            audience_level: Niveau d'audience ciblé
+            **kwargs: Paramètres additionnels spécifiques à la visualisation
+            
+        Returns:
+            Any: Objet de visualisation (figure, HTML, etc.)
+        """
+        pass
+    
+    def _adapt_to_audience(self, figure: Any, audience_level: AudienceLevel) -> Any:
+        """
+        Adapte une visualisation au niveau d'audience spécifié.
+        
+        Args:
+            figure: Visualisation à adapter
+            audience_level: Niveau d'audience ciblé
+            
+        Returns:
+            Any: Visualisation adaptée
+        """
+        # Implémentation par défaut (à surcharger dans les sous-classes)
+        if self._library == "plotly":
+            import plotly.graph_objects as go
+            
+            if isinstance(figure, go.Figure):
+                # Ajuster la complexité selon le niveau d'audience
+                if audience_level == AudienceLevel.PUBLIC:
+                    # Simplifier au maximum
+                    figure.update_layout(
+                        showlegend=True,
+                        legend=dict(orientation="h"),
+                        margin=dict(l=40, r=40, t=50, b=40),
+                    )
+                    # Supprimer les annotations techniques
+                    figure.update_layout(annotations=[])
+                    
+                elif audience_level == AudienceLevel.BUSINESS:
+                    # Niveau intermédiaire
+                    figure.update_layout(
+                        showlegend=True,
+                        legend=dict(orientation="h"),
+                        margin=dict(l=40, r=40, t=50, b=40),
+                    )
+                    
+                # Pour AudienceLevel.TECHNICAL, on garde tous les détails
+        
+        return figure
+    
+    def _set_theme(self, figure: Any) -> Any:
+        """
+        Applique le thème configuré à une visualisation.
+        
+        Args:
+            figure: Visualisation à thématiser
+            
+        Returns:
+            Any: Visualisation thématisée
+        """
+        if self._library == "plotly":
+            import plotly.graph_objects as go
+            
+            if isinstance(figure, go.Figure):
+                if self._theme == "dark":
+                    figure.update_layout(
+                        template="plotly_dark",
+                        paper_bgcolor="#222",
+                        plot_bgcolor="#222",
+                        font=dict(color="#fff")
+                    )
+                elif self._theme == "light":
+                    figure.update_layout(
+                        template="plotly_white",
+                        paper_bgcolor="#fff",
+                        plot_bgcolor="#f8f9fa",
+                        font=dict(color="#333")
+                    )
+                elif self._theme == "corporate":
+                    figure.update_layout(
+                        template="plotly_white",
+                        paper_bgcolor="#f8f9fa",
+                        plot_bgcolor="#f8f9fa",
+                        font=dict(family="Arial, sans-serif", color="#333")
+                    )
+        
+        elif self._library == "matplotlib":
+            import matplotlib.pyplot as plt
+            
+            if self._theme == "dark":
+                plt.style.use("dark_background")
+            elif self._theme == "light":
+                plt.style.use("default")
+            elif self._theme == "corporate":
+                plt.style.use("seaborn-v0_8-whitegrid")
+        
+        return figure
+    
+    def _apply_color_palette(self, figure: Any) -> Any:
+        """
+        Applique la palette de couleurs configurée à une visualisation.
+        
+        Args:
+            figure: Visualisation à colorer
+            
+        Returns:
+            Any: Visualisation colorée
+        """
+        if self._library == "plotly":
+            import plotly.graph_objects as go
+            
+            if isinstance(figure, go.Figure):
+                # Appliquer la palette aux traces
+                for i, trace in enumerate(figure.data):
+                    color_idx = i % len(self._color_palette)
+                    if hasattr(trace, "marker") and trace.marker:
+                        trace.marker.color = self._color_palette[color_idx]
+                    elif hasattr(trace, "line") and trace.line:
+                        trace.line.color = self._color_palette[color_idx]
+                    elif hasattr(trace, "fillcolor"):
+                        trace.fillcolor = self._color_palette[color_idx]
+        
+        elif self._library == "matplotlib":
+            import matplotlib.pyplot as plt
+            
+            # Définir la palette de couleurs pour matplotlib
+            plt.rcParams["axes.prop_cycle"] = plt.cycler(color=self._color_palette)
+        
+        return figure
+    
+    def save(self, figure: Any, filename: str, **kwargs) -> None:
+        """
+        Sauvegarde une visualisation dans un fichier.
+        
+        Args:
+            figure: Visualisation à sauvegarder
+            filename: Nom du fichier de sortie
+            **kwargs: Paramètres additionnels pour la sauvegarde
+        """
+        if self._library == "plotly":
+            import plotly.graph_objects as go
+            
+            if isinstance(figure, go.Figure):
+                figure.write_html(filename, include_plotlyjs="cdn" if kwargs.get("cdn", True) else True)
+                self._logger.info(f"Visualisation sauvegardée dans {filename}")
+        
+        elif self._library == "matplotlib":
+            import matplotlib.pyplot as plt
+            
+            plt.savefig(filename, dpi=kwargs.get("dpi", 300), bbox_inches="tight")
+            self._logger.info(f"Visualisation sauvegardée dans {filename}")
+        
+        elif self._library == "d3":
+            # Pour D3.js, on sauvegarde le HTML généré
+            with open(filename, "w", encoding="utf-8") as f:
+                f.write(figure)
+            self._logger.info(f"Visualisation sauvegardée dans {filename}")
+    
+    def _check_dependencies(self) -> bool:
+        """
+        Vérifie si les dépendances nécessaires sont installées.
+        
+        Returns:
+            bool: True si toutes les dépendances sont disponibles
+        """
+        if self._library == "plotly":
+            try:
+                import plotly
+                return True
+            except ImportError:
+                self._logger.error("La bibliothèque plotly n'est pas installée. Utilisez 'pip install plotly'.")
+                return False
+        
+        elif self._library == "matplotlib":
+            try:
+                import matplotlib
+                return True
+            except ImportError:
+                self._logger.error("La bibliothèque matplotlib n'est pas installée. Utilisez 'pip install matplotlib'.")
+                return False
+        
+        elif self._library == "d3":
+            # Pour D3.js, on vérifie si les templates sont disponibles
+            try:
+                from ..templates import d3_templates
+                return True
+            except ImportError:
+                self._logger.error("Les templates D3.js ne sont pas disponibles.")
+                return False
+        
+        return False

xplia/visualizations/boxplot_chart.py

@@ -0,0 +1,224 @@
+"""
+Implémentation des box plots (boîtes à moustaches) pour XPLIA
+"""
+
+def create_boxplot_chart(data, config, library="plotly", **kwargs):
+    """
+    Crée un box plot (boîte à moustaches) avec la bibliothèque spécifiée.
+    
+    Args:
+        data: Données pour le graphique
+        config: Configuration du graphique
+        library: Bibliothèque à utiliser
+        **kwargs: Arguments spécifiques au type de graphique
+        
+    Returns:
+        Objet graphique selon la bibliothèque utilisée
+    """
+    if library == "plotly":
+        return _create_plotly_boxplot_chart(data, config, **kwargs)
+    elif library == "matplotlib":
+        return _create_mpl_boxplot_chart(data, config, **kwargs)
+    elif library == "bokeh":
+        return _create_bokeh_boxplot_chart(data, config, **kwargs)
+    else:
+        raise ValueError(f"Bibliothèque {library} non supportée pour les box plots")
+
+# Implémentations spécifiques
+def _create_plotly_boxplot_chart(data, config, **kwargs):
+    """Implémentation Plotly des box plots"""
+    import plotly.graph_objects as go
+    
+    # Extraction des paramètres
+    title = config.get('title', '')
+    x_label = config.get('x_label', '')
+    y_label = config.get('y_label', '')
+    width = config.get('width', 800)
+    height = config.get('height', 500)
+    
+    # Normalisation des données d'entrée
+    if isinstance(data, dict):
+        # Format {x: [...], y: [...]} ou {data: [...], names: [...]}
+        if 'data' in data and 'names' in data:
+            # Multiple boîtes avec noms
+            y_data = data.get('data', [])
+            x_data = data.get('names', [])
+            orientation = kwargs.get('orientation', 'v')
+        elif 'y' in data:
+            # Une seule série
+            y_data = data.get('y', [])
+            x_data = data.get('x', [])
+            orientation = kwargs.get('orientation', 'v')
+        else:
+            # Dictionnaire de séries {nom_serie: données}
+            y_data = list(data.values())
+            x_data = list(data.keys())
+            orientation = kwargs.get('orientation', 'v')
+    else:
+        # Format [data1, data2, ...] ou [[data1], [data2], ...]
+        if all(isinstance(d, list) for d in data):
+            # Chaque sous-liste est un dataset
+            y_data = data
+            x_data = kwargs.get('names', [f"Série {i+1}" for i in range(len(data))])
+        else:
+            # Une seule série
+            y_data = [data]
+            x_data = kwargs.get('names', ["Données"])
+        orientation = kwargs.get('orientation', 'v')
+    
+    # Création du graphique
+    fig = go.Figure()
+    
+    # Ajout des box plots
+    if orientation == 'v':
+        for i, (y, name) in enumerate(zip(y_data if isinstance(y_data[0], list) else [y_data], 
+                                        x_data if isinstance(x_data, list) else [x_data])):
+            color = kwargs.get('colors', config.get('color_palette', []))[i % len(config.get('color_palette', ['#1f77b4']))]
+            fig.add_trace(go.Box(
+                y=y,
+                name=name,
+                boxmean=kwargs.get('boxmean', True),
+                marker_color=color,
+                line_color=kwargs.get('line_color', color),
+                fillcolor=kwargs.get('fillcolor', color),
+                opacity=kwargs.get('opacity', 0.7),
+                boxpoints=kwargs.get('boxpoints', 'outliers'),
+                jitter=kwargs.get('jitter', 0.3),
+                pointpos=kwargs.get('pointpos', -1.8),
+                orientation=orientation,
+                quartilemethod=kwargs.get('quartilemethod', 'linear')
+            ))
+    else:
+        for i, (x, name) in enumerate(zip(y_data if isinstance(y_data[0], list) else [y_data], 
+                                        x_data if isinstance(x_data, list) else [x_data])):
+            color = kwargs.get('colors', config.get('color_palette', []))[i % len(config.get('color_palette', ['#1f77b4']))]
+            fig.add_trace(go.Box(
+                x=x,
+                name=name,
+                boxmean=kwargs.get('boxmean', True),
+                marker_color=color,
+                line_color=kwargs.get('line_color', color),
+                fillcolor=kwargs.get('fillcolor', color),
+                opacity=kwargs.get('opacity', 0.7),
+                boxpoints=kwargs.get('boxpoints', 'outliers'),
+                jitter=kwargs.get('jitter', 0.3),
+                pointpos=kwargs.get('pointpos', -1.8),
+                orientation=orientation,
+                quartilemethod=kwargs.get('quartilemethod', 'linear')
+            ))
+    
+    # Configuration du layout
+    fig.update_layout(
+        title=title,
+        xaxis_title=x_label if orientation == 'v' else y_label,
+        yaxis_title=y_label if orientation == 'v' else x_label,
+        width=width,
+        height=height,
+        boxmode=kwargs.get('boxmode', 'group'),
+        boxgap=kwargs.get('boxgap', 0.1),
+        boxgroupgap=kwargs.get('boxgroupgap', 0.1)
+    )
+    
+    return fig
+
+def _create_mpl_boxplot_chart(data, config, **kwargs):
+    """Implémentation Matplotlib des box plots"""
+    import matplotlib.pyplot as plt
+    import numpy as np
+    
+    # Extraction des paramètres
+    title = config.get('title', '')
+    x_label = config.get('x_label', '')
+    y_label = config.get('y_label', '')
+    
+    # Normalisation des données (similaire à Plotly)
+    if isinstance(data, dict):
+        if 'data' in data and 'names' in data:
+            y_data = data.get('data', [])
+            x_data = data.get('names', [])
+        elif 'y' in data:
+            y_data = [data.get('y', [])]
+            x_data = [data.get('x', "")]
+        else:
+            y_data = list(data.values())
+            x_data = list(data.keys())
+    else:
+        if all(isinstance(d, list) for d in data):
+            y_data = data
+            x_data = kwargs.get('names', [f"Série {i+1}" for i in range(len(data))])
+        else:
+            y_data = [data]
+            x_data = kwargs.get('names', ["Données"])
+    
+    # Orientation
+    orientation = kwargs.get('orientation', 'v')
+    
+    # Création de la figure
+    fig, ax = plt.subplots(figsize=(
+        config.get('width', 800) / 100,
+        config.get('height', 500) / 100
+    ))
+    
+    # Options de style
+    boxprops = dict(linestyle='-', linewidth=1.5)
+    flierprops = dict(marker='o', markersize=6, markeredgecolor='black')
+    medianprops = dict(linestyle='-', linewidth=1.5, color='firebrick')
+    meanprops = dict(marker='D', markeredgecolor='black', markerfacecolor='firebrick')
+    
+    # Ajout des couleurs personnalisées si disponibles
+    colors = kwargs.get('colors', config.get('color_palette', []))
+    if colors:
+        patches = []
+        for i in range(len(y_data)):
+            color = colors[i % len(colors)]
+            bp_dict = {
+                'boxprops': dict(facecolor=color, **boxprops),
+                'flierprops': flierprops,
+                'medianprops': medianprops,
+                'meanprops': meanprops,
+                'patch_artist': True
+            }
+            patches.append(bp_dict)
+    else:
+        patches = [dict(boxprops=boxprops, flierprops=flierprops, 
+                        medianprops=medianprops, meanprops=meanprops)] * len(y_data)
+    
+    # Création du box plot
+    if orientation == 'v':
+        bp = ax.boxplot(y_data, 
+                       labels=x_data, 
+                       notch=kwargs.get('notch', False),
+                       vert=True, 
+                       patch_artist=True,
+                       showmeans=kwargs.get('boxmean', True),
+                       showfliers=kwargs.get('boxpoints', 'outliers') != 'False',
+                       widths=kwargs.get('width', 0.5))
+    else:
+        bp = ax.boxplot(y_data,
+                       labels=x_data,
+                       notch=kwargs.get('notch', False),
+                       vert=False,
+                       patch_artist=True, 
+                       showmeans=kwargs.get('boxmean', True),
+                       showfliers=kwargs.get('boxpoints', 'outliers') != 'False',
+                       widths=kwargs.get('width', 0.5))
+    
+    # Application des couleurs
+    for i, box in enumerate(bp['boxes']):
+        box_color = colors[i % len(colors)] if colors else 'lightblue'
+        box.set(facecolor=box_color, alpha=kwargs.get('opacity', 0.7))
+    
+    # Configuration des titres et labels
+    ax.set_title(title)
+    if orientation == 'v':
+        ax.set_xlabel(x_label)
+        ax.set_ylabel(y_label)
+    else:
+        ax.set_xlabel(y_label)
+        ax.set_ylabel(x_label)
+    
+    # Ajout de la grille
+    if kwargs.get('grid', True):
+        ax.grid(axis='y' if orientation == 'v' else 'x', linestyle='--', alpha=0.7)
+    
+    return fig

xplia/visualizations/charts_impl.py

@@ -0,0 +1,65 @@
+"""
+Implémentations des générateurs de graphiques pour XPLIA
+"""
+
+def create_bar_chart(data, config, library="plotly", **kwargs):
+    """
+    Crée un graphique à barres avec la bibliothèque spécifiée.
+    
+    Args:
+        data: Données pour le graphique (dict, DataFrame, etc.)
+        config: Configuration du graphique
+        library: Bibliothèque à utiliser
+        **kwargs: Arguments spécifiques au type de graphique
+        
+    Returns:
+        Objet graphique selon la bibliothèque utilisée
+    """
+    if library == "plotly":
+        return _create_plotly_bar_chart(data, config, **kwargs)
+    elif library == "matplotlib":
+        return _create_mpl_bar_chart(data, config, **kwargs)
+    elif library == "bokeh":
+        return _create_bokeh_bar_chart(data, config, **kwargs)
+    else:
+        raise ValueError(f"Bibliothèque {library} non supportée pour les graphiques à barres")
+
+# Implémentations spécifiques
+def _create_plotly_bar_chart(data, config, **kwargs):
+    """Implémentation Plotly des graphiques à barres"""
+    import plotly.graph_objects as go
+    
+    # Extraction des paramètres
+    title = config.get('title', '')
+    x_label = config.get('x_label', '')
+    y_label = config.get('y_label', '')
+    width = config.get('width', 800)
+    height = config.get('height', 500)
+    
+    # Normalisation des données d'entrée
+    x_data = data.get('x', []) if isinstance(data, dict) else data[0]
+    y_data = data.get('y', []) if isinstance(data, dict) else data[1]
+    
+    # Création du graphique
+    fig = go.Figure()
+    fig.add_trace(go.Bar(
+        x=x_data,
+        y=y_data,
+        marker_color=kwargs.get('color', config.get('color_palette', ['#1f77b4'])[0]),
+        name=kwargs.get('name', ''),
+        text=kwargs.get('text', None),
+        textposition=kwargs.get('textposition', 'auto'),
+    ))
+    
+    # Configuration du layout
+    fig.update_layout(
+        title=title,
+        xaxis_title=x_label,
+        yaxis_title=y_label,
+        width=width,
+        height=height,
+        bargap=kwargs.get('bargap', 0.2),
+        bargroupgap=kwargs.get('bargroupgap', 0.1)
+    )
+    
+    return fig