Molecule's trade valuation supports the computation of prices (for trade prices, marks, underlying values, and more) using a formula parser. This article describes the syntax it expects.
Price formulas are a combination of numerical constants, mathematical operators, and functions.
Constants are simple, numerical values such as
0.25. Constants are typically used to capture a premium or discount value.
Operators are the typical mathematical functions such as addition (
+), subtraction (
-), multiplication (
*), division (
/) and power (
Functions take inputs and perform specialized tasks to return an output. They provide the majority of the horsepower for the formula parser.
average- Returns the mathematical average of the input values
average(1.5, 2.5, 3.5, 4.5)yields a value of 3.0
min- Returns the minimum value of the input values
min(1.5, 2.5, 3.5, 4.5)yields a value of 1.5
max- Returns the maximum value of the input values
max(1.5, 2.5, 3.5, 4.5)yields a value of 4.5
round- Returns the input value, rounded to the precision specified
round(1.2345, 2)yields a value of 1.23
roundup- Returns the input value, rounded up, based on the precision specified
roundup(1.2345, 2)yields a value of 1.24
rounddown- Returns the input value, rounded down, based on the precision specified
rounddown(1.2345, 2)yields a value of 1.23
iffunction evaluates an input expression and returns the value of another depending on if the predicate expression is evaluated as true or false. Typical comparisons such as equal (
==), not equal (
!=), less than (
<), less than or equal (
<=), greater than (
>) and greater than or equal (
>=) can be leveraged in the predicate expression.
This is a special Molecule function used for looking up mark values. Unlike other functions which are referenced by a specific name, this one is used by referencing a Molecule ticker, such as CL or LO. Additional inputs, such as contract dates and as_of dates, are supported for explicitly defining the mark(s) to be queried.
The full syntax of the mark lookup function is
TICKER[call/put strike](contract date as_of date).
CL(2023-12-01, 2023-10-13)yields a value of 86.35, the mark for a December 2023 CL contract on 10/13/2023.
LO[call 95.0](2023-12-01, 2023-10-13)yields a value of 2.02, the mark for a December 2023 $95 LO call on 10/13/2023.
In many situations, additional context is automatically provided to the formula resolver to alleviate the need to explicitly define all of the inputs to the mark function. For example, when running valuations for a specific trade entry, the contract date and the as_of date are provided to the formula resolver from the entry. This means that a simple ticker, such as
CL, is a perfectly valid formula to be used on a trade. Using the example of a simple formula like
CL on a trade, the formula resolver will resolve a value by looking for a mark for product
CL where the contract date and as_of date equal those of the entry being valued.
Tickers can also be defined with a few special notations to reference points on a curve relative to the contract of the formula being resolved. Here are some examples:
:n- Following a ticker with a colon and an optional integer, such as
CL:2, will result in a mark lookup for the nth contract on the specified product's curve, where the first contract is that which is provided by the formula. For example, when valuing an entry with a contract date of 2023-12-01 and a formula of
CL:2, the formula resolver will return the value from the January 2024 CL contract. Likewise,
CL:3results in the value from the February 2024 CL contract.
!n- Following a ticker with an exclamation point and an optional integer, such as
CL!, will result in a mark lookup for the nth contract on the specified product's curve, where the first contract is the prompt contract on the entry's settlement date. For example, to value a December 2023 Crude swap that settles on the last business day of December, 2023, based on the prompt contract of the CL curve, the formula
CL!is your answer. This will return the value from the February 2024 CL contract which would be the prompt contract on December 29th, 2023.
The spot function is used to query marks over a range of as_of dates and return only those where the as_of date equals the contract date. This is typically used with daily products and nested inside of an aggregate function, like average, to find the average of daily prices over a period.
spot(PDP(2023-10-01..2023-10-31) will return all of the marks for product PDP between October 1st and October 31st where the as_of date equals the contract date. This formula can be nested inside of the average function, like
average(spot(PDP(2023-10-01..2023-10-31)), to yield the average of all of the PDP settlement marks in October.
The best function accepts multiple mark lookup expressions as inputs, evaluates each of them, and returns what is evaluated as the best mark. To determine the best mark, the function first looks at the mark level of each. In the case of multiple marks having the same mark level, the leftmost input is returned.
best(M.XXXX, H + PAN) + 0.02 is an example of how to price a trade of ICE's XIM product. In this example, M.XXXX represents a Molecule product used for capturing the final settlement price. This product will only have a price available on the settlement date of the contract. On the days prior to settlement date, the trade will value using a price that is resolved by adding the price of ticker H to the price of ticker PAN.
Date inputs can be either single dates or ranges. Ranges are specified the same way as with Molecule's REST API, where an input value of
2023-10-01..2023-10-31 represents the range of days between October 1st and 31st of 2023.