Scenarios & Forecasting Guide | Nagare Documentation

01What Are Scenarios?

A scenario in Nagare is a portfolio-wide forecast that models the future performance of your fund portfolio under specific assumptions. Think of it as a "what-if" analysis tool that lets you answer questions like:

→"What if deployment slows down by 25% across all funds?"
→"What if we achieve 50% better returns than our base case?"
→"What if exits are delayed by 2 years due to market conditions?"
→"How does our portfolio perform in a bear vs bull market?"

Key Concept: Portfolio-Level Forecasting

Unlike fund-level parameters (which define individual fund behavior), scenarios apply assumptions across multiple funds at once. You can include all funds, select specific funds, or use criteria-based filters (e.g., "all VC funds" or "all vintage 2023+").

Scenario Components

1. Fund Selection

Choose which funds to include (all funds, manual selection, or criteria-based filtering)

2. Scenario Type

BASE (standard forecast), OPTIMISTIC (bull case), PESSIMISTIC (bear case), or CUSTOM

3. Assumptions

Return adjustments, deployment pacing, exit timing, fee changes (applied portfolio-wide)

4. Calculation Results

Quarterly projections, portfolio aggregates, cashflow series, and performance metrics

02Common Use Cases

Bear/Base/Bull Analysis

Model three scenarios with different return assumptions to understand your portfolio's risk/reward profile.

Bear: -30% returns, 40% slower deployment, +2Y exit delays

Base: Target returns, standard pacing

Bull: +50% returns, 20% faster deployment, -1Y exits

Capital Planning

Model different deployment paces to forecast when you'll need additional capital, or when you'll have distributions available for recycling into new commitments.

Sensitivity Analysis

Test how sensitive your portfolio is to specific assumptions. Create scenarios varying only one parameter (e.g., "What if all exit timings slip 1 year?").

Fund Manager Due Diligence

Model a new fund commitment's impact on your portfolio. Create a scenario that includes the proposed fund and see how it affects overall portfolio metrics and cashflow timing.

Quarterly Board Reporting

Create a "Current Forecast" scenario each quarter that reflects your latest assumptions. Compare it to previous quarters to show how your outlook has evolved.

03Creating Your First Scenario

Via Web Interface

Navigate to the Scenarios page from the left sidebar

Click "New Scenario" button

Fill out the scenario creation form:

• Scenario Name: Descriptive name (e.g., "Q4 2024 Bear Case")
• Scenario Type: BASE, OPTIMISTIC, PESSIMISTIC, CUSTOM
• Fund Selection Mode: ALL, MANUAL, or CRITERIA
• Assumptions: Return adjustments, deployment changes, exit delays

Click "Create & Calculate" to create the scenario and run calculations

Via API

POST /api/v1/scenariosBRONZE

curl -X POST https://api.nagarehq.com/api/v1/scenarios \
  -H "Authorization: Bearer fnd_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenarioName": "Q4 2024 Base Case",
    "scenarioType": "BASE",
    "fundSelectionMode": "ALL",
    "assumptions": {
      "returnAdjustment": 0,
      "deploymentSlowdown": 0,
      "exitDelay": 0
    },
    "description": "Standard forecast with no adjustments"
  }'

The API returns the created scenario with a unique scenario ID:

Response: 201 Created

{
  "scenarioId": "SCN-1710518400000-ABC123",
  "scenarioName": "Q4 2024 Base Case",
  "scenarioType": "BASE",
  "fundSelectionMode": "ALL",
  "fundIds": ["ACME-GROWTH-I", "BRK-BUYOUT-2023", ...],
  "assumptions": {
    "returnAdjustment": 0,
    "deploymentSlowdown": 0,
    "exitDelay": 0
  },
  "calculationStatus": "PENDING",
  "tenantId": "your-tenant",
  "createdAt": "2024-03-16T10:30:00Z"
}

Calculation Status

After creating a scenario, its status is PENDING. You must trigger a calculation explicitly (see "Running Calculations" section). The UI does this automatically when you click "Create & Calculate".

04Fund Selection Modes

Nagare offers three powerful ways to select which funds are included in a scenario:

ALL - All Funds

ALL

Include all funds in your portfolio (across all statuses and types). This is the most common mode for portfolio-wide forecasts.

Example JSON:

"fundSelectionMode": "ALL"

MANUAL - Specific Funds

