Getting Started With Modules

This is an extension of the basic getting started.

In this guide we will extend the refactor the basic model in order to support two alternative use-cases:

  1. the interest rate is passed in to the calculation from an external source (external interest rate)
  2. the interest rate is calculated from the client’s credit score (interest rate from score)

What is a Module

In the first getting started we did not use explicit modules. All Formulas were put directly into the project’s so called Global Module (that is the project’s global space).

However, modules allow the modeller to structure their project and create a logical collection of formulas and table resources. A Module structure can be used for several purposes :

  • segment a model (e.g. different formulas for A and B products put into two respective modules)
  • model a formula hierarchy where modules build on each other (complex calculations built on top of some more basic ones)
  • override certain formulas so that when calculations are defined, different set of modules provide different implementations for the same formulas)
  • etc.

We opted against hierarchical module structure to keep projects easier to work with, so you cannot create modules within modules.

Our use of modules in this context

You might recall we have a variable named r m . We will create two separate formulas to calculate this variable to support our use-cases.

Refactor the model for the external interest rate case

  1. Create a new module for the mortgage formula:
  • name: PMT
  • description: Payment calculation example
  1. Navigate back to the project root and create a new module for the interest rate formula:
  • name: Interest from input
  • description: Monthly Interest calculation based on yearly interest input

At this point your project root should look like this:

../_images/monthly-usecase-models-1.png

It is time to move modules into their places:

  1. select three formulas shown below and click Move to move formulas to the PMT Module.

The move dialog:

../_images/move-to-pmt.png

Shows moving Formulas to the new module.

  1. When you navigate back to the project root you will find a single formula - the monthly interest rate formula - there. Move it to the Interest from Input module.
  2. Click on Evaluate to set the new modules in the 2 contexts we have previously created:
  • In the Default context select the PMT module.
  • In the PMT-simple context select the PMT and Interest from input modules.

This will show the variables correctly defined.

Now that formulas are placed in modules, you will need to refactor the API to tell it to include them.

  1. Open the sidebar and select API
  2. Click into the Calculation Group Mortgage PMT. You will see the Calculation PMT and all variables coloured red, telling you that these can not be resolved.
  3. The Modules dropdown is empty at the moment, click into it and select both PMT and Interest from input modules.
../_images/pmt-api-variables-with-modules.png

The above figure shows that variables are resolved, red coloring disappeared after selecting the modules including the specified variables in the API.

  1. Rebuild the Build and try it: Open the sidebar and select Deployment, click Build button on the top right

With this we have refactored our existing functionality into Modules.

Add interest rate calculation based on Scoring

Next you will add the interest rate calculation based on scoring. The calculation is very simple, it will lookup an annual percentage rate (apr) from a table based on the client’s score.

The score to rate table is the following:

From To Rate
760 850 4.17
700 759 4.392
680 699 4.569
660 679 4.569
640 659 5.213
620 639 5.759

You will need to take the row where the given score is between the from and to values and return the Rate.

The modifications are the followings (we will not detail tasks you already know):

  1. Create a new module
  • Name: Interest from Scoring
  • Description: Interest rate calculation with scoring parameter
  1. Create a new table within this Module (scroll down to see the New Table button)
  • Name: F
  • Description: FICO Score table
  1. Once you created the table you will have two options to upload data:
  • manually or
  • import a file
  1. Download the provided CSV and save it for the next step:

Download this CSV

  1. Click on import file and choose file to upload the file you downloaded in the previous step.
  2. Check the First row contains column names option and fill in the column domains (types) as on the following figure:
../_images/scoring-table-upload-1.png

