Value Driver Models

Value Driver Models (VDMs) allow subject-matter experts to build graphical models, and easily share them throughout your organisation.

Python and R Code Models

What if?

Two of Akumen’s key capabilities are scenario flexing and scenario management, which can be handled in the Research tab.

Scenario flexing allows you to generate a number of scenarios based on altering individual parameter values. For example, you can create a number of scenarios, flexing the interest rate of an NPV model.

Scenario management allows you to clone, delete, reorder or baseline existing scenarios, along with manually altering parameter values for those scenarios.

These Scenarios allow us to look at the “What if…?” situations and plan for either

• The worst case - and how it could be used to a users advantage;
• The best case - and how to best implement it; and
• The Optimal case - the best combination to inputs to outputs.

The Research Grid

The research grid can be found by clicking on the Research button at the top right of the screen.

The research grid is where scenarios can be cloned and researched.

Below is an example of the different scenario parameters (columns) in the research grid.

The rows on the grid are scenarios.

Scoping

The research grid is broken up into a number of rows. Application Level Parameters are those parameters that affect the entire model, regardless of scenario. Think, for example, a carbon tax or life of mine. The second row is always the study level rows. These values can be altered on a study by study basis and apply to all scenarios within that study. All other rows are scenario level rows. These rows have individual values that affect only that scenario. Flexed parameters appear in these rows.

Right click options are available in this grid to perform tasks such as setting complex values (eg a tabular input) or performing scenario operations such as clone, delete or execute.

Creating/Cloning Scenarios

Once a model has been built, data added to it, then the real power of Akumen become visible. Akumen has the power to do advanced scenario analysis. This means that users have the power to investigate the “What if” questions. Lets say that in a model there are two inputs. If we wanted to change the second input but still see the results of the original value we could do something called cloning.

As the name suggests we can clone the model we have just built to adjust certain values and still see the results of both scenarios, the original and the clone, without rebuilding the model.

When building a Driver Model there are two ways to clone a scenario. You can clone them in the Driver Model Build screen or in the Research Grid. When using Python or R, you can only clone scenarios in the Research Grid.

Cloning a Scenario on the Research Grid

1. Click on the RESEARCH tab in the top right of the screen.
2. You will be taken to the Research Grid.
3. Right click on the Baseline Scenario, often the top scenario.
   Note

   Initally, in a new model or study, the top scenario will be the Baseline Scenario. Any scenario can become the Baseline Scenario by right clicking on the scneario and selecting Set as Baseline. Once set the scenario will be greyed out and the font made bold. The Baseline Scenario is the scenario that we recommend cloning scenarios from as it should contain the default parameter values for the entire study.

4. Select clone from the options menu.
5. A new scenario will appear at the bottom of the list
6. It is recommended that all new scenarios, like studies, be given unique names so that they can be easily identified.
7. One way to rename a scenario is:
   1. Right click on the scenario again,
   2. Select properties from the options menu,
   3. A properties window will appear,
   4. You can now change the name of the scenario.
8. You can also rename a scenario by:
   1. Double clicking on the scenario name,
   2. Selecting the current text and deleting it,
   3. Then retyping the new scenario name.

Cloning a Driver Model Scenario

1. Right click on the current scenario at the bottom left of the screen in the scenario window.
2. Select clone from the options menu.
3. A new scenario will appear under your current scenario.
4. You will then be taken to your new scenario.
5. Using the steps above change the name of the cloned scenario.
6. Once the name of the scenario has been changed press okay.

Parameter Scoping

Parameter scoping is how the value of parameter affects other scenarios within the model. There are three levels of scope:

• Model Level - Any change in parameter configuration (such as numeric change, asset parameter selection change etc) or value affects all scenarios in the model.
• Study Level - Any change to the parameter affects all the scenarios in the current study. Scenarios in different studies are not affected.
• Scenario Level - Any change to the parameter affects only the current scenario.

As you can see in the image above, there are two parameters at the model level, and one at the scenario level. Changing Parameter - 1 from 5 to another value in the top row means that value is applied to every scenario. Parameter is set at the scenario level, where each value is different across each scenario.

Flexing Inputs

When you have any scenario with multiple fixed inputs and you ask the what if question, flexing is often the best way to create scenarios.

Flexing takes a scenario, asks the user what value they would like to investigate, asks for a range, and then creates a range of scenarios according to the specified range of values. It is the quickest way to create a collection of scenarios to a “What If” question.

If users decide to flex a scenario you can either flex it within the current study or you can create a new study and flex from the baseline scenario.

To flex a study:

1. Right click on the baseline scenario (the grey filled and bolded scenario).
2. Select Flex from the options menu.
3. A window will appear with all the possible inputs you can flex.
4. Select the input you would like to flex.
5. Set a starting value.
6. Set a step value.
   Note

   There is a hard limit of the number of scenarios that can be flexed at anytime (in a study). Akumen will inform you how many scenarios a flex will produce, and prevent you from exceeding the limit.

7. Set the final value.
8. Then press Generate.
9. A window will appear asking you to confirm the flex.
10. Press OK.
11. Then scenarios will be generated with new values from the stated starting value through to the stated final value.

Flexing can be done to more than one input at a time. For example you could flex the one input and then a second input at the same time with the same values. The model will create these scenarios as long as it has not reached the limit of scenarios that it can generate.

Executing Scenarios

Once you have created the scenarios that you want to investigate you will need to execute them to view the results. You can either execute a single scenario, a range of scenarios, or all the scenarios in a study.

To execute a single scenario:

1. Right click on the scenario you want to run.
2. Select Execute from the Options menu.
3. A window will appear confirming your selection.
4. Press OK.
5. The scenario will run.
6. If there are no errors it will return saying Complete, otherwise if there is an error it will come back saying Error.
7. A value will then be displayed as the result, for our model the result will appear in the calculation column.

To execute a range of scenarios:

8. Click on a scenario and drag down for the amount of scenarios you want to run.
9. Right click on the selection.
10. Select Execute from the Options menu.
11. A window will appear to confirm your selection.
12. Press OK.
13. The scenarios will run and the results will be displayed.

To execute all the scenarios in a study:

14. Click on the blue play button next to the scenario name.
15. A confirmation window will appear.
16. Select OK.
17. All the scenarios in your study will be run and the results displayed.

To view logs:

All model types record logs of their execution. In addition, adding print (or progress) calls in your code will include those statements in the run log. Right click on the scenario and click Logs to access the latest run log. In Py and R, it can also be accessed below the code editor using the Logs button.

To view run log history:

