Documentation

MiscTab Documentation

The MiscTab provides comprehensive control over the financial simulation parameters, chart display options, and export functionality. It serves as the central hub for customizing how the financial plan is calculated, visualized, and shared with clients.

This tab controls:

  • Display Options: Toggle visibility of different financial data series on charts
  • Simulation Parameters: Configure Monte Carlo simulation settings and inflation rates
  • Real Values Mode: Toggle between nominal and real (inflation-adjusted) values
  • Analysis Options: Control Monte Carlo displays, annotations, and performance optimization
  • Scenario Management: Save current scenarios or create new variations
  • Export Tools: Generate PDF reports and export charts for client presentations

Display Options

Layout Settings

Controls the overall layout of the planner interface.

Use Sidebar View:

  • Default: Tabbed view with one chart visible at a time
  • Sidebar View: All charts displayed simultaneously in a scrollable layout
  • Use Case: Sidebar view is ideal for comprehensive analysis and comparing multiple metrics side-by-side
  • Persistence: Setting is saved to database and applies across sessions

Financial Data Toggles

Controls which financial data series are displayed on the main Net Wealth chart. These toggles are hidden when in Sidebar View mode.

Savings Fund:

  • Displays the savings fund balance trajectory over time
  • Shows how cash reserves grow or deplete throughout the plan
  • Useful for tracking liquidity and cash flow management

Investment:

  • Shows total investment portfolio value across all investment funds
  • Tracks overall investment growth and withdrawals
  • Can be broken down further with "Individual" sub-toggle

Individual Investments:

  • Only available when "Investment" is enabled
  • Displays each of the up to 5 investment funds as separate lines
  • Allows detailed analysis of fund-specific performance and allocation
  • Hidden in Planner Lite Mode

KiwiSaver:

  • Shows total KiwiSaver balance across main client and partner
  • Tracks KiwiSaver growth from contributions and returns
  • Shows impact of consolidation events if configured

Individual KiwiSavers:

  • Only available when "KiwiSaver" is enabled
  • Separates main client and partner KiwiSaver balances
  • Useful for analyzing individual retirement savings trajectories

Analysis Options

Monte Carlo:

  • Displays best-case and worst-case simulation results as a shaded range
  • Shows the confidence interval around the average Net Wealth projection
  • Provides visual representation of plan uncertainty and risk
  • Hidden in Sidebar View mode

Target Estate:

  • Displays a horizontal dashed line representing the desired estate value
  • Configured in Goals Tab
  • Helps assess whether the plan achieves the target estate at ending age
  • Hidden in KiwiSaver Mode and Planner Lite Mode
  • Hidden in Sidebar View mode

Annotations:

  • Toggles visibility of custom annotations added to charts
  • Annotations are notes/markers placed directly on chart data points
  • Useful for highlighting key events or observations for client presentations
  • Persists across sessions when saved with scenario

Show Single Scenario:

  • Uses a single median scenario instead of Monte Carlo simulation
  • Provides deterministic results based on one representative scenario
  • Faster calculations and clearer single-line projections
  • Useful for initial planning before running full Monte Carlo analysis
  • Hidden in KiwiSaver Mode

Include Property Equity:

  • Controls whether property equity (value minus debt) is included in Net Wealth calculation
  • When enabled: All property equity automatically included in Net Wealth
  • When disabled: Property equity only included if individual property display flags are enabled
  • Allows flexibility in how property wealth is presented to clients
  • Hidden in KiwiSaver Mode and Planner Lite Mode

Optimise Performance:

  • Disables automatic recalculations when inputs change
  • Requires manual refresh using the refresh button in chart container
  • Significantly improves responsiveness on slower devices or complex scenarios
  • Shows toast notification when enabled explaining manual sync requirement
  • Useful for large Monte Carlo simulations (500+ scenarios)

Simulation Parameters

Inflation Rate (%)

The global annual inflation rate used throughout the financial plan unless overridden by specific inflation rates on individual income/expense items.

