Interpreting Results & Cushion Analysis¶

Understanding compliance test results goes beyond simple pass/fail status. This guide explains how to interpret results, analyze cushions, handle breaches, and use historical trends to improve portfolio management.

Understanding Test Results¶

Result Status Levels¶

Every compliance test returns one of three status levels:

Result Data Structure¶

Each test result contains comprehensive information:

{
  "test_name": "Single Obligor Limit",
  "test_category": "concentration",
  "current_value": "8.23",
  "threshold_value": "10.00",
  "cushion": "1.77",
  "status": "pass",
  "description": "ACME Corp: 8.23% of portfolio (limit: 10%)",
  "details": {
    "obligor_id": "OBL_12345",
    "obligor_name": "ACME Corporation",
    "par_exposure": 41150000,
    "total_portfolio_par": 500000000,
    "concentration_pct": 8.23
  }
}

Reading the Results Dashboard¶

The compliance dashboard organizes results for quick comprehension:

+--------------------------------------------------+
|  COMPLIANCE SUMMARY          As of: Jan 15, 2024 |
+--------------------------------------------------+
|                                                  |
|  [22] PASSED   [1] WARNING   [1] FAILED         |
|  ========      ========      ========           |
|  91.7% Pass Rate                                |
|                                                  |
+--------------------------------------------------+
|                                                  |
|  CONCENTRATION        RATING          COVERAGE   |
|  [8/8] Pass          [3/4] Pass      [6/6] Pass |
|                      [1] Warning                 |
|                                                  |
|  QUALITY             DIVERSITY                   |
|  [2/3] Pass          [3/3] Pass                 |
|  [1] Fail                                        |
|                                                  |
+--------------------------------------------------+

Cushion Analysis Explained¶

What is a Cushion?¶

A cushion represents the distance between the current value and the threshold. It tells you how much headroom you have before a breach occurs.

Cushion = Threshold - Current Value (for maximum limits)
Cushion = Current Value - Threshold (for minimum limits)

Cushion Calculation Examples¶

Example 1: Maximum Limit (Concentration)

Single Obligor Test:
- Current Value: 8.23%
- Threshold: 10.00%
- Cushion: 10.00% - 8.23% = 1.77%

Interpretation: You can increase this obligor's exposure by
up to 1.77% of portfolio par before breaching the limit.

Example 2: Minimum Limit (Coverage)

OC Ratio Test:
- Current Value: 122.50%
- Threshold: 120.00%
- Cushion: 122.50% - 120.00% = 2.50%

Interpretation: The OC ratio can decline by up to 2.50%
before breaching the minimum requirement.

Cushion as Percentage of Threshold¶

For easier comparison across tests, CalcBridge also calculates cushion as a percentage of the threshold:

Cushion % = (Cushion / Threshold) * 100

Single Obligor Example:
Cushion % = (1.77 / 10.00) * 100 = 17.7%

Cushion Analysis Table¶

A typical cushion analysis table shows all tests with their cushion status:

Breach Handling and Escalation¶

When a Breach Occurs¶

A compliance breach requires immediate attention and typically triggers:

1. Automated alerts - Email, Slack, PagerDuty notifications
2. Audit logging - Breach details recorded for compliance
3. Escalation workflow - Notification to designated personnel
4. Trading restrictions - Possible limitations on new trades

Breach Response Workflow¶

flowchart TD
    A[Breach Detected] --> B[Alert Generated]
    B --> C{Severity?}
    C -->|Critical| D[Immediate Escalation]
    C -->|Warning| E[Monitor & Investigate]
    D --> F[Trading Halt?]
    E --> G[Root Cause Analysis]
    F --> H[Remediation Plan]
    G --> H
    H --> I[Execute Remediation]
    I --> J[Re-run Tests]
    J --> K{Resolved?}
    K -->|Yes| L[Document & Close]
    K -->|No| H

Documenting Breaches¶

CalcBridge automatically logs breach events with:

• Timestamp and duration
• Exact values at breach
• Contributing factors (specific loans)
• User who acknowledged
• Remediation actions taken
• Resolution timestamp

{
  "breach_id": "breach_20240115_001",
  "test_name": "CCC Bucket",
  "breach_timestamp": "2024-01-15T10:30:00Z",
  "breach_value": "8.12%",
  "threshold": "7.50%",
  "breach_amount": "0.62%",
  "contributing_factors": [
    {
      "loan_id": "LN_78901",
      "obligor": "XYZ Holdings",
      "par_value": 5000000,
      "rating_before": "B3",
      "rating_after": "Caa1",
      "downgrade_date": "2024-01-14"
    }
  ],
  "acknowledged_by": "user@example.com",
  "acknowledged_at": "2024-01-15T10:45:00Z",
  "remediation_plan": "Sell down CCC exposure within 10 business days",
  "resolved_timestamp": null,
  "status": "open"
}

Breach Severity Classification¶

Historical Trend Analysis¶

Why Trends Matter¶

Point-in-time compliance results show current status, but trends reveal:

• Direction of portfolio drift
• Velocity of changes
• Seasonal patterns
• Impact of trading activity

Trend Visualization¶

CalcBridge provides trend charts for each test over time:

CCC Bucket Trend (90 Days)
                                                    Threshold: 7.5%
    8.5% |                                           - - - - - -
         |                                      *
    8.0% |                                 *
         |                            *
    7.5% |========================*===========================
         |                   *
    7.0% |              *
         |         *
    6.5% |    *
         |*
    6.0% +----+----+----+----+----+----+----+----+----+----+
         Oct  Nov  Dec  Jan

Trend Metrics¶

CalcBridge calculates trend metrics to predict future compliance status:

Predictive Alerts¶

When trends indicate an approaching breach, CalcBridge generates predictive alerts:

{
  "alert_type": "predictive_breach",
  "test_name": "CCC Bucket",
  "current_value": "6.85%",
  "threshold": "7.50%",
  "current_cushion": "0.65%",
  "trend_velocity": "+0.15%/week",
  "estimated_breach_date": "2024-02-15",
  "days_until_breach": 31,
  "confidence": "high",
  "recommendation": "Review CCC exposure and consider rebalancing"
}

Comparative Analysis¶

Period-over-Period Comparison¶

Compare compliance status across different time periods:

curl -X GET "https://api.calcbridge.io/api/v1/compliance/compare" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "date_1": "2024-01-01",
    "date_2": "2024-01-15"
  }'

Response:

{
  "comparison": {
    "date_1": "2024-01-01",
    "date_2": "2024-01-15",
    "changes": [
      {
        "test_name": "CCC Bucket",
        "value_date_1": "6.45%",
        "value_date_2": "7.12%",
        "change": "+0.67%",
        "status_date_1": "pass",
        "status_date_2": "warning",
        "status_change": "degraded"
      },
      {
        "test_name": "Senior OC Ratio",
        "value_date_1": "121.50%",
        "value_date_2": "122.50%",
        "change": "+1.00%",
        "status_date_1": "pass",
        "status_date_2": "pass",
        "status_change": "improved"
      }
    ]
  }
}

Scenario Comparison¶

Compare compliance before and after a proposed trade:

Best Practices¶

API Reference¶

Get Test Results with Full Details¶

curl -X GET "https://api.calcbridge.io/api/v1/compliance/results/{job_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -d "include_details=true&include_trends=true"

Get Historical Trends¶

curl -X GET "https://api.calcbridge.io/api/v1/compliance/trends" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "test_name": "ccc_bucket",
    "period": "90d",
    "granularity": "daily"
  }'

Get Cushion Summary¶

curl -X GET "https://api.calcbridge.io/api/v1/compliance/cushions" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "sort_by": "cushion_pct",
    "sort_direction": "asc"
  }'

Next: Setting Up Compliance Alerts