Run log history is also retained for each scenario, up to a maximum of 50 runs. Akumen will remove older logs outside the limit of 50. In addition to the history it stores the log file for that run. There is also an API call to access the run log information (see the API docs for access to the run log history). The url for this is /api/v2/models/{model_name}/execution_history

Output Protection

By default, Akumen ensures input and output consistency by resetting the run status and clearing all outputs of executed scenarios when a number of different events occur:

• Changing application code (including modifying a Value Driver Model) or changing Application Level Parameters - this will reset the run status and clear the outputs for ALL scenarios in the STUDY.
• Changing Study Level Parameters - this will reset the run status and clear the outputs for ALL scenarios in the STUDY.
• Changing Scenario Level Parameters - this will reset the run status and clear the outputs of ONLY the scenario impacted by the change.

Sometimes, this may not be the desired behaviour, especially for applications that take a long time to generate outputs. There are two ways of preserving outputs in Akumen. The first is to simply use the application, study, scenario cloning capabilities in Akumen. However this does not enforce preservation of outputs. It is up to the user (and/or security) to ensure outputs are not accidentally cleared when there is a change.

Output Protection

Output protection provides controls over what can be modified so outputs are not accidentally cleared by editing different parts of Akumen.

When an application is created, the application is created with output protection off. This means the behaviour listed above applies. An application can have it’s output protection toggled through Application Properties.

It can also be toggled in the model through the toggle next to the model name.

Output Protection status is shown by a toggle in the application manager.

Output protection changes the above behaviour as follows:

• Changing application code or Application Level Parameters can still occur, as long as there are no executed scenarios. As soon as Akumen detects one or more executed scenarios, it will prevent the operation with an error message.
• Changing Study Level Parameters can occur, as long as there are no executed scenarios within the study. As soon as Akumen detects one or more executed scenarios, it will prevent the operation with an error message.
• Changing Scenario Level Parameters can occur, as long as the scenario is not executed. If the scenario is executed, Akumen will prevent the operation with an error message.

Clearing Scenario, Study or Application outputs

Scenarios, Studies and Applications can have their outputs cleared and run status reset so they can be edited. This is a manual process through right click on the research grid, or through the Model or Study dropdown above the research grid. Once the scenario outputs are cleared, the operation can be retried.

Studies

Akumen has the potential to create hundreds of scenarios, each representing a what-if question in your model. With all these scenarios being created, it is important for users to understand how to group scenarios so that they don’t get lost. The best way to do this is through the use of Studies.

At the top of any Application there will be a dropdown menu with study written at the top (See below).

By using the dropdown menu users can sort and organize the different scenarios that have been created by cloning or flexing. Studies also allow for certain values to be used across the entire study or across all studies for ease of evaluating the best scenario to use.

To create a new study:

1. Click on the arrow next to your current study.
2. Select the plus button.
3. A pop up window will appear asking if you want to create a new study.
4. Press Okay.
5. A new study will be created and will be automatically called New Study.

When a new study is created the baseline scenario in the original study is carried through into the New Study and becomes the new study’s baseline scenario. Once a new study has been created users can rename the new study. It is always recommended that different Studies be given unique names that allow users to identify which study is which, and what types of scenarios they can expect to find in each study.

To rename a study:

1. Click on the arrow next to your current study.
2. Select the gear button.
3. This will open up the properties of the study.
4. In here you can change the name of your Study.

Study Functions:

The study functions available through the dropdown include:

• Create study (from the current study’s Baseline Scenario);
• Clone study - clones the study, including all scenarios within this study;
• Delete study - deletes the currently selected study - note there must always be one study - Akumen prevents deleting the very last study;
• Cancel study execution - cancels execution of any queued or in progress scenarios in this study;
• Reorder scenarios manually - opens a dialog allowing you to alter the order the scenarios appear in the reseach grid;
• Reorder scenarios by results - opens a dialog to allow you to set the parameter to use to reorder scenarios - once all the scenarios in the study have been executed they will be reordered using the results calculated in the parameter;
• Excel Export (Value Driver Model Only) - exports the driver model configuration to Excel; and
• Properties - opens the study properties.

The Data Tab

Once a scenario, study, or application has been executed the raw data is sent to the Data tab. The Data tab allows users to preview an query the raw results of any scenarios that have run without returning an error. This functionality works in the same way regardless of the language (Driver Models, Python or R) that is used. If a scenario runs but returns an error there will be no data to display for that scenario.

The Data screen is broken up into two sections:

• A List of Tables; and
• The Data Table.

Selecting one of the available data tables in the list will display the data in that table (when users first open the data tab the data table will be empty). This list will vary depending on what tables are generated by the application. These tables support the following functionality:

• Export Whole Table;
• Export Page; and
• Delete Table.

To access any of these functionalities simply right click on data table in the list and select from the displayed options.

When exporting the whole table be aware that this can cause issues with browsers if there is a lot of data in that particular data set. If a user reruns the application than the data tables will be recreated. By exporting tables users can import these data tables into other models in Akumen manually, however these data tables can also be directly imported into other models.

Data Tables

When a data table is selected from the list the data stored in that table is displayed. These entries can be:

• Sorted;
• Searched; and
• Viewed

Data is sorted by column. To sort the available users only need to click on the column they want to sort by. For number columns the sorting starts from 0 and goes to the maximum number. For strings, the sorting goes A-Z. Each column also displays the datatype the data is stored under. This is useful when diagnosing reporting issues and data type errors.

The Data View Search box allows the user to search the data set, using a Sql like syntax, eg "scenarioname"='Scenario' will filter on the scenario called Scenario. Note we enclose the scenarioname column name in double quotes. This is because there is the possibility that columns are case sensitive, and double quotes are required to enforce the case sensitivity in the database engine.

Setting Up the Reports Tab

Whenever a user runs scenarios in an application and and those scenarios return as complete the results are sent to the Data tab. Any table in the data tab are automatically available in the reports.

Akumen’s reports provide an interactive results dashboard where users can create graphs and other visuals in order to view their model’s results.

However the process of creating reports for Driver Model and creating reports for Python and R vary.

To access Driver Model results users need to ensure that the tick-box in the properties box of each node which says Publish to Results has been selected. If that box has not been selected then there will be no results for the query to draw from. . An chart icon will appear on the node indicating it is published to results.

For Python and R users there needs to be a specified output in the return {} or ret() section of the code. If there is no output specified then there will be no data for the reports to draw from.

For more on how to create Reports for both Driver Models, Python, and see the Reports section.

Security and Governance

There are four default user roles in Akumen, and they are organized in the following way:

• Administrators;
• Builders;
• Users; and
• Viewers.