MANUAL

Explicitly list which funds to include. Use this when you want to model a subset of your portfolio (e.g., "only my VC funds" or "only vintage 2023+").

Example JSON:

{
  "fundSelectionMode": "MANUAL",
  "fundIds": ["ACME-GROWTH-I", "BRK-BUYOUT-2023", "XYZ-VC-2024"]
}

CRITERIA - Rule-Based Filtering

CRITERIA

Use criteria to dynamically select funds based on their attributes. This is powerful for creating templated scenarios that automatically include funds matching certain rules.

Example: All VC Funds

{
  "fundSelectionMode": "CRITERIA",
  "criteria": {
    "fundType": ["VENTURE_CAPITAL"]
  }
}

Example: Vintage 2023+ Funds

{
  "fundSelectionMode": "CRITERIA",
  "criteria": {
    "vintageMin": 2023
  }
}

Example: Active Deploying Funds

{
  "fundSelectionMode": "CRITERIA",
  "criteria": {
    "status": ["DEPLOYING", "HARVESTING"],
    "tags": ["active"]
  }
}

Available Criteria Fields

• fundType: Array of fund types

• status: Array of fund statuses

• vintageMin / vintageMax: Vintage year range

• tags: Array of tags (all must match)

• currency: Array of currencies

05Scenario Assumptions

Assumptions are the core of what-if modeling. They define how the scenario differs from the base case (MASTER parameters). All assumptions are applied multiplicatively to existing fund parameters.

Return Adjustment

Adjust the target returns (TVPI) for all funds in the scenario. Positive values increase returns, negative values decrease them.

+0.5 (50% increase)2.0x TVPI → 3.0x TVPI

0 (no change)2.0x TVPI → 2.0x TVPI

-0.3 (30% decrease)2.0x TVPI → 1.4x TVPI

Deployment Slowdown

Adjust the deployment pacing (capital calls). Positive values slow down deployment, negative values speed it up. This stretches or compresses the deployment schedule.

0.4 (40% slower)5 year deployment → 7 year deployment

0 (no change)5 year deployment → 5 year deployment

-0.2 (20% faster)5 year deployment → 4 year deployment

Exit Delay (Quarters)

Shift all exit events forward (positive) or backward (negative) by a fixed number of quarters. This models market timing effects on exit opportunities.

8 (2 year delay)Q16 exit → Q24 exit

0 (no change)Q16 exit → Q16 exit

-4 (1 year early)Q16 exit → Q12 exit

Example: Creating a Bear Case

Bear Case Assumptions

{
  "scenarioName": "Q4 2024 Bear Case",
  "scenarioType": "PESSIMISTIC",
  "fundSelectionMode": "ALL",
  "assumptions": {
    "returnAdjustment": -0.3,        // 30% lower returns
    "deploymentSlowdown": 0.4,       // 40% slower deployment
    "exitDelay": 8                   // 2 year exit delays
  }
}

06Running Calculations

After creating a scenario, you must trigger a calculation to generate projections. Calculations are compute-intensive, so they run asynchronously in the background.

Trigger Calculation via API

POST /api/v1/scenarios/:scenarioId/calculateBRONZE

curl -X POST https://api.nagarehq.com/api/v1/scenarios/SCN-123/calculate \
  -H "Authorization: Bearer fnd_live_YOUR_API_KEY"

The calculation starts immediately and the response confirms it's in progress:

Response: 200 OK

{
  "scenarioId": "SCN-123",
  "calculationStatus": "IN_PROGRESS",
  "message": "Calculation started",
  "startedAt": "2024-03-16T10:35:00Z"
}

Check Calculation Status

Poll the scenario endpoint to check if the calculation has completed:

GET /api/v1/scenarios/:scenarioIdSAGE

curl -X GET https://api.nagarehq.com/api/v1/scenarios/SCN-123 \
  -H "Authorization: Bearer fnd_live_YOUR_API_KEY"

Response: Calculation Complete

{
  "scenarioId": "SCN-123",
  "scenarioName": "Q4 2024 Base Case",
  "calculationStatus": "COMPLETED",
  "completedAt": "2024-03-16T10:37:45Z",
  "fundCount": 15,
  "quarterCount": 60
}

Calculation Status Values

• PENDING: Scenario created, not yet calculated

• IN_PROGRESS: Calculation running

