Technical Documentation: Alive-Book Visualization System

Technical Documentation: Alive-Book Visualization System#

Overview#

This document provides comprehensive technical documentation for the Alive-Book visualization system, detailing the architecture, data flow, visualization components, and technical implementation details. The system enables interactive exploration of corporate social responsibility metrics derived from the Alive Standards framework.

System Architecture#

The visualization system follows a modular architecture with the following components:

┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│   Data Layer  │────►│ Processing    │────►│ Visualization │
│   (Sources)   │     │ Pipeline      │     │ Layer         │
└───────────────┘     └───────────────┘     └───────────────┘
                                                    │
                                                    ▼
                                            ┌───────────────┐
                                            │ Interactive   │
                                            │ Dashboard     │
                                            └───────────────┘

Data Layer#

  • Excel Data Source: Contains WEF Partner company data with sustainability metrics

  • PDF Insights: Text-based insights from the Alive Analysis document

Processing Pipeline#

  • Data Extraction: Loads and parses data from the source files

  • Data Transformation: Converts, cleans, and prepares data for visualization

  • Metric Calculation: Computes derived metrics (SRI, PSI) from raw data

  • Anomaly Detection: Applies machine learning to identify outliers

Visualization Layer#

  • Chart Components: Modular visualization functions for different analysis types

  • Design System: Consistent styling, typography, and color scheme

  • Responsive Design: Adaptable layouts for different screen sizes

Interactive Dashboard#

  • Filtering Controls: Industry, year, and company selectors

  • Linked Views: Coordinated visualizations that update together

  • Tooltips and Annotations: Contextual information on interaction

Data Processing#

Data Loading and Validation#

The DataProcessor class handles data loading with robust error handling:

def load_data(self):
    try:
        # Load Excel data with efficient data streaming
        self.df = pd.read_excel(self.excel_path, sheet_name="WEF Partners")
        
        # Load PDF insights
        with open(self.pdf_path, "rb") as f:
            reader = PdfReader(f)
            self.pdf_insights = " ".join([page.extract_text() for page in reader.pages[:2]])
        
        # Process the dataframe
        self._process_dataframe()
        
    except FileNotFoundError as e:
        print(f"ERROR: File not found - {e}")
        raise
    except Exception as e:
        print(f"ERROR: Failed to load data - {e}")
        raise

Metric Calculation#

The system calculates several key metrics:

Social Responsibility Index (SRI)#

SRI = (compliance_weight * compliance_score) + 
      (emissions_weight * emissions_score) + 
      (penalties_weight * penalties_score)

Where:

  • compliance_score: Alive Standards compliance (0-100)

  • emissions_score: Inverted CO2 emissions scale (higher is better)

  • penalties_score: Inverted legal penalties scale (higher is better)

Penalty Severity Index (PSI)#

PSI = log10((Total Penalties / Revenue_2024) × 10^6)

With a repeat offender multiplier of 2.5× for companies with recurring violations.

Anomaly Detection#

The system uses the Isolation Forest algorithm to detect anomalies in the dataset:

def _detect_anomalies(self):
    # Select features for anomaly detection
    features = ['CO2_Emissions', 'Legal_Penalties', 'Alive_Compliance', 'PSI']
    X = self.df[features].fillna(0)
    
    # Standardize the features
    scaler = StandardScaler()
    X_scaled = scaler.fit_transform(X)
    
    # Apply Isolation Forest
    model = IsolationForest(contamination=0.1, random_state=42)
    self.df['Anomaly'] = model.fit_predict(X_scaled)
    
    # Convert to binary labels (1: normal, -1: anomaly)
    self.df['Anomaly'] = self.df['Anomaly'].map({1: 'Normal', -1: 'Anomaly'})

Visualization Components#

Risk Matrix#

The risk matrix plots companies based on their compliance scores and legal penalties, with bubble size representing CO2 emissions:

def create_risk_matrix(df, selected_industries=None, year=2024):
    # Filter data
    filtered_df = df.copy()
    if selected_industries:
        filtered_df = filtered_df[filtered_df['Industry'].isin(selected_industries)]
    
    # Create the scatter plot
    fig = px.scatter(
        filtered_df,
        x='Alive_Compliance',
        y='Legal_Penalties',
        size='CO2_Emissions',
        color='Industry',
        color_discrete_map=INDUSTRY_COLORS,
        hover_name='Company Name',
        title=f'Social Responsibility Risk Matrix {year}'
    )
    
    # Add quadrant lines and annotations
    # ...
    
    return fig

Risk Heatmap#

The heatmap visualizes multiple risk dimensions across companies:

def create_risk_heatmap(df, selected_industries=None):
    # Prepare risk metrics
    risk_metrics = {
        'CO2 Risk': 100 - normalized_co2_emissions,
        'Legal Risk': normalized_legal_penalties,
        'Compliance Risk': 100 - compliance_scores,
        'Social Index Risk': 100 - sri_scores
    }
    
    # Create heatmap
    fig = go.Figure(data=go.Heatmap(
        z=z_values,
        x=risk_factors,
        y=companies,
        colorscale=[
            [0, COLOR_PALETTE["success"]],
            [0.5, COLOR_PALETTE["warning"]],
            [1, COLOR_PALETTE["danger"]]
        ]
    ))
    
    return fig

Emissions Chart#

The emissions chart compares CO2 emissions across industries:

def create_emissions_chart(df, selected_industries=None):
    # Group by industry and calculate total emissions
    industry_emissions = filtered_df.groupby('Industry')['CO2_Emissions'].sum().reset_index()
    
    # Calculate the percentage of total emissions
    total_emissions = industry_emissions['CO2_Emissions'].sum()
    industry_emissions['Percentage'] = (industry_emissions['CO2_Emissions'] / total_emissions * 100)
    
    # Create the bar chart
    fig = go.Figure()
    fig.add_trace(go.Bar(
        x=industry_emissions['Industry'],
        y=industry_emissions['CO2_Emissions'],
        text=industry_emissions['Percentage'].map('{:.1f}%'.format)
    ))
    
    return fig

Radar Chart#

The radar chart shows circular economy dimensions for specific companies:

def create_radar_chart(df, company_name):
    # Define circular economy dimensions
    dimensions = [
        'Waste Management', 
        'Resource Consumption',
        'Recycling & Recovery',
        'Eco-design',
        'Product Lifecycle',
        'Supply Chain Management'
    ]
    
    # Create the radar chart
    fig = go.Figure()
    fig.add_trace(go.Scatterpolar(
        r=r_values,
        theta=theta,
        fill='toself',
        name=company_name
    ))
    
    return fig

Parallel Coordinates#

The parallel coordinates plot visualizes anomalies and multidimensional relationships:

def create_parallel_coordinates(df):
    # Apply log transform for better visualization
    plot_df['CO2_Emissions_log'] = np.log1p(plot_df['CO2_Emissions'])
    plot_df['Legal_Penalties_log'] = np.log1p(plot_df['Legal_Penalties'])
    
    # Create the parallel coordinates plot
    fig = px.parallel_coordinates(
        plot_df,
        dimensions=[
            'Alive_Compliance',
            'Legal_Penalties_log',
            'CO2_Emissions_log',
            'PSI',
            'SRI'
        ],
        color='Anomaly'
    )
    
    return fig

Interactive Dashboard#

The interactive dashboard integrates all visualization components with filtering controls:

# Define dashboard layout
app.layout = html.Div([
    # Header
    html.Div([
        html.H1("Alive Standards Compliance Dashboard")
    ]),
    
    # Control Panel
    html.Div([
        # Industry Filter
        html.Div([
            html.Label("Filter by Industry:"),
            dcc.Dropdown(
                id='industry-filter',
                options=[{'label': i, 'value': i} for i in sorted(df['Industry'].unique())],
                multi=True,
                value=['Energy', 'Technology']
            )
        ]),
        
        # Year Slider
        html.Div([
            html.Label("Select Year:"),
            dcc.Slider(
                id='year-slider',
                min=2023,
                max=2024,
                value=2024,
                marks={2023: '2023', 2024: '2024'}
            )
        ]),
        
        # Company Selection
        html.Div([
            html.Label("Select Company:"),
            dcc.Dropdown(
                id='company-selector',
                options=[{'label': name, 'value': name} for name in sorted(df['Company Name'].unique())]
            )
        ])
    ]),
    
    # Visualization Panels
    html.Div([
        # Risk Matrix Panel
        html.Div([
            html.H2("Risk Matrix"),
            dcc.Graph(id='risk-matrix')
        ]),
        
        # Other visualization panels...
    ])
])

# Define callback for updating charts
@app.callback(
    [Output('risk-matrix', 'figure'),
     Output('risk-heatmap', 'figure'),
     Output('emissions-chart', 'figure'),
     Output('radar-chart', 'figure'),
     Output('parallel-chart', 'figure')],
    [Input('industry-filter', 'value'),
     Input('year-slider', 'value'),
     Input('company-selector', 'value')]
)
def update_charts(selected_industries, year, company_name):
    # Update risk matrix
    risk_matrix = create_risk_matrix(df, selected_industries, year)
    
    # Update other charts...
    
    return risk_matrix, risk_heatmap, emissions_chart, radar_chart, parallel_chart