The following points refer to the best practices surrounding setting up security for data where different groups of users are concerned.

• Users should not be an admin unless they specifically need to be. Admins can see all apps, including those that are unpublished. It is recommended that most users come under the Builder user category. This means they still do the same tasks as an admin, however they cannot see unpublished apps nor manage user accounts and security. This enables a “clean” product environment where people can work on their own creations, and then publish them for all to see once they are ready for “delivery”.

• Before the roles are established, put into place an accountability system whereby only authorized people may modify the model code/driver model, and those who just need to perform scenario analysis may not. Code and driver models do not appear for those in groups that do not have model code access.

• Use appropriate groups to lock down permissions at the study level. This means leaving at least one study where data is may be accessed by everyone in the appropriate groups, then lock down the more confidential studies.

• Although Akumen supports setting permissions for objects for specific users, groups remain the best way to lock down permissions. This allows new people, with similar roles, to come on board and to be automatically allocated permissions without requiring someone to go through all the Akumen objects and set permissions.

Version Control

Below are a list of the best practices where model versions are concerned.

• For Python/R models, Akumen supports GIT integration.

• For Driver Models, new versions of models need to be cloned.
  

  Note

  The model properties are such that all models have a test field for users to enter in version details for the model.

• Users can clone pages (including hierarchical cloning) from a completely different driver model (as long as they are authorized). This allows smaller purpose-built models to be built, and then be brought into larger models. To update the larger models, the imported pages can be deleted and reimported at a later stage.

• Make use of node assumptions. Assumptions are a free text field which can have comments added to it about the node - such as where the data has come from, what the calculation solves, and what the overall model is doing.

• Use Dockerfile in Py and R models to “fix” the Py and R version - Akumen can upgrade the version of Py and R in different releases.

Maintenance of Models

Below are a list of best practices regarding maintaining applications, assets, and pages.

• Ensure nodes are “Scoped” correctly. This means, for driver models, that the majority of the nodes have their inputs set at the application level, and a change in parameter affects all nodes in that application. Starting with v3.0, Akumen makes use of sparse input data, making large driver models extremely efficient compared to previous versions.

• Utilizing the new “Copy page from another Driver Model” feature introduced in Akumen v3.0 will allow Driver Model libraries to be created. These can be small purpose built “approved” libraries that can be thoroughly tested (e.g. unit testing) using a dummy results set that can be deployed to other models using real live data.

• Ensure only required inputs are sent to the research grid and results.

• Make use of the Akumen Pages for those that only need scenario management, and modify inputs to give them a nicer graphical front end for entering data. They can also contain help information and data dictionaries in an easy-to-use web interface.

• Ensure apps are well documented through code comments (to ensure an easy transition for new people, and an understanding for others in the organization). Driver Model calculations also support code comments, as well as assumptions, so there is no reason why apps should not be fully documented.

• Ensure that all documentation of apps, permissions and users are up to date so that if and when an Administrator user has to complete a handover they can do so without causing too much confusion for the new admin. All documentation should be written as if the person reading it has no background in Akumen, this will make training and handover less stressful for all parties and allow new users to figure out how applications are built.

Beginning the Driver Model

Before we start, we need to delete the demonstration nodes that are created by Akumen when a Value Driver Model is created. Click and hold on an area of the canvas, and drag the mouse so all the nodes are covered by the square. Release the mouse, and all nodes will be selected. Hit the delete key and accept the prompt to delete all of the nodes.

Our Driver model will be modelled in three parts:

• First, we will be modelling its operational income;
• Then we will be adding in the fixed overhead costs; and
• Last, we will address the shop’s cash reserve at the bank.

Because of this we will need three Driver Model Pages. On the left hand side of the screen you will see the pages window. We will create two sub pages from the page titled Initial Page so that we can create the different parts of the Driver Model.

1. Right click on the page titled Initial Page.
2. Select Create Sub Page.
3. Repeat the above steps again until you have two sub pages and one page.
4. Rename the Initial Page to Bank Account by right clicking on the Initial Page and hitting rename.
5. Rename one of the Driver Model Pages Operational Income.
6. And the other page Fixed Costs.

Now go to the Operational Income page. On this page we will start building our Driver Model based on the operational income.

Jack knows from experience that one cup of coffee from his Italian coffee machine costs $0.5. This is the value he would like every app to use. Hence, we put it into the Asset Library.

1. From the Palette, click and drag an Asset Parameter node onto the workspace.
2. From the popup window, select the Coffee Machine.Cost Per Cup asset parameter and click ok.
   Info

   The Asset Node on the Driver Model has a permanent link to the Asset Library. If the value of the property in the Asset Library changes, the new value will propagate to all the applications that use that property. Akumen will also create an audit trail for this property which allows users to confirm from where the value came thus giving you full traceability of, and control over the crucial numbers in your business.

3. From the Palette, click and drag a Numeric node onto the design surface underneath the asset node.
4. Click on the name to rename the node.
5. Rename the node Price per Cup.
6. Click on the value and change it to 3 (this will be our starting price for a cup of coffee).
   Info

   You will notice the different colours indicate different nodes. For example, a Numeric Node is green, an Asset Parameter Node is blue. For more information on the different types of nodes click here.

7. Click on the properties symbol on the node to bring up the properties bar on the right side of the screen.
8. There will be a tick box called Publish to Results in the properties bar. Ensure this check box is ticked so that this value gets published to the Data tab.
   Warning

   The Publish to Results tick box must be ticked in all nodes that you wish to see the results for, otherwise the values for that node will not appear in the Data tab. The nodes that are published to results have a small chart icon, and publish to research have a “hamburger” above the publish to results icon.

Now that we have our two starting values we can add our Calculation node to work out how much money would be made per cup of coffee sold.

1. From the Palette, click and drag a Calculation Node onto the design surface to the left of the asset and numeric nodes.
2. Rename the node Profit per Cup.
3. Hover over the Asset Parameter, and click and drag a link from the output of the Asset Parameter to the input of the Calculation node (Profit Per Cup).
4. Hover over the Numeric node (Price per Cup), and click and drag a link from the output of the Numeric node to the input of the Calculation node (Profit Per Cup).
5. Click on the value of the calculation (displayed as NaN which means Not a Number) to pop up the expression editor screen.
6. Click and drag the first input, Price per Cup (the Numeric node) from the left panel into the expression editor on the right.
7. Click after the text, which should look like [Price per Cup] and add a - (subtract) symbol.
8. Click and drag the second node input, Coffee Machine.Cost Per Cup (the Asset Parameter node) from the left panel to the expression editor on the right.
9. Confirm the calculation looks like [Price per Cup]-[Coffee Machine.Cost Per Cup].
10. Click OK to save the changes. Click on the “Automatic Evaluation” toggle to check if the calculation is correct - the calculation value should update with the correct number.