Behavior:

  • Default: Typically 2-3% based on long-term historical averages
  • Range: Can be negative (deflation) to high inflation scenarios (5%+)
  • Application: Applied to all incomes, expenses, property values, and other nominal values
  • Individual Overrides: Specific items can have their own inflation rates in their respective tabs
  • Real Values Mode: Automatically set to 0% when Real Values mode is enabled (read-only)

Strategic Use:

Conservative Planning: Use higher inflation (3-4%) to stress-test purchasing power
Optimistic Planning: Use lower inflation (1-2%) for best-case scenarios
Historical Average: 2.5% represents NZ long-term CPI inflation

Real Values Mode

A powerful toggle that converts the entire plan from nominal (dollar) values to real (inflation-adjusted) values.

When Enabled:

  • Global inflation rate is forced to 0%
  • All individual inflation rates are reduced by the global inflation amount
  • Charts show "real" purchasing power in today's dollars
  • Original inflation rates are stored and can be restored when disabled

Calculation Process:

Before Real Values Mode (Nominal):
  Global Inflation: 2.5%
  Income Inflation: 3.0%
  Expense Inflation: 2.0%

After Real Values Mode Enabled (Real):
  Global Inflation: 0%
  Income Inflation: 3.0% - 2.5% = 0.5% (real wage growth)
  Expense Inflation: 2.0% - 2.5% = -0.5% (real expense reduction)

Benefits:

  • Easier client communication using today's dollar values
  • Clearer understanding of real purchasing power over time
  • Simplifies comparison across different time periods
  • Removes inflation "noise" from projections

Important Notes:

  • State is managed centrally and persists across page navigation
  • Original rates are stored in database for saved scenarios
  • When disabled, all original inflation rates are restored exactly
  • Investment return calculations still use original global inflation for proper real return calculation

Number of Simulations

Controls how many Monte Carlo scenarios are run to calculate success rates and confidence intervals.

Range:

  • Minimum: 1 (effectively single scenario mode)
  • Maximum: 1,000 (hard cap for performance)
  • Default: Typically 100-200 for balance of accuracy and speed
  • Step: Increment by 50 for easier adjustment

Accuracy vs. Performance:

50 simulations: Fast, rough estimate (±5% accuracy)
100 simulations: Good balance for initial analysis (±3% accuracy)
200 simulations: Standard for client presentations (±2% accuracy)
500 simulations: High accuracy for final planning (±1% accuracy)
1,000 simulations: Maximum accuracy but slow (±0.5% accuracy)

When to Adjust:

  • Increase: For final recommendations, conservative clients, complex scenarios
  • Decrease: For initial exploration, faster devices, simple scenarios
  • Performance Impact: Each doubling approximately doubles calculation time

Confidence Interval (%)

Defines the statistical confidence level for Monte Carlo simulation results.

Range:

  • Minimum: 0% (shows full range from worst to best case)
  • Maximum: 100% (theoretical, would show only average)
  • Default: Typically 90% or 95%
  • Step: Increment by 5%

Interpretation:

90% Confidence Interval:
  - Excludes the worst 5% and best 5% of scenarios
  - Shows the range where 90% of outcomes fall
  - More conservative than 95%

95% Confidence Interval:
  - Excludes the worst 2.5% and best 2.5% of scenarios
  - Shows the range where 95% of outcomes fall
  - Standard for statistical analysis

80% Confidence Interval:
  - Excludes the worst 10% and best 10% of scenarios
  - Narrower range, less conservative
  - Useful for showing more likely outcomes

Visual Impact on Charts: When "Show Monte Carlo" is enabled, the shaded range represents the confidence interval:

  • Lower bound: The worst case within the confidence interval
  • Upper bound: The best case within the confidence interval
  • Average line: The median/average outcome across all simulations

Scenario Management

Current Scenario Information

Displays details about the currently loaded scenario:

  • Scenario Name: The name assigned to this scenario
  • Household Name: The client/household this scenario belongs to
  • Scenario ID: Unique identifier (shown if scenario is saved)

