=====================
What-If Analysis
=====================

The What-If Studio enables scenario-based model exploration. Create
alternative scenarios by changing feature values and compare prediction
outcomes side-by-side.

.. contents:: Sections
   :local:
   :depth: 2

Overview
--------

What-If Analysis lets you answer questions like:

- "What would happen if this customer's tenure increased from 3 to 24 months?"
- "How does changing the contract type affect churn probability?"
- "Which features have the most impact on the prediction?"

The workflow is:

1. **Create a session** tied to a deployed model and baseline input
2. **Add scenarios** with modified feature values
3. **Run scenarios** to get predictions
4. **Compare** all scenarios against the baseline

----

Creating a Session
------------------

A session is tied to a deployment and requires a baseline set of feature
values (the "current state" you want to explore alternatives for):

.. code-block:: python

   resp = requests.post(f"{BASE_URL}/api/studio/sessions", headers=HEADERS, json={
       "project_id": project_id,
       "deployment_id": deployment_id,
       "baseline_input": {
           "tenure_months": 3,
           "monthly_charges": 75.0,
           "contract": "Month-to-month",
           "payment_method": "Electronic check",
           "internet_service": "Fiber optic",
           "online_security": "No",
       },
   })
   session_id = resp.json()["id"]

Getting the Feature Schema
^^^^^^^^^^^^^^^^^^^^^^^^^^

Before creating sessions, retrieve the expected features for a
deployment:

.. code-block:: python

   resp = requests.get(
       f"{BASE_URL}/api/studio/deployments/{deployment_id}/schema",
       headers=HEADERS,
   )
   schema = resp.json()
   for feat in schema["features"]:
       print(f"  {feat['name']}: {feat['dtype']} (values: {feat.get('domain', 'numeric')})")

----

Adding Scenarios
----------------

Each scenario modifies one or more features from the baseline:

.. code-block:: python

   # Scenario 1: longer tenure
   resp = requests.post(
       f"{BASE_URL}/api/studio/sessions/{session_id}/scenarios",
       headers=HEADERS,
       json={
           "name": "Longer tenure (24 months)",
           "changes": {"tenure_months": 24},
       },
   )
   scenario_1_id = resp.json()["id"]

   # Scenario 2: switch to annual contract
   resp = requests.post(
       f"{BASE_URL}/api/studio/sessions/{session_id}/scenarios",
       headers=HEADERS,
       json={
           "name": "Annual contract + security",
           "changes": {
               "contract": "One year",
               "online_security": "Yes",
           },
       },
   )
   scenario_2_id = resp.json()["id"]

   # Scenario 3: premium package
   resp = requests.post(
       f"{BASE_URL}/api/studio/sessions/{session_id}/scenarios",
       headers=HEADERS,
       json={
           "name": "Premium package",
           "changes": {
               "contract": "Two year",
               "monthly_charges": 110.0,
               "online_security": "Yes",
               "internet_service": "Fiber optic",
           },
       },
   )
   scenario_3_id = resp.json()["id"]

----

Running Scenarios
-----------------

Execute each scenario to get predictions:

.. code-block:: python

   for sid in [scenario_1_id, scenario_2_id, scenario_3_id]:
       requests.post(
           f"{BASE_URL}/api/studio/scenarios/{sid}/run",
           headers=HEADERS,
       )

----

Comparing Results
-----------------

Compare all scenarios against the baseline:

.. code-block:: python

   resp = requests.get(
       f"{BASE_URL}/api/studio/sessions/{session_id}/compare",
       headers=HEADERS,
   )
   comparison = resp.json()

   baseline = comparison["baseline"]
   print(f"Baseline prediction: {baseline['prediction']}")
   print(f"Baseline probabilities: {baseline.get('probabilities', {})}")

   for scenario in comparison["scenarios"]:
       print(f"\n{scenario['name']}:")
       print(f"  Prediction: {scenario['prediction']}")
       print(f"  Probabilities: {scenario.get('probabilities', {})}")
       print(f"  Changed features: {scenario.get('changes', {})}")

Listing Sessions
----------------

View all What-If sessions for a project:

.. code-block:: python

   resp = requests.get(
       f"{BASE_URL}/api/studio/sessions",
       headers=HEADERS,
       params={"project_id": project_id, "limit": 20},
   )
   for s in resp.json()["items"]:
       print(f"  {s['id']}: deployment={s['deployment_id']}, scenarios={s.get('scenario_count', 0)}")

SDK Example
-----------

.. code-block:: python

   from coreplexml import CorePlexMLClient

   client = CorePlexMLClient(base_url=BASE_URL, api_key=API_KEY)

   # Create session
   session = client.studio.create_session(
       project_id=project_id,
       deployment_id=deployment_id,
       baseline_input={"tenure_months": 3, "monthly_charges": 75.0},
   )

   # Add scenarios
   s1 = client.studio.create_scenario(
       session["id"],
       name="Longer tenure",
       changes={"tenure_months": 24},
   )
   client.studio.run_scenario(s1["id"])

   # Compare
   comparison = client.studio.compare(session["id"])

----

.. seealso::

   - :doc:`/api-reference/studio` -- Full Studio API reference
   - :doc:`mlops` -- Deploy models for What-If analysis