Add Variability

Now that we can calculate the profit per cup we need to get to our operational income, and to get that we need to add in an estimation of our monthly sales – the quantity of cups poured.

From market research, John knows that the demand for coffee in his area is a function of price. He has determined that the quantity of cups demanded per month is equal to approximately 3500 – 100 * [Price per Cup] ^ 2. However, this function does not describe his observation fully. The demand for coffee also seems to be affected by a random “noise” that John cannot explain. He decides that this noise should be modelled by a standard distribution with a mean of 0 and a standard deviation of 150.

The first thing we will do is add a Distribution node to the Driver Model. After that we will calculate the demand per month.

1. From the Palette, click and drag a Distribution node onto the workspace underneath the Price per Cup node.
2. Rename the node Demand Noise.
3. Click on the properties icon on the Distribution node.
4. Change the Mean to 0.
5. Change the StdDev to 150.
6. From the Palette, click and drag a Calculation node onto the design surface.
7. Rename the node Monthly Demand.
8. Link the Numeric node to the Calculation node.
9. Link the output of the Distribution node to the Calculation node.
10. Click on the NaN value, and enter the expression 3500 – 100 * [Price per Cup]^2 + [Demand Noise].
11. Confirm the driver model looks like the screen shot below.

Add Timeseries

Before we can forecast the operational income of the coffee shop, we need to account for another detail in our case study. Remember:

John and Jack believe they’ll need 10 weeks to set-up their new shop in the leased property.

In other words, it will take 10 weeks before they may sell their first coffee and start satisfying the demand that we calculated in the previous section using the Distribution node. For that reason, we are going to add in a Timeseries node that models the months in operation (for more information on Timeseries nodes click here).

1. From the Palette, click and drag a Timeseries node onto the design surface.
2. Rename the node Fraction of Month Operating.
3. Click on the Timeseries value (currently 0.00) to open the timeseries editor.
4. At the top of the Timeseries editor, set the number of periods to 12 and set the periods to represent monthly.
5. Enter 0.5 into the Timeseries excel cell D2 and 1 into the cells E2 through to M2, then press OK.
   Info

   The editor supports excel-like dragging of values across cell. Select the little blue circle of the cell marker for this purpose.

   

We now have our Timeseries node now, so we can now work out the monthly income while the Coffee Shop is in Operation.

1. Add a new Calculation node to the left of your previous calculations and rename it to Monthly Income.

   Info

   You can use the mouse to click and drag to pan around the driver model, or the scroll wheel of your mouse to zoom in and out if you start to run out of space on this page.

2. Connect the timeseries and the other two calculations (Profit per Cup and Monthly Demand) to the new Calculation node.

3. Set the expression for the new calculation to: [Fraction of Month Operating] * [Monthly Demand] * [Profit per Cup].

4. Confirm the driver model looks like.

We now have a forecast of the operational income for John’s coffee shop. Now that we have this we can go and model the fixed overhead costs.

Setting up the Fixed Costs

The fixed overhead costs are the next part of this coffee shop Driver Model. For this part of the tutorial we will use calculation nodes to calculate the total fixed overhead costs. To start this part of the Driver Model go to your Driver Model page titled Fixed Costs. We have a little bit of information regarding some of the fixed costs for this coffee shop. The first is the monthly rent we put into the Asset Library as part of the Coffee House Asset. The second is that Jack, who is lending the coffee machine, wants to be employed rather than a partner. Jack says that his salary will likely be 2400 a month.

First we will set up the inputs:

1. Drag an Asset Parameter node from the node palette onto the workspace.
2. Select the Coffee House.Monthly Rent Asset Attribute.
3. Then drag a Numeric node onto the workspace and name it Jacks Salary.
4. Give the Numeric node a value of 2400.

Now that we have our primary inputs, we can start adding them together using a calculation node.

1. Drag a Calculation node from the node palette onto the workspace to the the left of the Asset Parameter node.
2. Rename the node to Monthly Expenses.
3. Link the Asset Parameter node, Coffee House.Monthly Rent, to the calculation node.
4. Link the Numeric node, Jacks Salary, to the calculation node.
5. Click on the “NaN” text on the “Monthly Expenses” calculation node.
6. Enter the formula [Coffee House.Monthly Rent] + [Jacks Salary] in the expression editor.
7. Turn on automatic evaluation to observe the calculated result for Monthly Expenses.

Using a Node Reference Node

Getting the results of the two separate Driver Models onto one page requires the use of the Node Reference node. This node will take any value from any Driver Model on any of the other Driver Model pages and bring them into the current page. We will use Node Reference nodes to connect the two separate Driver Models we have just created and use them in the final one to work out the cash reserves at the bank according to the modelled income and expenses. For more information on Node Reference nodes click here.

1. Go to the Bank Account page.
2. Drag a Node Reference node from the node pallette and onto the workspace.
3. A popup screen will appear allowing you to select the node you want to reference.
4. Select Monthly Expenses as shown below.
5. Drag another Node Reference node onto the workspace.
6. This time Select Monthly Income (the Calculation node on the Operational Income page).
7. Once the two Node Reference nodes are set up drag a Calculation node onto the workspace to the left of the two Node Reference nodes.
8. Name this Calculation Cash Flow.
9. Link the two Reference nodes to the Calculation node.
10. Go into the expression editor and enter this expression into the editor [Monthly Income]-[Monthly Expenses].
11. Press OK.
12. Your driver model should look like the one below.

Now that we have connected our two driver models together we need to work out what the end of month balances will be for the shop so we can find out when John will make start making a return on the Coffee Shop.

Completing the Model

To complete the model we need to add one more node, the Prior Value node. The Prior Value node will allow us to sum up the end of month balances to find out when there will be a return on the $10000 originally put into the coffee shop.

Prior Value Nodes are used to access the value of a node from the previous time step. They are especially useful for calculating balances. Driver Models typically calculate the closing balance and the Prior Node is used to determine the opening balance, today’s opening balance is yesterday’s closing balance (for more information on Prior Value nodes click here).