• COMPLETED: Calculation successful, results ready

• FAILED: Calculation error (check error message)

Calculation Performance

Typical calculation times:

~5 sec

Small portfolio (1-5 funds)

~15 sec

Medium portfolio (10-20 funds)

~45 sec

Large portfolio (50+ funds)

07Understanding Results

Once a calculation completes, you can retrieve results at different levels of granularity:

1. Portfolio Aggregates (Dashboard View)

Get high-level portfolio metrics—total NAV, total distributions, portfolio IRR, etc.

GET /api/v1/scenarios/:scenarioId/aggregates/latestSAGE

curl -X GET https://api.nagarehq.com/api/v1/scenarios/SCN-123/aggregates/latest \
  -H "Authorization: Bearer fnd_live_YOUR_API_KEY"

Response: Portfolio Aggregates

{
  "scenarioId": "SCN-123",
  "asOfDate": "2024-03-16",
  "currency": "USD",
  "totalCommitment": 250000000,
  "totalCalled": 180000000,
  "totalDistributed": 95000000,
  "totalNAV": 215000000,
  "portfolioTVPI": 1.72,
  "portfolioIRR": 0.185,
  "portfolioDPI": 0.53,
  "portfolioRVPI": 1.19
}

2. Per-Fund Latest Data

Get the most recent quarter's data for each fund in the scenario:

GET /api/v1/scenarios/:scenarioId/funds/latestSAGE

curl -X GET https://api.nagarehq.com/api/v1/scenarios/SCN-123/funds/latest \
  -H "Authorization: Bearer fnd_live_YOUR_API_KEY"

3. Cashflow Series (Time Series)

Get quarterly cashflow data for the entire forecast horizon (for charts):

GET /api/v1/scenarios/:scenarioId/cashflowSAGE

curl -X GET https://api.nagarehq.com/api/v1/scenarios/SCN-123/cashflow \
  -H "Authorization: Bearer fnd_live_YOUR_API_KEY"

Response: Cashflow Series

{
  "scenarioId": "SCN-123",
  "currency": "USD",
  "quarters": [
    {
      "quarter": 1,
      "year": 2024,
      "capitalCall": 12000000,
      "distribution": 5000000,
      "nav": 45000000,
      "cumCapitalCall": 12000000,
      "cumDistribution": 5000000
    },
    {
      "quarter": 2,
      "year": 2024,
      "capitalCall": 15000000,
      "distribution": 8000000,
      "nav": 52000000,
      "cumCapitalCall": 27000000,
      "cumDistribution": 13000000
    },
    ...
  ]
}

08Comparing Scenarios

The real power of scenarios comes from comparing multiple forecasts side-by-side. Nagare makes it easy to visualize bear/base/bull cases or test different strategic assumptions.

Comparison View (UI)

Navigate to the Comparison page and select 2-3 scenarios to compare:

Side-by-Side Metrics

Compare key metrics (TVPI, IRR, NAV) across scenarios in a table format

Overlayed Cashflow Charts

See how capital calls and distributions differ across scenarios on a single chart

NAV Waterfall

Visualize how portfolio NAV evolves under different scenarios

Sensitivity Tornado

See which assumptions have the biggest impact on portfolio outcomes

API Comparison (Custom Analysis)

For custom analysis, fetch aggregates from multiple scenarios and compare programmatically:

Example: Fetch 3 Scenarios

# Fetch Bear Case
curl -X GET https://api.nagarehq.com/api/v1/scenarios/SCN-BEAR/aggregates/latest

# Fetch Base Case
curl -X GET https://api.nagarehq.com/api/v1/scenarios/SCN-BASE/aggregates/latest

# Fetch Bull Case
curl -X GET https://api.nagarehq.com/api/v1/scenarios/SCN-BULL/aggregates/latest

# Compare TVPI, IRR, NAV across the three

Pro Tip: Naming Convention

Use a consistent naming scheme for scenarios: YYYY-QQ Type(e.g., "2024-Q4 Bear", "2024-Q4 Base", "2024-Q4 Bull"). This makes comparison and time-travel analysis much easier.

09Setting Main Scenario

You can designate one scenario as the "main" scenario. This is the forecast shown by default on the dashboard and in reports. Typically, this is your current base case forecast.

Set Main Scenario via API

POST /api/v1/scenarios/:scenarioId/set-mainBRONZE