Scoring table

  1. Now create the formula that will select the right row from the table:
  • Title: Select APR with the given score
  • Formula source: apr = ((e)_'APR | e (- @F : (e)_'From <= Score /\ (e)_'To >= Score)
Dissecting the above:
  • apr = : tells we are going to assign a value to the apr variable
  • e (- @F : tells e is an element of the F resource table, the at sign marks table resources
  • (e)_'APR : tells the table query will return the APR column from the table
  • (e)_'From <= Score && (e)_'To >= Score : this is the query part that says we need the element where the Score is between the From and To columns
  • Score : remember that in this use case this variable value will be passed into the calculation
  1. Last formula in this exercise is to calculate monthly interest rate from apr. Create a new formula (still in the Interest from Scoring module)
  • Title: Calculate monthly interest rate
  • Formula source: r_'m = (apr / 12) / 100
  • Documentation: Calculate monthly interest rate from APR

Evaluate the APR selection formula

While we are here, let’s evaluate the table selection formula.

Click on Evaluate and create a new Evaluation context for testing score selection.

  • configuration name: APR
  • module in configuration: Interest from scoring
  • variables in configuration:
    • Score (input) and
    • apr (output)

Set Score to 760 and click Calculate. You should see the result 4.17 displayed for our apr variable. If you want, you can add r m too to see it’s value set.

../_images/apr-evaluation-output.png

Create the Scoring API

Let’s now create the Scoring API which is based on the client’s score instead of the annual interest rate passed into the service.

Navigate to the API menu (left sidebar)

  • Click New Calculation Group button.
    • Set the Name of the Calculation Group to MortgagePMTFromScore. Leave the API ID to it’s default.
    • Set the Modules incleded in the Calculation Group scope to PMT and Interest from Scoring
  • Click New Calculation button.
    • Set the name of the Calculation to PMT. Leave the API ID to it’s default.
  • Select input variables: Score, T, P
  • Select output variable: c r

Similar to the mortgage from input interest rate case, you will need to specify some details for the users of your API:

Input variable Score :

  • API Id: clientScore
  • Domain: %Z_+ (positive or zero real)

Input variable T :

  • API Id: term
  • Domain: %Z_+ (positive or zero integer)

Input variable P :

  • API Id: principal
  • Domain: %R_+ (positive or zero real)

Output variable c r :

  • API Id: monthlyPayment
  • Domain: %R (any real)

To also give further documentation for your API client developers, add this documentation to the API elements:

  • General description: PMT formula from FICO score
  • inputs:
    • term: term in years
    • clientScore: client's FICO score
    • principal: principal of loan
  • output:
    • monthlyPayment: monthly loan payment

Deployment

One of the goals of this exercise was to show how to use modularization to expose different APIs of the same model to different clients.

Let’s now imagine a fictitious back-office application that will calculate the score (maybe calling another Formulative API) and pass this score into Formulative to get the loan payment amount. For this we need another secure client endpoint that includes this new API. To achieve this we will first create a new Build Configuration and a new Client.

To create the Build configuration:

  • Open the sidebar and select Deployment
  • Click New (New Build Config)
  • Name: MortgagePMTFromScore
  • Select only the MortgagePMTFromScore calculation group
  • Enable the Web Service target
  • Click Create to create the new Build Configuration
../_images/buildConfig-mortgagePmtFromScore.png

Build configuration

  • Create a Draft Build for this Build configuration - just click Build and follow the wizard.

When you are done with Building you will be returned to the Build Configuration’s build list:

../_images/buildList-MortgagePMTFromScore.png

Build list

Since this is not your first Build, there are no defaults provided:

  • your Build will not be configured to be accessible to the existing Client Application
  • your Build will not be installed in any existing containers.

To fix these, do the followings:

  • Click Access above to tell which Client Applications will have access to your new API.
  • Click Create Client Application to create a new application and name it internal-app
  • Click Save
../_images/client-app-internal.png

Internal Client Application

Install your Build’s Web Service Target on your default container:
  • Click Install Web Service
  • Leave the Default Container selected and click Install

Note

You could have opted to create a new Container for your new API. We leave it to you this time to try that if you want.

Once installed, you can test your web service to see if it is working:

  • Click into the Draft Build card
  • Click on the Web Service tab
  • Click Get Token
  • Scroll down to the mortgagePmtFromScore section (open it)
  • Fill in the request body parameters
  • Click Execute
../_images/ws-call-parameters-mortgagePmtFromScore.png

Web Service Call parameters to test the deployed mortgage service

Once you executed the service call, you will see the calculation results.

Summary

In this extension we showed you how to:

  • organize model resources into modules
  • work with parameter tables
  • keep some common Formulas in a shared module
  • separate two variations of calculating the monthly rate into separate modules
  • created two separate, secure endpoints (client applications) for the two APIs. One maybe an external portal, while the other some in-house application.