1. Drag a Prior Value node onto the workspace somewhere under the Cash Flow Calculation node.
2. Rename the node Start of Month Balance.
3. Drag a Numeric node onto the workspace to the right of the Prior Value node.
4. Rename this one Start Capital.
5. Set the value fo this node to 10000.
   Note

   Prior Value Nodes are different to normal nodes in that they have two separate input ports; one on the left and one on the top. The top port is for the initial or starting value of the node and provides a value from before the first timestep, ie t = -1. This value will be used for the first timestep in the series. When the initial value is zero this input port can be left empty. The second port is for the closing value that will become the starting value for the next timestep. Hovering over each port will display a tool tip with information on the purpose of each port.

6. Connect the Numeric node to the top port of the Prior Value node.
7. Drag a Calculation node onto the workspace to the left of all the nodes.
8. Rename this node End of Month Balance.
9. Connect Cash Flow and Start of Month Balance (the Calculation node and Prior Value node) to the End of Month Balance Calculation node.
10. Go into the Expression editor for the End of Month Balance node and enter the expression [Start of Month Balance]+[Cash Flow] by dragging the two connected assets from the list into the editor.
11. Take the output of the Calculation node and connect it to the normal input port on the Prior Value (Start of Month Balance) node.

Your Driver Model should look like the image below.

Ensure the Automatic Evaluation toggle is on, then step through time to see when John will make a return on his coffee shop. You should find that by the tenth timestep the End of Month Balance should be 11350, so we can say that John will make a return at around 11 months.

You have now completed a Driver Model. The next part of the tutorial is using the Research Grid to find the best price for a cup of coffee to maximize the return. Proceed to research to learn how to research the coffee shop findings, or click here to build the same application in Python or here to build the same application in R

Add File

When you create a new application in either Python or R Akumen will take you to the code editor screen. There are Five main areas to the Code editor screen:

1. Application/Study Actions – Located at the top left-hand side are applications which show property settings.
2. Workflow Tabs – Build, Research and Report tabs all help generate and use your application.
   • In Build you will construct your application.
   • In Research you can create and manage all your scenarios.
   • In Report you visualize your results from all scenarios.
   • In Data we can view/search output values from the model. (Only present in code editor based applications).
3. Code Editor Actions – above the file view, allows you to upload scripts and models.
4. File View – On the left-hand side of the screen is a tree structure which gives you a way to organize your scripts and models.
5. Code Editor Screen – This is the main build area where you can write your models, or where the code is placed when you upload your models.

To create a new file:

1. Click on the main.py file.
2. Delete the sample code in main.py.
3. A * will appear next to the file indicating that it has been modified.
4. Enter the following into the code editor:

    def akumen(start_day, periods): 
    """ 
    Parameters: 
    - Input: start_day [datetime] 
    - Input: periods [float] 
    """ 
    return {}

The above will start our model off by allowing us to set a start date and enter the amount of time periods we will be using in the model.

5. Now that we have entered the above code, save the changes to your file.
6. Now go to the Research Tab at the top right of the screen.
7. The start_day field is a date selector cell, in the row labelled Application Level Parameters select a start date.
   Info

   Assigning a parameter to the Application Level Parameters applies the assigned value to all scenarios across the entire application. Assigning a value to the Study Level Parameters applies the assigned value to all scenarios within a single study. Any value in either of these cells will not be displayed in the scenarios within the studies.

8. The periods field is a numeric field, enter the value 12.

Modelling the Income of the Coffee Shop

John would like to invest $10,000 and open his own coffee shop. John’s good friend Jack will contribute his coffee machine to the start-up. However, Jack does not like risks and therefore wants to be employed by John rather than partnering. They have already found the location, but they believe they need 10 weeks to set it up as a café.

From market research, John knows that the demand for coffee in his area is a function of price. He has determined that the quantity of cups demanded per month equals approximately to 3500 – 100 * [Price per Cup]^2. However, this function does not describe his observation fully. The demand for coffee also seems to be affected by a random “noise” that John cannot explain. He decides to model this noise through a standard distribution with a mean of 0 and a standard deviation of 50.

John is wondering when he will make a return on his investment and Jack wants to know what the price for a cup of coffee should be.

To start modelling John’s coffee shop we need to first define what parameters contribute to the operational income. These parameters are:

• The Cost per Cup;
• Price per Cup;
• The Demand Noise; and
• How long it will take to set up the cafe.

We then need to work out what the costs to the cafe are. Currently they are the shop rent and Jack’s salary. We also know that we have a start capital of $10000. Most of these will be float values in Python, two will be asset values, and a few of our parameters will be put into a tabular entry.

Switch back to the Build tab, open the main.py file, and overwrite the contents of the file with the following code

def akumen(start_day, periods, 
           cost_per_cup, price_per_cup, demand_noise, fract_of_month_operating, 
           shop_rent, jacks_salary, start_capital, 
           **kwargs): 
    """ 
    Parameters: 
    - Input: start_day [datetime] 
    - Input: periods [float]          

    Operational Income: 
    - Input: cost_per_cup [float] 
    - Input: price_per_cup [float] 
    - Input: demand_noise [float] 
    - Input: fract_of_month_operating [tabular] (xlsx)        

    Fix costs and Accounting: 
    - Input: shop_rent [float] 
    - Input: jacks_salary [float] 
    - Input: start_capital [float]        

    Output data: 
    - Output: monthly_incomes [file] (monthly_incomes.csv) 
    - Output: monthly_balances [file] (monthly_balances.csv)
    """  
return{} 

We have a number of float values in our Python code. Float values can be assigned as Assets or can be entered as numbers or dates by users. These are the values we are going to enter first. After the float values we will address adding assets and editing tabulars to finish modelling the operational income of the coffee shop.

First we will look at entering in our float values:

1. Go back to the Research Grid and enter the following values into the Application Level Parameters row:
   • start_day: [Select today’s date]
   • periods: 12
   • demand_noise: 50
   • jacks_salary: 2400
   • start_capital: 10000
2. Enter 3 into the price_per_cup row at the scenario level.

Linking Assets

Linking Assets into Python code can be done in two ways:

• Through code; or
• Through the Research Grid

For this tutorial we will attach our two assets to the Python code as values through the Research Grid. We know that two of our values, cost per cup and monthly rent, are already in the Asset Library (if this is not the case go back to the Asset Library page and Asset Library Template page to create your Assets)

To attach the Assets to the Python code as values:

1. Make sure you are still in the Research Grid.
2. Right click on the cell in the Application Parameters Level row under the cost_per_cup column.
3. Select Select Asset from the options menu.
4. A popup window will appear asking you to select the asset for application, select the Asset Coffee Machine which will give us our cost per cup value.
5. Click Ok.
6. The cell will then go from green to blue (showing it has changed from a numeric and string cell to an asset parameter cell) and display the Asset value.
7. Right click on the cell in the Application Parameters Level row under the shop_rent column.
8. Select Select Asset from the options menu.
9. Select the Asset Coffee House from the Asset Parameter window to give the monthly rent value.
10. Click Ok.

