Projections and Healthcheck

This walkthrough demonstrates how we can project the return of a client’s investment and plot graphs to visualize the portfolio projection using Projection API.

We will start this walkthrough with a finished retirement goal planning.

To see the complete retirement and other goals planning journey and how API Library can power them, see our complete docs (link to docs).

We can see in the image above that our client has a retirement goal amount written on the left hand side and the details of the expenses on the right hand side. With Projection API we can check if this goal is achievable based on the client’s risk profile and deposit plan.

So our next step is to assess the client’s risk profile. This risk profile will then be mapped to a model portfolio consisting of funds our client is recommended to invest in and the weightage of each fund. We leave the risk profiling design and portfolio mapping up to you. If you need help on how to do it you can contact [email protected] This walkthrough will show an example of how we design risk profiling and portfolio mapping.

Here is an example of a risk profile questionnaire.

The result of this questionnaire is a risk profile data (from risk averse to aggressive) from which will then be mapped to an investment portfolio.

Here’s an example of how we show the mapped portfolio to the client.

The expected mean and standard deviation of each fund in the portfolio is a required parameter in the Projection API.

We then next to capture our client’s deposit plan.

Initial and monthly contribution are required parameters of the Projection API.

With the risk profile and deposit plan inputted, now we have all the required information to call Projection API where it will calculate the projection of a portfolio based on its expected return and standard deviation.

POST /api/returnsCalc/v2/projections

Projections API uses inputs from these following categories elaborated below:

For more details on the API consumption, request payload and response payload, please refer to this API documentation (link to specific endpoint doc).

This is the following request payload for this API:

{
  "recommendationSelection": {
      "shortfallRecommendation": {
          "initialInvestment": true,
          "constantInfusion": true,
          "dynamicIncreasingInfusion": true,
          "dynamicDecreasingInfusion": true,
          "goalAmount": true,
          "goalYear": true
      },
      "surplusRecommendation": {
          "glidePath": {
              "glidePath": true,
              "portfolioDerisking": true,
              "deriskStartDate": "2031-01-02",
              "deriskEndDate": "2040-01-03"
          }
      }
  },
  "availablePortfolios": [
      {
          "modelPortfolioId": 4,
          "discreteExpectedMean": 0.03,
          "discreteExpectedStandardDeviation": 0.05
      },
      {
          "modelPortfolioId": 11,
          "discreteExpectedMean": 0.05,
          "discreteExpectedStandardDeviation": 0.06
      },
      {
          "modelPortfolioId": 12,
          "discreteExpectedMean": 0.06,
          "discreteExpectedStandardDeviation": 0.07
      },
      {
          "modelPortfolioId": 13,
          "discreteExpectedMean": 0.08,
          "discreteExpectedStandardDeviation": 0.1
      },
      {
          "modelPortfolioId": 14,
          "discreteExpectedMean": 0.12,
          "discreteExpectedStandardDeviation": 0.16
      }
  ],
  "inputs": {
      "startDate": "2021-01-01",
      "endDate": "2041-01-01",
      "compounding": "monthly",
      "confidenceInterval": 0.8,
      "grossInitialInvestment": 30000,
      "currentWealth": 0,
      "frontEndFees": 0.01,
      "backEndFees": 0.01,
      "managementFees": [
          0
      ],
      "grossGoalAmount": 1102897,
      "modelPortfolioIdList": [
          13
      ],
      "infusions": [
          1000
      ],
      "targetProbability": 0.57
  }
}

From the request payload above, the Projection API projects the future expected portfolio values at each compound date based on expected annual returns and volatilities of Model Portfolios invested each year during the goal period. According to this, the API can perform as Healthcheck, determining if client’s goal is achievable, and also returns probability of achieving goal.

In addition, the periodic projections output values from the Projection API can be used to plot projection graphs to see how the Model Portfolio performs in a range period of time.

Moreover, it will display various recommendations client can follow, such as increasing deposit plans and selecting less risky Model Portfolios nearer to the goal end date.

All the information above are summarized in the Projection API response payload below (SURPLUS projection scenario):

{
  "difference": -78938.75,
  "goalProbability": "0.580033",
  "healthCheckStatus": "SURPLUS",
  "matchGoalProb": false,
  "performanceTest": { ... },
  "projections": [
    {
        "date": "2023-02-01",
        "goalAmountNet": 1102897,
        "projectionLowerAmt": 30000,
        "projectionMiddleAmt": 30000,
        "projectionTargetAmt": 30000,
        "projectionUpperAmt": 30000
    }
    ...
    {
        "date": "2047-02-01",
        "goalAmountNet": 1102897,
        "projectionLowerAmt": 740339.19,
        "projectionMiddleAmt": 1181768.41,
        "projectionTargetAmt": 1181835.75,
        "projectionUpperAmt": 2021569.56
    },
  ],
  "recommendations": {},
  ...
}

To plot the projection graph, the output values from “projections” field in the response payload above will be utilized. Meanwhile, you can display the value of “healthCheckStatus” in the page to inform the client whether the goal is achievable. If “healthCheckStatus” field returns “OK” or “SURPLUS”, it means that the projected investment value is above the goal amount. On the other hand, if “healthCheckStatus” field returns “SHORTFALL”, you can offer suggestions to the client from the “recommendations” values in the response payload to ensure the client can achieve his goal.

Here is an example of SHORTFALL projection and how it can be displayed:

{
  "difference": 20000,
  "goalProbability": "0.001348",
  "healthCheckStatus": "SHORTFALL",
  "matchGoalProb": false,
  "performanceTest": {... },
  "projections": [
    {
      "date": "2023-02-01",
      "goalAmountNet": 1922252.23,
      "projectionLowerAmt": 29700.0,
      "projectionMiddleAmt": 29700.0,
      "projectionTargetAmt": 29700.0,
      "projectionUpperAmt": 29700.0
    },
    ...
    {
      "date": "2048-02-01",
      "goalAmountNet": 1922252.23,
      "projectionLowerAmt": 1251616.10,
      "projectionMiddleAmt": 1902022.78
      "projectionTargetAmt": 1902252.23,
      "projectionUpperAmt": 3052444.35
    },
  ],
  "recommendations": {
    "constantInfusion": [
      2167,
      2167,
      ...
    ],
    "dynamicDecreasingInfusion": [
      10861,
      10861,
        ...
    ],
    "dynamicIncreasingInfusion": [
      1734,
      4784,
      …
    ],
    "endDate": "2064-12-31",
    "goalAmount": 1922252.23,
    "initialInvestment": 878365
  },
  ...
}