Of the many features that help TruePlanning stand out as the premier predictive cost analytics tool, TruePlanning’s ability to calibrate is frequently cited by users as the most important feature in TruePlanning. Users can create models that are highly tuned to the organizations and processes that they are modelling. The 50,000-foot description of calibration is to increase the fidelity of a model to a known process or organization by using ‘actuals’ (known result data) and driving TruePlanning inputs so that the known values are obtained.

A concrete example would be knowing the number of hours it took create a piece of software and adjusting the Organizational Productivity to get to the known number of hours. The Organizational Productivity input is a good choice for an input to be calibrated because it is a TruePlanning specific measure of an organization’s general efficiency.

Many TruePlanning users will want to perform the calibration process in ‘bulk’ because they will obtain the actual data in a dump from an accounting system or some other data store and will got lots of data at one time for multiple TruePlanning Cost Objects. The TruePlanning Excel Solution provided access to bulk calibration using the TruePlanning API. Other users build, or had PRICE build custom calibration tools. TruePlanning’s API has always had the required features to allow users to perform the steps required to perform calibration, but it was ‘an exercise left to the student’ in that users needed to build up the process manually. The benefit of this was that users could perform calibrations exactly the way they wanted to.

There were some downsides to having to create the calibration process from scratch in the API. One was the effort to build up all of the steps involved in calibration: targeting the right Cost Object, getting to the right Input, repeatedly setting the value, testing the results, and so on. A second issue was that because all the behaviors were occurring outside of TruePlanning as individual steps. The same input was being set, the entire model was being calculated, and the results were obtained and tested over and over again. A third issue was the fact that there was no guarantee that each calibration process that was created followed the exact same rules or work the same way.

The TruePlanning application has had, since its inception, a GUI based calibration process. This process was not, however, exposed through the API… Until now! With TruePlanning 2016 (16.0.6187.2) users have access to a calibration process through the API. This means users will gain the benefits of access to an easy to use, repeatable, and better performing calibration process through the API.  It’s easy to use because it’s a simple object with a few parameters. Its repeatable because the same code will be executed for each calibration. Its better performing because the data will not need to ‘round trip’ between the API and TruePlanning, and instead the data stays in TruePlanning through the entire calibration process.

The heart of the calibration feature of the TruePlanning API is the “Calibration” object. It has multiple parameters and two methods that are used to set up a standard calibration.  There are other properties and methods not listed below that will be covered in future blogs and are covered by the TruePlanning COM API documentation.

 

Properties  Name Type Example Information
Input CostObjectOutput String Software_App.Software_
Assembly. LoginComponent::
Labor Requirement
The CostObjectOutput property defines the value in the estimate for which there is an actual value. The string is the “path” to the target Cost Object made up of the Cost Objects that are parents to the target Cost Object as well as the target Cost Object itself. At the end of the path the is a “::” and then the metric value being targeted. Cost Objects are separated by a “.” Character. In the provided example, the Labor Requirement value for the “LoginComponent” Cost Object in the is targeted. The parent Cost Objects, “Software_App” and “Software_Assembly” are listed before “LoginComponent” in the path.
Input Tolerance Number 1 This value defines how close the calibration needs to get to the target value to be considered successful. A min and max value are calculated from the target value based on the provided tolerance percent. A number that represents the percentage is provided. A value of “1” means 1%. A value of “5” would be 5%. A value of “0.1” would be 1/10 of a percent. For example, if the target value were 1000 and the tolerance was set to 1 then the calibration would be successful when the resulting target value was >= 990 and <= 1010.
Input MaxIterations Number 100 This value defines the number of attempts that will be made during the calibration. With each iteration a new value of the selected input will set, then the project will be calculated, and then the results will be checked to see if they are within the tolerances set for the resulting target.
Input Target Number 1000 This is the value that the calibration is aiming to obtain for the value set by the “CostObjectOutput” parameter. In this example the “Labor Requirement” for the “LoginComponent” was specified, so the “Target” property will tell the calibration, when run, to vary the specified Input until a “Labor Requirement” value, within specified tolerances, is found. With the tolerance set to 1, this means a value for “Labor Requirement” between 990 and 1010 would be a successful calibration.
Output CalibratedInput Number 4.2 This is the first value that achieves getting the target value within tolerances. In this example an Organizational Productivity value of 4.2 produces a “Labor Requirement” that is within tolerances.
Output OutputName String Labor Requirements The name of the target for the calibration. In this example, it is “Labor Requirement”.
Output OutputAnswer String 1006 This is the value of the target of the calibration that is obtained when the “CalibratedInput” value is used. In this example, if an Organizational Productivity is set for the selected input, the “Labor Requirement” for the selected target is 1006.
Output LastInteration Number 8 The number of iterations the calibration performed to get an input value that produces a target value that is within tolerances. In this example, the calibration process ran 8 iterations.
         
Methods        
  SetInput TruePlanningApi _16_0.Input  calibrationTest.SetInput tpInputVar This method requires a TruePlanningApi_16_0.Input object. It sets the Input that will be used in the calibration. Because a TruePlanningApi_16_0.Input object is used, the calibration knows which Cost Object the input belongs to. In this example, (per the snippet of code below) the input selected is “Organizational Productivity”.
  Run N/A calibrationTest.Run This initiates the running of the calibration.

 

The following is a simple snippet of code showing the use of the new calibration feature of the API in VBA:

‘ this is a snippet of code, the full code can be provided upon request

 

‘ costObject and proj variables are declared earlier

Dim tInput as TruePlanningApi_16_0.Input

Set tInput = costObject.Inputs.ItemByName(“Organizational Productivity”)

 

Dim cTest As TruePlanningApi_16_0.Calibration

Set cTest = proj.Calibrations.New("COne")

 

cTest.SetInput tInput

targetOutputPath = costObject.Path & "::Labor Requirement"

cTest.CostObjectOutput = targetOutputPath

cTest.Tolerance = 1  ' this is a % value 1 = 1%, 10 = 10%

cTest.MaxIterations = 100

cTest.Target = 1000

cTest.Run

 

dim outputNumb as double

outputNumb = cTest.CalibratedInput  ‘ 4.2

outputNumb = cTest.OutputAnswer     ‘ 1006

outputNumb = cTest.LastIteration    ‘ 8

 

Dim outputStr as string

outputStr = cTest.OutputName ‘ Labor Requirement

 

Our “inside” behavior of calibration is now “out”. To those familiar with the TruePlanning API, setting up a calibration is now very simple, and highly repeatable.

If you would like a working sample in Excel VBA, let us know.

Please feel free to contact PRICE if you have any questions about this feature, TruePlanning, TrueMapper, or any other PRICE products and services.