Tabular Data

We have now entered our float values and attached our Assets, the last step we have is to enter data into our tabular input. This tabular will allow us to work out what fraction of the coffee shop will be operational over the course of the 12 months we are modelling. John and Jack believe that it will take 10 weeks before their coffee shop is ready to sell coffee. This means that for the first two months and half of the third month of the year they will not be able to sell any coffee at their cafe.

The tabular will reflect the operational months, and since this fraction will not change from study to study we can set up this table in the Application Parameters Level row. To set up the tabular:

1. Double-click on the under the fract_of_month_operating column, in the Application Parameters Level row (it will be yellow since it is a cell for tabular inputs).
2. An empty spreadsheet will open.
   Info

   This spreadsheet is very similar to an Excel spreadsheet and supports the same basic features as an Excel spreadsheet. It can upload excel spreadsheets and when data is downloaded from the cell it will display as an excel .csv.

3. Select cell A1.
4. Enter Month 1 into the cell.
5. Since this sheet is similar to that of excel you can click and drag this cell entry along until you get to cell L1 which should read Month 12.
6. Enter 0 into cell A2.
7. Enter 0 into cell B2.
8. Enter 0.5 into cell C2.
9. Enter 1 into cells D2 to L2.
   Note

   You can use the same click and drag feature for months for the other cells all requiring a fraction of 1 in them.

   
10. Your spreadsheet should now look like the one below.
11. Press the Save button in the right hand corner of the screen to save the changes to your sheet.
12. Akumen will close it and exit the sheet for you.

Now that we have set up our tabular data we can say that we have finished modelling our operational income. The next step requires putting a few more lines of code in to model the fixed costs and produce the final bank account values at the end of the month.

Finalise Application Code

Now that we have modelled our operational income and filled in all the relevant values into our Research Grid we can model our fixed costs and set up the code to find the final bank balance at the end of every time step which for this model is at the end of every month.

To model the Fixed costs and find the final bank balance we will need to exit the Research Grid and go back to the Build screen and our code editor.

Once in the build screen put the following lines of code at the top of the model:

from pandas import DataFrame 
from dateutil import parser, relativedelta 
from random import gauss 

These lines of code will allow the model import the necessary libraries to complete the calculations needed in our next few lines of code and allow us to model the noise demand that we have already defined as part of our operational income.

Once these lines are in replace the return {} at the bottom of the model with the following code:

    # Initialize model run variables 
    fract_of_month_operating = fract_of_month_operating.get('Sheet1') 
    date = parser.parse(start_day) 
    time_step = relativedelta.relativedelta(months=1) 
    account_balance = start_capital 
    monthly_incomes = [] 
    monthly_balances = []   

    # Iterate over time periods 
    for i in range(int(periods)):        
        # Calculate operational income 
        profit_per_cup = price_per_cup - cost_per_cup 
        demand = 3500 - 100 * price_per_cup**2 - gauss(0, demand_noise) 
        income = demand * profit_per_cup * fract_of_month_operating.iloc[0, i%12]      

        # Calculate operational expenses 
        fix_costs = jacks_salary + shop_rent         

        # Calculate cash flow and account balance 
        cash_flow = income - fix_costs 
        account_balance = account_balance + cash_flow         

        # Store values for output reporting 
        monthly_incomes.append([date, income]) 
        monthly_balances.append([date, account_balance])         

        # Advance model time 
        date = date + time_step 
       
    # Prepare output data 
    monthly_incomes = DataFrame(monthly_incomes, columns=['date', 'monthly_incomes']) 
    monthly_balances = DataFrame(monthly_balances, columns=['date', 'monthly_balances']) 

    return {
        'monthly_incomes': monthly_incomes, 
        'monthly_balances': monthly_balances 
    } 

The above lines of code not only Calculate the income and the costs, but also model the distribution noise, create timesteps in the model and work out and write the final bank balances to the Results tab. This is now a workable model of John and Jack’s coffee shop.

You have now completed a Python Application in Akumen. The next part of the tutorial is using the Research Grid to find the best price for a cup of coffee to maximize the return. Proceed to research to learn how to research the coffee shop findings, or click here to build the application in a Driver Model or here to build the application in R code.

Plotting Charts

Akumen can return charts, plotted through Python libraries such as MatPlotLib. By adding the following code to your Python coffee shop application you will be able to view the results of the model once the scenarios have been run. Add the following code to the bottom of the Python application, just before the return{}.

    # Images can be viewed through the Research Grid, if they are saved to outputs.
    plt = monthly_incomes.plot(x='date', y='monthly_incomes')
    fig = plt.get_figure()
    fig.savefig('outputs/monthly_income.png')
    
    plt = monthly_balances.plot(x='date', y='monthly_balances')
    fig = plt.get_figure()
    fig.savefig('outputs/monthly_balances.png')

Once you have added the code and saved your changes, rerun your model to produce new data. As soon as the scenarios have run and returned complete you can view the charts in a few different ways:

1. Access the build tab, and click on the Images icon located above the log; or
2. Access the research tab, right click on an executed scenario and select Images from the options list.

The completed main.py file should appear as follows:

from pandas import DataFrame 
from dateutil import parser, relativedelta 
from random import gauss 