Save Current

Updates the existing scenario with current input data and settings.

Requirements:

  • Must have an existing scenario ID (cannot save if no current scenario)
  • User must have "save scenarios" permission
  • Disabled for read-only users

What Gets Saved:

  • All input data from all tabs (Personal, Income, Expenses, etc.)
  • Display preferences (chart toggles, sidebar view)
  • Simulation parameters (inflation, num simulations, confidence)
  • Real Values mode state and original inflation rates
  • Annotations and their positions
  • What-If events configuration

Use Case:

  • Updating a scenario after making adjustments
  • Saving incremental changes during planning session
  • Preserving client-approved recommendations

Save as New

Creates a new scenario based on current inputs, preserving the original.

Requirements:

  • User must have "save scenarios" permission
  • No scenario ID required (can save from any state)

Process:

  1. Opens modal prompting for new scenario name
  2. Creates new database record with unique ID
  3. Copies all current input data and settings
  4. Associates with current household
  5. Switches to the newly created scenario

Use Case:

  • Creating scenario variations for comparison
  • Testing different strategies (conservative vs. aggressive)
  • Preserving "before" state before making major changes
  • Creating alternative recommendations for client review

Export Tools

PDF Export

Generates a comprehensive PDF report of the financial plan for client delivery.

Process:

  1. Click "PDF Export" button
  2. System triggers financial calculations if not already performed
  3. Opens DownloadPDFModal with customization options
  4. Select which sections to include in report
  5. Generate PDF with selected content

PDF Customization Options:

Sections to Include:

  • Personal Information: Ages, life expectancy, household composition
  • Income: Primary income, additional incomes, NZ Superannuation
  • Expenses: Living expenses, one-off expenses breakdown
  • Investments: Investment fund allocations and strategies
  • KiwiSaver: KiwiSaver balances and contribution schedules
  • Property: Property details, mortgages, rental income
  • Goals: Financial goals and achievement analysis
  • What-If Scenarios: Configured life events and their impacts

Additional Options:

  • Include Data Table: Year-by-year detailed financial data
  • AI Summary: Experimental feature for AI-generated plan summary (experimental users only)
  • Chart Selection: Coming soon - select specific charts to include

PDF Features:

  • A4 page format optimized for printing
  • Professional layout with household/scenario branding
  • Page numbers and navigation
  • Compressed for smaller file size
  • High-quality text rendering for clarity

Performance Considerations:

  • Shows "Calculating..." spinner while financial metrics are computed
  • May take 5-30 seconds depending on number of simulations and complexity
  • Uses lazy calculation to avoid unnecessary recalculations

Chart Export

Exports individual charts as high-resolution images for presentations and reports.

Process:

  1. Click "Chart Export" button
  2. Opens ExportModal with chart selection
  3. Choose which charts to export
  4. Select format and resolution
  5. Download images individually or as ZIP

Available Charts:

Always Available:

  • Net Wealth projection chart
  • Income breakdown chart
  • Expense breakdown chart

Conditionally Available:

  • Property Value chart (if properties configured)
  • Debt chart (if property debt exists)
  • Repayments chart (if debt configured)
  • Capital Gains chart (if properties configured)
  • Property Cashflow chart (if rental income configured)
  • Cashflow Breakdown (if enabled in settings)
  • Negative Cashflow Breakdown (if enabled)

Export Options:

  • Format: PNG (high quality), JPG (smaller file size), SVG (vector)
  • Resolution: Standard (1x), High (2x for retina), Print (3x for printing)
  • Background: Transparent or white background
  • Dimensions: Maintains aspect ratio, scales appropriately

Use Cases:

  • Creating client presentation slides
  • Including charts in written reports
  • Social media sharing (with client permission)
  • Printing for physical client meetings

Annotations System

Adding Annotations

Allows adding custom notes directly onto chart data points to highlight key events or insights.

