Structure

Scenario Identifier

The scenario identifier is used to reference scenario data under the scenarioData node, or historical data under the historicalData node, or both. It allows you to define an association of a type with zero up to six parameters:

"id": {
    "type": "XXX",
    "parameters": [
        ["param1"[,"param2"[,"param3"[,"param4"[,"param5"[,"param6"]]]]]]
    ]
}

MetaData

The metaData object lists the properties linked to a scenario identifier. When the metadata is available, they can be located either on the scenarioData node, or on the historicalData node.

"metaData": {
    "stringKey": "Item",
    "dateKey": "2017-07-14",
    "doubleKey": 3.1415,
    "boolean": false,
    "numberArrayKey": [
        10,
        2.2,
        0.1
    ],
    "stringArrayKey": [
    "arrayItem1",
    "arrayItem2",
    "arrayItem3"
    ],
    "dateArrayKey": [
        "2017-01-01",
        "2017-02-01",
        "2017-03-01"
    ],
    "booleanArrayKey": [
        true,
        false
    ]
}

Axes

The axes are combinations of coordinates represented by \(x\), \(y\) and \(z\):

  • Case \(\varnothing\) (empty): corresponds to data0D (contains a single value).
  • Case \(x\): corresponds to data1D (contains an array of \(x\) values).
  • Case \(x, y\): corresponds to data2D (contains a matrix of \(x \times y\) values).
  • Case \(x, y, z\): corresponds to data3D (contains a cube of \(x \times y \times z\) values).

Note that for data2D and data3D, the platform expects a dense input:

  • For data2D: any x must be combined with any y, i.e. \(x \times y\) values.
  • For data3D: any x must be combined with any y and z, i.e. \(x \times y \times z\) values.

data0D, data1D , data2D and data3D are functions provided by the FPP common library in the DataAccess.module.

Dates

The calculation dates for which a script will be executed need to be defined as an array of dates. These dates must be also referred within the scenario points.

"dates": [
    "2010-01-20",
    "2011-03-10",
    "2012-11-22"
]

Scenario Data

Scenario Values

Scenario values are gathered in an array of doubles, the scenario values.

Scenario dates

Scenario dates are the dates for which you have scenario values.

Scenario Points

Scenario points are lists of axes and scenario values taken by a scenario data for a given array of scenario dates:

  • case \(\varnothing\) (empty), no points:
"points": {
    "2017-04-19": []
}
  • data0D with 2 dates and 3 scenarios each:
"points": {
    "2017-04-19": [{
        "values": [
            1.05,
            1.06,
            1.07
        ]
    }],
    "2018-07-21": [{
        "values": [
            1.021,
            1.069,
            1.087
        ]
    }]
}
  • data1D with 2 dates and 2 scenarios each:
"points": {
    "2017-04-19": [{
        "x": 12,
        "values": [
            1.05,
            1.07
        ]
    }],
    "2018-07-21": [{
        "x": 13,
        "values": [
            1.069,
            1.087
        ]
    }]
}
  • data2D with 1 date and 3 scenarios each:
"points": {
    "2017-04-19": [{
        "x": 12,
        "y": 0,
        "values": [
          2,
          5,
          3
        ]
      },{
        "x": 12,
        "y": 3,
        "values": [
          2.2,
          0,
          37
        ]
      },{
        "x": 81,
        "y": 0,
        "values": [
          42,
          42,
          42
        ]
      },{
        "x": 81,
        "y": 3,
        "values": [
          1,
          2,
          3
        ]
      }
    ]
}

Note that the number of scenario must be consistent for all scenario dates of all scenario data and that data2D and data3D structures must be dense – no sparsity is allowed.

Scenario Data

Scenario data refers to the association of the following nodes:

  • id (scenario identifier)
  • [metaData]
  • points
{
  "id": {
    "type": "FX",
    "parameters": [
      "EUR",
      "USD"
    ]
  },
  "points": {
    "2017-04-19": [{
      "values": [
        1.065,
        1.0654
      ]
    }],
    "2017-04-20": [{
      "values": [
        1.066,
        1.0659
      ]
    }]
  }
}

scenarioData

scenarioData is an array of scenario data:

[{
  "id": {
    "type": "FX",
    "parameters": [
      "EUR",
      "USD"
    ]
  },
  "points": {
    "2017-04-19": [{
      "values": [
        1.065,
        1.0654
      ]
    }],
    "2017-04-20": [{
      "values": [
        1.066,
        1.0659
      ]
    }]
  }
}, {
  ... // other scenario data associations
}]

Historical Data

Historical Values

The historical data are gathered in an array containing a single double.

Historical Dates

These are the dates for which you have historical values.

Historical Points

Historical points are lists of axes and historical values taken by a historical data given the historical dates. Beware that for a historical date, the number of scenarios must be equal to 1. Also note that the number of historical dates can vary from one scenario identifier to another.

  • historicalData0D:
"points": {
  "2016-07-14": [{
    "values": [
      1.023
    ]
  }],
  "2016-07-21": [{
    "values": [
      1.021
    ]
  }]
}
  • historicalData1D:
"points": {
  "2016-07-14": [{
    "x": 12,
    "values": [
      2
    ]
  },{
    "x": 81,
    "values": [
      1
    ]
  }],
  "2016-07-21": [{
    "x": 12,
    "values": [
      12
    ]
  },{
    "x": 81,
    "values": [
      11
    ]
  }]
}

Historical Data