def akumen(start_day, periods, 
           cost_per_cup, price_per_cup, demand_noise, fract_of_month_operating, 
           shop_rent, jacks_salary, start_capital, 
           **kwargs): 
    """ 
    Parameters: 
    - Input: start_day [datetime] 
    - Input: periods [float]          

    Operational Income: 
    - Input: cost_per_cup [float] 
    - Input: price_per_cup [float] 
    - Input: demand_noise [float] 
    - Input: fract_of_month_operating [tabular] (xlsx)        

    Fix costs and Accounting: 
    - Input: shop_rent [float] 
    - Input: jacks_salary [float] 
    - Input: start_capital [float]        

    Output data: 
    - Output: monthly_incomes [file] (monthly_incomes.csv) 
    - Output: monthly_balances [file] (monthly_balances.csv)
    """  
    
    # Initialize model run variables 
    fract_of_month_operating = fract_of_month_operating.get('Sheet1') 
    date = parser.parse(start_day) 
    time_step = relativedelta.relativedelta(months=1) 
    account_balance = start_capital 
    monthly_incomes = [] 
    monthly_balances = []   

    # Iterate over time periods 
    for i in range(int(periods)):        
        # Calculate operational income 
        profit_per_cup = price_per_cup - cost_per_cup 
        demand = 3500 - 100 * price_per_cup**2 - gauss(0, demand_noise) 
        income = demand * profit_per_cup * fract_of_month_operating.iloc[0, i%12]      

        # Calculate operational expenses 
        fix_costs = jacks_salary + shop_rent         

        # Calculate cash flow and account balance 
        cash_flow = income - fix_costs 
        account_balance = account_balance + cash_flow         

        # Store values for output reporting 
        monthly_incomes.append([date, income]) 
        monthly_balances.append([date, account_balance])         

        # Advance model time 
        date = date + time_step 
       
    # Prepare output data 
    monthly_incomes = DataFrame(monthly_incomes, columns=['date', 'monthly_incomes']) 
    monthly_balances = DataFrame(monthly_balances, columns=['date', 'monthly_balances']) 

    # Images can be viewed through the Research Grid, if they are saved to outputs.
    plt = monthly_incomes.plot(x='date', y='monthly_incomes')
    fig = plt.get_figure()
    fig.savefig('outputs/monthly_income.png')
    
    plt = monthly_balances.plot(x='date', y='monthly_balances')
    fig = plt.get_figure()
    fig.savefig('outputs/monthly_balances.png')
    
    return {
        'monthly_incomes': monthly_incomes, 
        'monthly_balances': monthly_balances 
    } 

Add File

When you create a new application in either Python or R Akumen will take you to the code editor screen. There are Five main areas to the Code editor screen:

1. Application/Study Actions – Located at the top left-hand side are applications which show property settings.
2. Workflow Tabs – Build, Research and Report tabs all help generate and use your application.
   • In Build you will construct your application.
   • In Research you can create and manage all your scenarios.
   • In Report you visualize your results from all scenarios.
   • In Data we can view/search output values from the model. (Only present in code editor based applications).
3. Code Editor Actions – above the file view, allows you to upload scripts and models.
4. File View – On the left-hand side of the screen is a tree structure which gives you a way to organize your scripts and models.
5. Code Editor Screen – This is the main build area where you can write your models, or where the code is placed when you upload your models.

1. Click on the main.r file.
2. Delete the sample code in main.r.
3. A * will appear next to the file.
4. Enter the following into the code editor:

akumen <- function(start_day, periods,...) { 
    # Parameters: 
    #- Input: start_day [datetime] 
    #- Input: periods [float] 
    return () 
} 

The above will start our model off by allowing us to set a start date and enter the amount of time periods we will be using in the model.

5. Now that we have entered the above code, save the changes to your file.
6. Now go to the Research Tab at the top right of the screen.
7. The start_day field is a date selector cell, in the row labelled Application Level Parameters select a start date.
   Info

   Assigning a parameter to the Application Level Parameters applies the assigned value to all scenarios across the entire application. Assigning a value to the Study Level Parameters applies the assigned value to all scenarios within a single study. Any value in either of these cells will not be displayed in the scenarios within the studies.

8. The periods field is a numeric field, enter the value 12.

Modelling a Coffee Shop

John would like to invest $10,000 and open his own coffee shop. John’s good friend Jack will contribute his coffee machine to the start-up. However, Jack does not like risks and therefore wants to be employed by John rather than partnering. They have already found the location, but they believe they need 10 weeks to set it up as a café.

From market research, John knows that the demand for coffee in his area is a function of price. He has determined that the quantity of cups demanded per month equals approximately to 3500 – 100 * [Price per Cup]^2. However, this function does not describe his observation fully. The demand for coffee also seems to be affected by a random “noise” that John cannot explain. He decides to model this noise through a standard distribution with a mean of 0 and a standard deviation of 50.

John is wondering when he will make a return on his investment and Jack wants to know what the price for a cup of coffee should be.

To start modelling John’s coffee shop we need to first define what parameters contribute to the operational income. These parameters are:

• The Cost per Cup;
• Price per Cup;
• The Demand Noise; and
• How long it will take to set up the cafe.

We then need to work out what the costs to the cafe are. Currently they are the shop rent and Jack’s salary. We also know that we have a start capital of $10000. Most of these will be float values in R, a two will be asset values, and a few of our parameters will be put into a tabular entry.

Switch back to the Build tab, open the main.r file, and overwrite the contents of the file with the following code

# Load Libraries 
library(lubridate) 

akumen <- function (start_day, periods, 
           cost_per_cup, price_per_cup, demand_noise, fract_of_month_operating, 
           shop_rent, jacks_salary, start_capital, 
           ...) {    
    # Parameters: 
    # - Input: start_day [datetime] 
    # - Input: periods [float]          

    # Operational Income: 
    # - Input: cost_per_cup [float] 
    # - Input: price_per_cup [float] 
    # - Input: demand_noise [float] 
    # - Input: fract_of_month_operating [tabular] (xlsx)        

    # Fix costs and Accounting: 
    # - Input: shop_rent [float] 
    # - Input: jacks_salary [float] 
    # - Input: start_capital [float]        

    # Output data: 
    # - Output: monthly_incomes [file] (monthly_incomes.csv) 
    # - Output: monthly_balances [file] (monthly_balances.csv)
return ()
} 

We have a number of float values in our R code. Float values can be assigned as Assets or can be entered as numbers or dates by users. These are the values we are going to enter first. After the float values we will address adding assets and editing tabulars to finish modelling the operational income of the coffee shop.

First we will look at entering in our float values:

1. Go back to the Research Grid and enter the following values into the Application Level Parameters row:
   • start_day: [Select today’s date]
   • periods: 12
   • demand_noise: 50
   • jacks_salary: 2400
   • start_capital: 10000
2. Enter 3 into the price_per_cup row at the scenario level.

Linking Assets

Linking Assets into R code can be done in two ways:

• Through code; or
• Through the Research Grid

For this tutorial we will attach our two assets to the R code as values through the Research Grid. We know that two of our values, cost per cup and monthly rent, are already in the Asset Library (if this is not the case go back to the Asset Library page and Asset Library Template page to create your Assets)

To attach the Assets to the R code as values:

1. Make sure you are still in the Research Grid.
2. Right click on the cell in the Application Parameters Level row under the cost_per_cup column.
3. Select Select Asset from the options menu.
4. A popup window will appear asking you to select the asset for application, select the Asset Coffee Machine which will give us our cost per cup value.
5. Click Ok.
6. The cell will then go from green to blue (showing it has changed from a numeric and string cell to an asset parameter cell) and display the Asset value.
7. Right click on the cell in the Application Parameters Level row under the shop_rent column.
8. Select Select Asset from the options menu.
9. Select the Asset Coffee House from the Asset Parameter window to give the monthly rent value.
10. Click Ok.