Process:

  1. Enable "Annotations" toggle to show existing annotations
  2. Click "Add Annotation" button to enter annotation mode
  3. Click on a specific data point on the chart
  4. Dialog appears prompting for:
    • Annotation Text: The note content (e.g., "Retirement begins", "Market crash scenario")
    • Color: Visual color for the annotation marker
    • Series: Which data line the annotation applies to (Net Wealth, Savings, etc.)
  5. Click "Stop Annotating" to exit annotation mode

Annotation Features:

  • Positioned at exact age/value coordinates
  • Persist when scenario is saved
  • Can be shown/hidden with toggle
  • Click annotation marker to delete
  • Synced across chart updates

Strategic Uses:

Example Annotations:
- Age 65: "NZ Superannuation begins - $27,000/year"
- Age 55: "Mortgage fully paid off"
- Age 70: "Market recession scenario impact"
- Age 45: "Children finish university"
- Age 60: "Transition to part-time work"

Showing/Hiding Annotations

The "Annotations" toggle controls visibility of all annotations:

  • Enabled: All annotations visible on charts
  • Disabled: Annotations hidden but preserved
  • Persistence: Setting saved with scenario

Deleting Annotations

When annotations are visible:

  1. Click on the annotation marker on the chart
  2. Confirmation dialog appears
  3. Confirm to permanently delete the annotation
  4. Annotation removed from scenario

Advanced Features

Performance Optimization

The "Optimise Performance" toggle fundamentally changes how calculations are triggered:

Standard Mode (Default):

  • Calculations run automatically whenever inputs change
  • Charts update in real-time as you modify values
  • Smooth experience on modern devices
  • May lag on slower devices with complex scenarios

Performance Mode (Optimised):

  • Calculations only run when manually triggered
  • Refresh button appears in chart container
  • Inputs can be changed rapidly without lag
  • Click refresh to see updated results
  • Toast notification explains manual sync requirement

When to Enable:

  • Running 500+ Monte Carlo simulations
  • Working on slower devices or tablets
  • Making many rapid input changes
  • Complex scenarios with multiple properties/goals
  • Experiencing lag or delayed chart updates

Technical Benefits:

  • Prevents calculation cascade when changing multiple related values
  • Reduces memory usage by deferring calculations
  • Allows faster data entry without waiting for recalculations
  • User controls exactly when expensive computations run

Table Export Settings

Controls which columns are included when exporting year-by-year data tables to PDF.

Category: Income & Expenses

  • Always Included: Age
  • Optional Columns:
    • Gross Income: Total income before tax
    • Net Income: Income after tax
    • Total Expenditure: All regular expenses
    • Additional Expenditure: One-off expenses
    • Net Cashflow: Income minus expenses
    • Main Income: Main client's income separately
    • Partner Income: Partner's income separately

Category: Investments & KiwiSaver

  • Optional Columns:
    • Investments Fund: Total investment balance
    • Total KiwiSaver: Combined KiwiSaver balance
    • Main KiwiSaver: Main client's KiwiSaver
    • Partner KiwiSaver: Partner's KiwiSaver
    • Annual Investment Return: Yearly investment gains
    • Annual KiwiSaver Return: Yearly KiwiSaver gains
    • Minimum Investment Return: Worst case return
    • Maximum Investment Return: Best case return

Category: Property

  • Optional Columns:
    • Property Value: Total property value
    • Debt Value: Total mortgage debt
    • Monthly Debt Repayment: Monthly mortgage payment
    • Annual Debt Repayments: Yearly total payments
    • Annual Interest Payments: Interest portion of payments
    • Annual Principal Repayments: Principal portion of payments

Category: Taxation

  • Optional Columns:
    • Income Tax: Total income tax paid
    • MTR Investment Tax: Tax on MTR investment returns
    • PIE Investment Tax: Tax on PIE investment returns
    • KiwiSaver Tax: PIE tax on KiwiSaver returns
    • Main Income Tax: Main client's income tax
    • Partner Income Tax: Partner's income tax