curl -X POST https://api.nagarehq.com/api/v1/scenarios/SCN-BASE/set-main \
  -H "Authorization: Bearer fnd_live_YOUR_API_KEY"

This automatically unsets any previous main scenario and marks the specified scenario as main:

Response: 200 OK

{
  "scenarioId": "SCN-BASE",
  "scenarioName": "Q4 2024 Base Case",
  "isMain": true,
  "message": "Scenario set as main"
}

Main Scenario Best Practices

Update your main scenario quarterly to reflect your latest forecast. Keep historical main scenarios archived (don't delete) so you can perform time-travel analysis: "What did we forecast in Q2 2023?"

10Best Practices

Always Create Bear/Base/Bull Trio

Don't rely on a single forecast. Create three scenarios (pessimistic, base, optimistic) to understand the range of possible outcomes. This helps manage expectations and plan for downside risk.

Use Descriptive Names with Dates

Name scenarios like "2024-Q4 Base Case" or "2025-Q1 Bear (Recession)". Include the quarter so you can track how your forecast has evolved over time.

Archive, Don't Delete Old Scenarios

Keep historical scenarios for time-travel analysis. Mark them as archived but don't delete. This lets you answer "What did we forecast 6 months ago?" for variance analysis.

Document Your Assumptions

Use the scenario description field to explain why you chose specific assumptions. "Bear case assumes recession, 30% lower valuations" is much more useful than just "Bear case".

Recalculate After Actuals Upload

When you upload new transactions (actuals), recalculate your main scenario. The blended view will automatically use actuals for past quarters, giving you an updated forward forecast.

Use CRITERIA for Dynamic Scenarios

If you have a scenario that should always include "all VC funds" or "all mature funds", use CRITERIA selection mode. It automatically picks up new funds as they're added.

11API Examples

List All Scenarios

GET /api/v1/scenariosSAGE

curl -X GET "https://api.nagarehq.com/api/v1/scenarios?page=1&limit=20" \
  -H "Authorization: Bearer fnd_live_YOUR_API_KEY"

Update Scenario Assumptions

PUT /api/v1/scenarios/:scenarioIdNAVY

curl -X PUT https://api.nagarehq.com/api/v1/scenarios/SCN-123 \
  -H "Authorization: Bearer fnd_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assumptions": {
      "returnAdjustment": -0.4,
      "deploymentSlowdown": 0.5,
      "exitDelay": 12
    }
  }'

Delete Scenario

DELETE /api/v1/scenarios/:scenarioIdRED

curl -X DELETE https://api.nagarehq.com/api/v1/scenarios/SCN-123 \
  -H "Authorization: Bearer fnd_live_YOUR_API_KEY"

12Troubleshooting

Calculation stuck in IN_PROGRESS

Cause: Calculation timed out or encountered an error, but status wasn't updated.

Solution: Wait 5 minutes, then check status again. If still stuck, trigger a new calculation. Long-running calculations (50+ funds) may take 1-2 minutes.

Scenario results look unrealistic

Common causes: Extreme assumptions (e.g., +5.0 returnAdjustment = 500% increase), or missing funds (MANUAL mode with empty fund list).

Solution: Review assumptions—they're multiplicative, so use reasonable values (-0.5 to +1.0). Check fund selection to ensure funds are included.

Can't compare scenarios with different fund lists

Cause: Scenarios include different funds, so portfolio totals aren't comparable.

Solution: For apples-to-apples comparison, ensure all scenarios use the same fund selection mode and fund list. Use ALL or identical MANUAL lists.

Main scenario dashboards show outdated data

Cause: Main scenario hasn't been recalculated after recent transactions or parameter updates.

Solution: Trigger a recalculation on the main scenario. Establish a routine to recalculate quarterly after uploading new actuals.

CRITERIA selection returns no funds

Cause: Criteria too restrictive (no funds match all conditions).

Solution: Relax criteria or check that your funds have the expected attributes (fund type, tags, status, vintage). Use MANUAL mode temporarily to verify fund IDs.

Ready to Model Your Portfolio's Future?

Now that you understand scenarios, explore Monte Carlo simulations for probabilistic forecasting and multi-currency management for global portfolios.

Next: Monte Carlo Simulations →View API Reference ← Previous: Transactions & Actuals

Scenarios & Forecasting

In This Guide