feat: mcda impact analysis by perspective

Author: rebecamurillo

demo_mcda.ipynb

@@ -9,7 +9,7 @@
     },
     {
       "cell_type": "code",
-      "execution_count": 1,
+      "execution_count": null,
       "id": "62a72ef0",
       "metadata": {},
       "outputs": [
@@ -203,7 +203,8 @@
         "from src.sum_impact_assessment.utils.tools import load_living_labs_from_file, load_measures_from_file, load_kpis_from_file, load_kpi_groups_from_file\n",
         "from src.sum_impact_assessment.models import KPIImpactAnalyzer, PrometheeGaiaAnalyzer\n",
         "from src.sum_impact_assessment.schemas.mcda import Goal, Alternative\n",
-        "from src.sum_impact_assessment.schemas.impact_analysis import MeasureImpactCoefficient, LivingLabImpactError, KPIGroupImpactOutput\n",
+        "from src.sum_impact_assessment.schemas.impact_analysis import KPIGroupImpactOutput\n",
+        "from src.sum_impact_assessment.schemas.mcda import MCDAAnalysisOutput\n",
         "\n",
         "\n",
         "from pandas import DataFrame, concat\n",
@@ -296,7 +297,15 @@
         "\n",
         "alts_df = DataFrame(alts_data)\n",
         "alts_df.to_csv(\n",
-        "    f\"{file_dir}/promethee_goals_alternatives_matrix.csv\", index=False)"
+        "    f\"{file_dir}/promethee_goals_alternatives_matrix.csv\", index=False)\n",
+        "\n",
+        "analyzer = PrometheeGaiaAnalyzer(\n",
+        "    goals=goals, alternatives=business_alternatives)\n",
+        "\n",
+        "# Get complete structured output with standardized keys\n",
+        "print(\"Running complete PROMETHEE-GAIA analysis with structured output...\")\n",
+        "mcda_output: MCDAAnalysisOutput = analyzer.run_analysis(\n",
+        "    run_visualizations=False)"
       ]
     },
     {

src/sum_impact_assessment/api/routes/jobs.py

@@ -1,13 +1,13 @@
 """
 Job management API routes.
 """
-from fastapi import APIRouter, Depends, HTTPException, BackgroundTasks, status as api_status, Query
+from fastapi import APIRouter, Body, Depends, HTTPException, BackgroundTasks, status as api_status, Query
 from sqlalchemy.orm import Session
 from typing import List, Optional
 from datetime import datetime
 from ...database.connection import get_db, get_db_session
 from ...repositories.job_repository import JobRepository
-from ...schemas.job import JobNameEnum, JobRunResponse
+from ...schemas.job import JobNameEnum, JobRunResponse, TriggerJobRequest
 from ...jobs import get_job_class
 from ...utils.logger import get_logger
 
@@ -18,19 +18,21 @@
 router = APIRouter(prefix="/jobs")
 
 
-def execute_job_in_background(job_name: JobNameEnum, job_id: str):
+def execute_job_in_background(job_name: JobNameEnum, job_id: str, params: Optional[dict] = None):
     """
     Execute a job in the background.
 
     Args:
         job_name: The name of the job to execute
         job_id: The UUID of the job run to track
+        params: Optional parameters for the job
     """
     logger.info(
         f"Background task started for job",
         extra={
             "job_name": job_name.value,
-            "job_id": job_id
+            "job_id": job_id,
+            "params": params
         }
     )
 
@@ -39,7 +41,7 @@ def execute_job_in_background(job_name: JobNameEnum, job_id: str):
         try:
             # Get the job class and execute
             job_class = get_job_class(job_name)
-            job_class.run(job_id=job_id, db=db)
+            job_class.run(job_id=job_id, db=db, params=params)
         except Exception as e:
             logger.error(
                 f"Background job execution failed",
@@ -56,6 +58,65 @@ def execute_job_in_background(job_name: JobNameEnum, job_id: str):
 def trigger_job(
     job_name: JobNameEnum,
     background_tasks: BackgroundTasks,
+    request: Optional[TriggerJobRequest] = Body(
+        None,
+        openapi_examples={
+            "no_params": {
+                "summary": "No parameters",
+                "description": "Run job with default settings",
+                "value": None
+            },
+            "kpi_group_filter": {
+                "summary": "Filter by KPI group",
+                "description": "Run MCDA analysis for specific KPI group only",
+                "value": {
+                    "params": {
+                        "kpi_group_id": "MCDA_GOALS"
+                    }
+                }
+            },
+            "mcda_regulatory_perspective": {
+                "summary": "MCDA Analysis for regulatory perspective",
+                "description": "Run MCDA analysis with regulatory stakeholder weights",
+                "value": {
+                    "params": {
+                        "kpi_group_id": "MCDA_GOALS",
+                        "perspective": "regulatory"
+                    }
+                }
+            },
+            "mcda_pto_perspective": {
+                "summary": "MCDA Analysis for PTO perspective",
+                "description": "Run MCDA analysis with PTO stakeholder weights",
+                "value": {
+                    "params": {
+                        "kpi_group_id": "MCDA_GOALS",
+                        "perspective": "pto"
+                    }
+                }
+            },
+            "mcda_citizens_users_perspective": {
+                "summary": "MCDA Analysis for citizens/users perspective",
+                "description": "Run MCDA analysis with citizens/users stakeholder weights",
+                "value": {
+                    "params": {
+                        "kpi_group_id": "MCDA_GOALS",
+                        "perspective": "citizens_users"
+                    }
+                }
+            },
+            "mcda_nsm_providers_perspective": {
+                "summary": "MCDA Analysis for NSM providers perspective",
+                "description": "Run MCDA analysis with NSM providers stakeholder weights",
+                "value": {
+                    "params": {
+                        "kpi_group_id": "MCDA_GOALS",
+                        "perspective": "nsm_providers"
+                    }
+                }
+            }
+        }
+    ),
     db: Session = Depends(get_db)
 ):
     """
@@ -67,6 +128,7 @@ def trigger_job(
     Args:
         job_name: Name of the job to trigger (must be a valid JobNameEnum value)
         background_tasks: FastAPI background tasks manager
+        request: Optional request body with job parameters
         db: Database session (injected)
 
     Returns:
@@ -76,8 +138,9 @@ def trigger_job(
         HTTPException 404: If the job name is not found in the registry
         HTTPException 500: If there's a database error
     """
+    params = request.params if request else None
     logger.info(f"Job trigger request received",
-                extra={"job_name": job_name.value})
+                extra={"job_name": job_name.value, "params": params})
 
     try:
         # Verify the job exists in the registry
@@ -91,21 +154,29 @@ def trigger_job(
             )
 
         # Create a new job run with PENDING status
+        # For MCDA analysis, append perspective to job name if provided
         job_repo = JobRepository(db)
-        job_run = job_repo.create_job_run(job_name=job_name.value)
+        actual_job_name = job_name.value
+
+        if job_name == JobNameEnum.MCDA_ANALYSIS and params and "perspective" in params:
+            perspective = params["perspective"]
+            actual_job_name = f"{job_name.value}_{perspective}"
+            logger.info(f"MCDA job with perspective: {perspective}")
+
+        job_run = job_repo.create_job_run(job_name=actual_job_name)
 
         logger.info(
             f"Job run created",
             extra={
-                "job_name": job_name.value,
+                "job_name": actual_job_name,
                 "job_id": job_run.id,
                 "status": job_run.status
             }
         )
 
         # Schedule the job for background execution
         background_tasks.add_task(
-            execute_job_in_background, job_name, job_run.id)
+            execute_job_in_background, job_name, job_run.id, params)
 
         logger.info(
             f"Job scheduled for background execution",

src/sum_impact_assessment/data/mcda_goal_weights.json

@@ -0,0 +1,22 @@
+{
+  "regulatory": {
+    "Improve Safety": 0.4,
+    "Improve Public Transport": 0.3,
+    "Improve Accessibility": 0.3
+  },
+  "pto": {
+    "Improve Safety": 0.3,
+    "Improve Public Transport": 0.4,
+    "Improve Accessibility": 0.3
+  },
+  "nsm_providers": {
+    "Improve Safety": 0.4,
+    "Improve Public Transport": 0.3,
+    "Improve Accessibility": 0.3
+  },
+  "citizens_users": {
+    "Improve Safety": 0.3,
+    "Improve Public Transport": 0.3,
+    "Improve Accessibility": 0.4
+  }
+}

src/sum_impact_assessment/jobs/__init__.py

@@ -3,11 +3,13 @@
 """
 from typing import Dict, Type
 from ..services.kpi_measures_analysis_job import KpiMeasuresAnalysisJob
+from ..services.mcda_analysis_job import MCDAAnalysisJob
 from ..schemas.job import JobNameEnum
 
 # Job registry mapping job names to job classes
 JOB_REGISTRY: Dict[JobNameEnum, Type] = {
-    JobNameEnum.KPI_MEASURES_ANALYSIS: KpiMeasuresAnalysisJob
+    JobNameEnum.KPI_MEASURES_ANALYSIS: KpiMeasuresAnalysisJob,
+    JobNameEnum.MCDA_ANALYSIS: MCDAAnalysisJob
 }
 
 

src/sum_impact_assessment/schemas/job.py

@@ -3,7 +3,7 @@
 """
 from pydantic import BaseModel, Field
 from datetime import datetime
-from typing import Optional
+from typing import Optional, Dict
 from enum import Enum
 
 
@@ -12,6 +12,7 @@ class JobNameEnum(str, Enum):
     Enumeration of valid job names.
     """
     KPI_MEASURES_ANALYSIS = "kpi_measures_analysis"
+    MCDA_ANALYSIS = "mcda_analysis"
 
 
 class JobStatusEnum(str, Enum):
@@ -24,6 +25,26 @@ class JobStatusEnum(str, Enum):
     FAILURE = "FAILURE"
 
 
+class TriggerJobRequest(BaseModel):
+    """
+    Request schema for triggering a job with optional parameters.
+    """
+    params: Optional[Dict] = Field(
+        None,
+        description="Optional job-specific parameters. For mcda_analysis: {'kpi_group_id': 'MCDA_GOALS'}"
+    )
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "params": {
+                    "kpi_group_id": "MCDA_GOALS",
+                    "perspective": "regulatory"
+                }
+            }
+        }
+
+
 class JobRunResponse(BaseModel):
     """
     Response schema for job run information.