Historical data refers to the association of the following nodes:

  • id (scenario identifier)
  • [metaData]
  • points
{
  "id": {
    "type": "FX",
    "parameters": [
      "EUR",
      "USD"
    ]
  },
  "points": {
    "2016-07-14": [{
      "values": [
        1.023
      ]
    }],
    "2016-07-21": [{
      "values": [
        1.021
      ]
    }]
  }
}

historicalData

historicalData is an array of historical data:

[{
  "id": {
    "type": "FX",
      "parameters": [
        "EUR",
        "USD"
      ]
  },
  "points": {
    "2016-07-14": [{
      "values": [
        1.023
      ]
    }],
    "2016-07-21": [{
      "values": [
        1.021
      ]
    }]
  }
},{
  ... // other historical data associations
}]

Calendars

Definition

A calendar has three properties:

  • start: the start date of the calendar
  • end: the end date of the calendar
  • dates: business dates of the calendar, which must be between "start" and "end"

Calendars are read-only structure provided by the user through the DataManager. In addition to the three properties above, calendars provided to the DataManager must be identified by an ID.

To provide calendars from JSON file to pricing data, you must comply with the following JSON structure:

{
  "calendars": [
    { "id" : "calendar1",
      "start":"1970-01-01",
      "end" : "1970-01-03",
      "dates" : ["1970-01-02"]
    },
    { "id" : "calendar2",
      "start":"2000-01-01",
      "end" : "2000-01-03",
      "dates" : ["1970-01-02"]
    }
  ]
}

Calendars Functions

calendar

Get a calendar from its ID.

calendar = calendar("id")

calendarContains

Is the given date present in the calendar.

if( calendarContains(calendar, "1970-01-01") )
    // ...

daysBetween

Returns the number of business dates present in the calendar between the two given dates.

return daysBetween(calendar, "1970-01-01", "2000-01-01")

union

Performs a calendar union.

union = union(cal1, cal2)

The returned calendar has the following properties:

  • start: min start of (cal1, cal2)
  • end: max end of (cal1, cal2)
  • dates: dates union of (cal1, cal2)

intersection

Performs a calendar intersection.

intersection = intersection (cal1, cal2)

The returned calendar has the following properties:

  • start: min start of (cal1, cal2)
  • end: max end of (cal1, cal2)
  • dates: dates intersection of (cal1, cal2)

To illustrate the usage of the calendar functions, a sample script configuration is provided to you: Tutorial_Calendars

From Theory to Practice

In this part, we use the knowledge provided in the previous parts through a real example - the structure of a pricing data file which includes the following nodes:

\[ \text{pricing data (.scn)} = dates + scenario data + historicalData + configuration + calendars \]

Format of the Scenario Data Field

Scenario data is a store of scenario values:

  • id: the scenario Identifier gathers both the type and parameters of the scenario data. The types can be yield curve, foreign exchange rate or volatility, correlation, etc. The parameters will refer to USD Libor and discount factors, USD swaption ATM volatility and log-normal or expiry dates for instance.
  • metaData: this optional node contains static data providing information about the scenario data itself. This can be the currency, zero coupon basis or interpolation methods for a discount curve and can also be the volatility basis, quotation type or expiry interpolation method for a volatility surface.
  • points: these are list of axes (0 to 3) and scenario values for each calculation date. For example, \(x\), \(y\) and \(z\) can represent respectively the strike, expiry and maturity of a volatility cube.

Below you have a scenario data sample:

"dates": [
    "2010-01-20",
    "2011-03-10",
    "2012-11-22"
  ],
"scenarioData": [
    {
    "id": {
      "parameters": [
        "FTSE100"
      ],
      "type": "EQUITY"
    },
    "metaData": {
        "currency": "EUR",
        "curveDate": "2010-01-20",
        "switchDates": [],
        "interpolationVariables": [
          "zeroCouponRate"
        ],
        "interpolationMethods": [
          "linear"
        ],
        "zeroCouponFormula": "exponential",
        "zeroCouponBasis": "ACT/360"
      },
      "points": {   // points are defined for each scenario date defined in the "dates" field
        "2010-01-20": [
          {
            "values": [
              0.7843315,
              0.77538679,
              0.7614555,
              0.76718513,
              0.75198465,
              0.77925854,
              0.77274491,
              0.79083359,
              0.79465029,
              0.76830421
            ]
          }
        ],
        "2011-03-10": [
          {
            "values": [
              0.7843315,
              0.77538679,
              0.7614555,
              0.76718513,
              0.75198465,
              0.77925854,
              0.77274491,
              0.79083359,
              0.79465029,
              0.76830421
            ]
          }
        ],
        "2012-11-22": [
          {
            "values": [
              0.7843315,
              0.77538679,
              0.7614555,
              0.76718513,
              0.75198465,
              0.77925854,
              0.77274491,
              0.79083359,
              0.79465029,
              0.76830421
            ]
          }
        ]
      }
    },
    ...  // other scenario data associations
  ]

Format of the Historical Data Field

The values of historical data represent past uni-dimensional data. We do not use historical data in our tutorials.

  • id: same than for the scenario data.
  • metaData: same optional node than for the scenario data.
  • points: these are list of axes (0 to 3) and historical values (only 1) for each historical date. For each date there must be only 1 scenario value.

Here is an example:

"historicalData" : [
  {
    "id": {
      "type": "FX",
      "parameters": [
        "EUR",
        "USD"
      ]
    },
    "points": {
      "2016-07-14": [
        {
          "values": [
            1.023
          ]
        }
      ],
      "2016-07-21": [
        {
          "values": [
            1.021
          ]
        }
      ]
    }
  },
  ... // other historical data associations
]