Tabular Data

We have now entered our float values and attached our Assets, the last step we have is to enter data into our tabular input. This tabular will allow us to work out what fraction of the coffee shop will be operational over the course of the 12 months we are modelling. John and Jack believe that it will take 10 weeks before their coffee shop is ready to sell coffee. This means that for the first two months and half of the third month of the year they will not be able to sell any coffee at their cafe.

The tabular will reflect the operational months, and since this fraction will not change from study to study we can set up this table in the Application Parameters Level row. To set up the tabular:

1. Double-click on the under the fract_of_month_operating column, in the Application Parameters Level row (it will be yellow since it is a cell for tabular inputs).
2. An empty spreadsheet will open.
   Info

   This spreadsheet is very similar to an Excel spreadsheet and supports the same basic features as an Excel spreadsheet. It can upload excel spreadsheets and when data is downloaded from the cell it will display as an excel .csv.

3. Select cell A1.
4. Enter Month 1 into the cell.
5. Since this sheet is similar to that of excel you can click and drag this cell entry along until you get to cell L1 which should read Month 12.
6. Enter 0 into cell A2.
7. Enter 0 into cell B2.
8. Enter 0.5 into cell C2.
9. Enter 1 into cells D2 to L2.
   Note

   You can use the same click and drag feature for months for the other cells all requiring a fraction of 1 in them.

   
10. Your spreadsheet should now look like the one below.
11. Press the Save button in the right hand corner of the screen to save the changes to your sheet.
12. Akumen will close it and exit the sheet for you.

Now that we have set up our tabular data we can say that we have finished modelling our operational income. The next step requires putting a few more lines of code in to model the fixed costs and produce the final bank account values at the end of the month.

Finalise Application Code

Now that we have modelled our operational income and filled in all the relevant values into our Research Grid we can model our fixed costs and set up the code to find the final bank balance at the end of every time step which for this model is at the end of every month.

To model the Fixed costs and find the final bank balance we will need to exit the Research Grid and go back to the Build screen and our code editor.

Once there, copy the code below over the “return ()” statement at the bottom of the main.r file, ensuring that the closing bracket has not been copied over:

    # Initialize model run variables 
    date <- as.Date(start_day) 
    time_step <- months(1) 
    account_balance <- start_capital 

    n <- as.integer(periods) 

    monthly_incomes <- data.frame(date = as.Date(n, origin = "1900-01-01"), monthly_incomes = numeric(n), stringsAsFactors=FALSE) 

    monthly_balances <- data.frame(date = as.Date(n, origin = "1900-01-01"), monthly_balances = numeric(n), stringsAsFactors=FALSE) 

    # Iterate over time periods 
    for (i in 1:n) { 
        # Calculate operational income 
        profit_per_cup <- price_per_cup - cost_per_cup 
        demand <- 3500 - 100 * price_per_cup**2 - rnorm(1, 0, demand_noise) 
        income <- demand * profit_per_cup * as.numeric(fract_of_month_operating[['Sheet1']][1,i])

        # Calculate operational expenses 
        fix_costs <- jacks_salary + shop_rent   

        # Calculate cash flow and account balance 
        cash_flow <- income - fix_costs 
        account_balance <- account_balance + cash_flow         

        # Store values for output reporting 
        monthly_incomes$date[i] <- date 
        monthly_incomes$monthly_incomes[i] <- income 
        monthly_balances$date[i] <- date 
        monthly_balances$monthly_balances[i] <- account_balance        

         # Advance model time 
        date <- date + time_step 
    }    

    # The akumen() function must return a dictionary including keys relating to outputs. 
    ret <- list() 

    ret[["monthly_incomes"]] <- monthly_incomes 

    ret[["monthly_balances"]] <- monthly_balances 

    return(ret) 

The above lines of code not only Calculate the income and the costs, but also model the distribution noise, create timesteps in the model and work out and write the final bank balances to the Results tab. This is now a workable model of John and Jack’s coffee shop which we can use for finding answers to their two questions:

• What is the best price for a cup of coffee?
• When is the coffee shop making its return on investment?

The completed main.r file should appear as follows:

# Load Libraries 
library(lubridate) 

akumen <- function (start_day, periods, 
           cost_per_cup, price_per_cup, demand_noise, fract_of_month_operating, 
           shop_rent, jacks_salary, start_capital, 
           ...) {
    # Parameters:
    # - Input: start_day [datetime]
    # - Input: periods [float]

    # Operational Income:
    # - Input: cost_per_cup [float]
    # - Input: price_per_cup [float]
    # - Input: demand_noise [float]
    # - Input: fract_of_month_operating [tabular] (xlsx)

    # Fix costs and Accounting:
    # - Input: shop_rent [float]
    # - Input: jacks_salary [float]
    # - Input: start_capital [float]

    # Output data:
    # - Output: monthly_incomes [file] (monthly_incomes.csv)
    # - Output: monthly_balances [file] (monthly_balances.csv)

    # Initialize model run variables
    date <- as.Date(start_day)
    time_step <- months(1)
    account_balance <- start_capital

    n <- as.integer(periods)

    monthly_incomes <- data.frame(date = as.Date(n, origin = "1900-01-01"), monthly_incomes = numeric(n), stringsAsFactors=FALSE)

    monthly_balances <- data.frame(date = as.Date(n, origin = "1900-01-01"), monthly_balances = numeric(n), stringsAsFactors=FALSE)

    # Iterate over time periods
    for (i in 1:n) {
        # Calculate operational income
        profit_per_cup <- price_per_cup - cost_per_cup
        demand <- 3500 - 100 * price_per_cup**2 - rnorm(1, 0, demand_noise)
        income <- demand * profit_per_cup * as.numeric(fract_of_month_operating[['Sheet1']][1,i])

        # Calculate operational expenses
        fix_costs <- jacks_salary + shop_rent

        # Calculate cash flow and account balance
        cash_flow <- income - fix_costs
        account_balance <- account_balance + cash_flow

        # Store values for output reporting
        monthly_incomes$date[i] <- date
        monthly_incomes$monthly_incomes[i] <- income
        monthly_balances$date[i] <- date
        monthly_balances$monthly_balances[i] <- account_balance

         # Advance model time
        date <- date + time_step
    }

    # The akumen() function must return a dictionary including keys relating to outputs.
    ret <- list()

    ret[["monthly_incomes"]] <- monthly_incomes

    ret[["monthly_balances"]] <- monthly_balances

    return(ret)
}