Design System#

The visualization system implements a consistent design system with the following components:

Color Palette#

COLOR_PALETTE = {
    "primary": "#2E5EAA",      # Primary blue for main elements
    "secondary": "#5E366E",    # Secondary purple for accents
    "accent": "#F08B33",       # Orange accent for highlights
    "background": "#F9F9F9",   # Light background
    "text": "#333333",         # Dark text
    "success": "#3AA655",      # Green for positive metrics
    "warning": "#FFC857",      # Yellow for medium risk
    "danger": "#D64045",       # Red for high risk
    "neutral": "#7D8491"       # Gray for neutral elements
}

Typography#

TITLE_FONT = {
    "family": "Arial, sans-serif",
    "size": 22,
    "color": COLOR_PALETTE["text"]
}

AXIS_FONT = {
    "family": "Arial, sans-serif",
    "size": 14,
    "color": COLOR_PALETTE["text"]
}

Chart Template#

CHART_TEMPLATE = {
    "layout": go.Layout(
        paper_bgcolor=COLOR_PALETTE["background"],
        plot_bgcolor=COLOR_PALETTE["background"],
        font={"family": "Arial, sans-serif", "color": COLOR_PALETTE["text"]},
        margin=dict(l=60, r=30, t=80, b=60),
        legend=dict(
            orientation="h", 
            yanchor="bottom", 
            y=1.02, 
            xanchor="right", 
            x=1
        ),
        xaxis=dict(
            showgrid=True,
            gridcolor="#EEEEEE"
        ),
        yaxis=dict(
            showgrid=True,
            gridcolor="#EEEEEE"
        )
    )
}

Performance Optimizations#

Several optimizations have been implemented to ensure smooth performance:

  1. Efficient Data Loading: Data is loaded with optimized streaming to handle large files

  2. Data Caching: Processed data is cached to avoid redundant calculations

  3. WebGL Rendering: Large datasets use WebGL acceleration for better performance

  4. Responsive Techniques: Visualizations adapt to different screen sizes and devices

  5. Error Handling: Robust error handling prevents crashes and provides meaningful feedback

Cross-Browser Compatibility#

The visualization system has been tested across multiple browsers to ensure consistent rendering:

Browser

Version

Compatibility

Chrome

100+

Full

Firefox

95+

Full

Safari

15+

Full

Edge

99+

Full

Accessibility#

The dashboard implements various accessibility features:

  1. Color Contrast: All text meets WCAG 2.1 AA standards for contrast

  2. Screen Reader Support: Semantic HTML structure for navigation

  3. Keyboard Navigation: All interactive elements are keyboard accessible

  4. Text Alternatives: Non-text content has text alternatives

  5. Responsive Design: Content adapts to different viewport sizes and zoom levels

Future Enhancements#

Recommended future enhancements include:

  1. Real-Time Data Integration:

    • Integration with streaming data sources using Apache Kafka

    • Live updating visualizations without page refresh

  2. Advanced Analytics:

    • Expanded machine learning capabilities for predictive risk assessment

    • Time-series forecasting of environmental metrics

    • Causal inference modeling for policy impact analysis

  3. Enhanced Visualization Types:

    • Supply chain network graphs showing interconnections between companies

    • Geospatial visualizations of environmental impact

    • Hierarchical tree maps for categorizing companies by risk profiles

  4. Export and Reporting:

    • PDF report generation with key insights

    • Excel export of filtered data views

    • Scheduled email reports with visualization snapshots

  5. Mobile Optimization:

    • Touch-optimized interactions for mobile devices

    • Progressive Web App capabilities for offline access

    • Responsive layouts optimized for small screens

Technical Requirements#

Dependencies#

jupyter-book>=0.13.0
matplotlib>=3.5.0
numpy>=1.21.0
ghp-import>=2.0.0
plotly>=5.14.0
dash>=2.9.0
PyPDF2>=3.0.0
jupyter-dash>=0.4.0
openpyxl>=3.1.0
pandas>=1.5.0
scikit-learn>=1.2.0

Environment Setup#

name: alive-env
channels:
  - conda-forge
dependencies:
  - python=3.9
  - jupyter-book>=0.13.0
  - matplotlib>=3.5.0
  - numpy>=1.21.0
  - ghp-import>=2.0.0
  - plotly>=5.14.0
  - dash>=2.9.0
  - PyPDF2>=3.0.0
  - jupyter-dash>=0.4.0
  - openpyxl>=3.1.0
  - pandas>=1.5.0
  - scikit-learn>=1.2.0