Strategic Column Selection:

  • Minimal: Age, Net Income, Total Expenditure, Net Cashflow, Investments Fund
  • Standard: Add Total KiwiSaver, Property Value, Debt Value, Income Tax
  • Comprehensive: Include all columns for detailed analysis
  • File Size Impact: More columns = larger PDF file size

Best Practices for Financial Advisers

Display Options Strategy

Initial Client Meeting:

  • Keep toggles simple: Show only Net Wealth and key components
  • Enable Monte Carlo to demonstrate uncertainty
  • Use Target Estate to show goal achievement

Detailed Analysis:

  • Enable Individual Investments to analyze fund allocation
  • Show Individual KiwiSavers to discuss retirement savings strategies
  • Use Annotations to mark key life events and transitions

Client Presentation:

  • Toggle off unnecessary detail to avoid overwhelming clients
  • Focus on 2-3 key metrics that matter most to client goals
  • Use Sidebar View for comprehensive review sessions

Simulation Parameters Guidelines

Inflation Rate Selection:

Conservative Planning: 3.0% (stress-test purchasing power)
Standard Planning: 2.5% (NZ historical average)
Optimistic Planning: 2.0% (low inflation environment)
Real Values Analysis: 0% (with Real Values mode enabled)

Monte Carlo Simulations:

Initial Exploration: 50-100 simulations (quick feedback)
Client Meetings: 200-300 simulations (reliable results)
Final Recommendations: 500-1000 simulations (high confidence)

Confidence Intervals:

Conservative Clients: 90% (more cautious range)
Standard Clients: 95% (statistical standard)
Optimistic Clients: 80% (focus on likely outcomes)

Real Values Mode Usage

When to Enable:

  • Explaining long-term projections to clients confused by inflation
  • Comparing purchasing power across different time periods
  • Simplifying retirement income discussions
  • Presenting to analytically-minded clients who prefer "today's dollars"

When to Disable:

  • Showing actual dollar amounts for near-term planning
  • Comparing to nominal financial goals (e.g., "$1 million at retirement")
  • Working with clients who think in nominal terms
  • Coordinating with external nominal projections

Scenario Management Workflow

Typical Session Flow:

  1. Load Base Scenario: Start with client's current situation
  2. Make Adjustments: Modify inputs based on client feedback
  3. Save Current: Update base scenario with refinements
  4. Test Variations: Create "what-if" scenarios
  5. Save as New: Preserve each variation for comparison
  6. Export: Generate PDF reports for each scenario
  7. Present: Show side-by-side comparison of scenarios

Scenario Naming Conventions:

Base Case: "Current Plan - Conservative"
Variations: "Early Retirement - Age 60"
           "Aggressive Investment Strategy"
           "What-If: Market Recession at 64"
           "Property Purchase - Investment Home"

Export Best Practices

PDF Report Generation:

  • Always include Personal, Income, Expenses sections for context
  • Include relevant sections based on client situation (skip Property if renting)
  • Use data table for detail-oriented clients
  • Keep file size manageable by excluding unnecessary sections

Chart Export Usage:

  • Export high-resolution (2x) for client emails
  • Use print quality (3x) for physical presentations
  • PNG with transparency for PowerPoint presentations
  • JPG for smaller file size when emailing multiple charts

Performance Optimization Strategy

Enable Performance Mode When:

  • Working with 500+ simulations
  • Client has 3+ properties with multiple loans
  • Complex goal structures (5+ goals)
  • Multiple what-if events active
  • Experiencing noticeable lag

Workflow with Performance Mode:

  1. Enable "Optimise Performance"
  2. Make all desired input changes across multiple tabs
  3. Return to Misc Tab
  4. Click refresh button in chart container
  5. Review updated results
  6. Repeat as needed

Disable Performance Mode:

  • For real-time feedback during client meetings
  • When making single isolated changes
  • On modern devices with simple scenarios
  • When client wants to see immediate impact of changes

Common Use Cases

Case 1: Retirement Planning Analysis

Setup:

  • Enable: Investment, KiwiSaver, Target Estate
  • Simulations: 300
  • Confidence: 95%
  • Real Values Mode: Enabled (show purchasing power)

Workflow:

  1. Load client's current scenario
  2. Adjust retirement age in Personal Tab
  3. Modify KiwiSaver contributions
  4. Set desired estate value in Goals Tab
  5. Enable Target Estate display
  6. Add annotation at retirement age
  7. Export PDF report
  8. Save as New: "Retirement at 65 - Recommended"

Case 2: Property Purchase Decision

Setup:

  • Enable: Property Value, Debt, Include Property Equity
  • Simulations: 200
  • Create scenarios with/without property purchase

Workflow:

  1. Base scenario: Current situation
  2. Save as New: "With Property Purchase"
  3. Configure property in Property Tab
  4. Compare Net Wealth trajectories
  5. Analyze cashflow impact
  6. Export charts for both scenarios
  7. Present side-by-side comparison

Case 3: Insurance Needs Analysis

Setup:

  • Configure death event in What-If Tab
  • Test with/without insurance payout
  • Enable Monte Carlo for risk visualization

Workflow:

  1. Base scenario: Current insurance coverage
  2. Add death event at age 50
  3. Set current insurance payout
  4. Run scenario WITH insurance (toggle ON)
  5. Save as New: "Death Scenario - Insured"
  6. Toggle insurance OFF
  7. Save as New: "Death Scenario - Uninsured"
  8. Compare outcomes to justify coverage recommendation

Case 4: Client Presentation Package

Setup:

  • Sidebar View: Enabled (show all charts)
  • Annotations: Enabled (show key events)
  • Real Values: Enabled (simpler communication)

Workflow:

  1. Finalize recommended scenario
  2. Add annotations for key milestones
  3. Export comprehensive PDF with all sections
  4. Export individual charts (Net Wealth, Income, Expenses)
  5. Create PowerPoint with exported charts
  6. Include PDF as appendix
  7. Save scenario with client-approved name

Troubleshooting

PDF Export Issues

Problem: PDF is blank or missing content

  • Solution: Wait longer after opening modal (content may still be rendering)
  • Check: Ensure financial calculations have completed (no spinner)
  • Try: Close and reopen PDF modal
  • Fallback: Use Chart Export to get individual chart images

Problem: PDF file size is too large

  • Solution: Reduce number of sections included
  • Disable: Data table export (largest component)
  • Reduce: Number of charts if chart selection is enabled

Performance Issues

Problem: Planner is slow or unresponsive

  • Enable: "Optimise Performance" mode
  • Reduce: Number of simulations (try 100 instead of 500)
  • Simplify: Reduce number of What-If events
  • Clear: Browser cache and reload page
  • Check: Device memory and close other applications

Problem: Charts not updating after input changes

  • Check: "Optimise Performance" is enabled (manual refresh required)
  • Action: Click refresh button in chart container
  • Verify: Changes were actually saved (check input fields)
  • Try: Disable and re-enable performance mode

Real Values Mode Issues

Problem: Can't edit inflation rate

  • Check: Real Values mode is enabled (inflation locked at 0%)
  • Solution: Disable Real Values mode to restore inflation editing

Problem: Original rates not restored when disabling

  • Check: Scenario was saved with Real Values mode enabled
  • Verify: Original rates are stored in database
  • Fallback: Manually re-enter inflation rates if restoration fails

Scenario Save Issues

Problem: "Save Current" button is disabled

  • Check: Current scenario ID exists (must have loaded scenario)
  • Verify: User has save scenarios permission
  • Solution: Use "Save as New" instead if no current scenario

Problem: Scenario saves but changes don't persist

  • Check: Browser isn't blocking localStorage/sessionStorage
  • Verify: Database connection is stable
  • Try: Hard refresh page (Ctrl+Shift+R) and reload scenario
  • Check: Real Values state is properly persisted to database