Expression Syntax¶

How to use the expression engine in Everysk¶

The expression engine is one of the powerful features within Everysk that enables fast development with little to no code required. It serves as an internal language capable of performing a wide array of customized tasks including mathematical equations, compliance checks, blending benchmarks, and data exploration. This guide will walk you through the syntax and various use cases of the expression engine within Everysk.

Robots That Use the Expression Engine¶

The expression engine's versatility is showcased through a variety of use cases, empowering you to perform complex calculations and logical operations within Everysk. Here are some prominent digital robots that utilize the expression language, each shown with a runnable solve() call:

Datastore Explorer Robot¶

Filter and manipulate data from datastores using unique expressions in the Datastore Explorer.

Example: Return the symbol for each position in a portfolio.

The Datastore Explorer always references one or more datastores and uses the expression engine to define properties that it outputs in a report or workflow. A simple function, single_text(), is used to cast a value from the datastore as a text value with a unique value. This type of property is often used to label data returned from a datastore exploration. Examples include symbols, labels, or custom tags.

import numpy as np

expression_engine.solve('single_text(sec_attribute_symbol)', {
    'sec_attribute_symbol': np.array(['AAPL', 'AAPL', 'AAPL'])
})
# 'AAPL'

Compliance Rule Solver Robot¶

Evaluate compliance rules, such as checking if a calculated value meets a specific condition.

Example: Check if the sum of market value for two instrument types is greater than or equal to 70% of the portfolio's Net Liquid Value (NLV).

The Compliance Solver references a datastore that contains itemized rules, each with their own filters and mathematical expressions. Here, filter() selects the positions matching an instrument type, sum() aggregates their market value, and port_attribute() pulls the single NLV value that repeats across every row of the datastore.

import numpy as np

expression_engine.solve(
    'sum(filter(market_value, instrument_type in ["Bond", "Equity"])) / port_attribute(nlv) >= 0.70',
    {
        'market_value': np.array([300000.0, 200000.0, 50000.0]),
        'instrument_type': np.array(['Bond', 'Equity', 'Cash']),
        'nlv': np.array([600000.0, 600000.0, 600000.0]),
    }
)
# True

Expression Solver Robot¶

Perform arithmetic operations using up-stream variables from a workflow and user specified calculations.

Example: Calculate a daily two sigma shock value for an index from its annualized standard deviation.

Certain robots such as the Expression Solver allow users to define variables in the robot itself rather than referencing fields in a datastore. In this example, std is a variable retrieved from a previous robot and used directly in the formula.

expression_engine.solve('std * 2', {'std': 0.015})
# 0.03

Time Series Operator Robot¶

Compute statistics on time series data, such as averages, z-scores, total returns, volatilities, scaling and many other measures.

Example: Calculate the average monthly return of a portfolio for the last day of each month.

The Time Series Operator works off a series of date-value tuples, so in this example returns represents a history of returns stored alongside their corresponding dates. The date function is_last_day_of_month() is used as the filter condition to keep only month-end observations before averaging them.

import numpy as np

expression_engine.solve(
    'mean(filter(returns, is_last_day_of_month(dates)))',
    {
        'returns': np.array([0.01, 0.02, -0.005, 0.03]),
        'dates': np.array(['20230130', '20230131', '20230227', '20230228']),
    }
)
# 0.025

Custom Benchmark Generator Robot¶

Design and calculate custom benchmarks by crafting expressions that combine and weight different market indices or data sources.

Example: Create a blended benchmark by applying a 70/30 weighting to the ACWI and the AGG indices.

Here, returns history for two indices is fed in as inputs, and average() combines them into a single weighted benchmark return.

import numpy as np

expression_engine.solve(
    'average(returns, weights)',
    {
        'returns': np.array([0.05, 0.03]),  # ACWI, AGG
        'weights': np.array([0.7, 0.3]),
    }
)
# 0.044

Syntax and Functions¶

The expression engine's power comes from its ability to interpret expressions based on intuitive grammatical rules and a library of different functions. Expressions can encompass variables, operators, function calls, and literal values. See below for examples of the most common elements of the expression syntax:

Expression	Example
Absence of Value	`None`
Integer	`7`
Float	`7.7`
String	`"Everysk"`
Backtick String	`Everysk`
Boolean	`True` or `False`
Variable	`my_var` or `'my_other_var'`
Array	`[None, 7, 7.7, "Everysk", True, my_var]`
Function	`my_function(arg_1, arg_2, …, arg_n)`
Not	`not my_var`
Negation	`-my_var`
Multiplication	`my_var * my_other_var`
Division	`my_var / my_other_var`
Floor Division	`my_var // my_other_var`
Modulo	`my_var % my_other_var`
Addition	`my_var + my_other_var`
Subtraction	`my_var - my_other_var`
Within	`"Cash" in ["Equity", "Future", "Cash"]`
Not within	`my_var not in my_other_var`
Equal	`my_var == "Everysk"`
Not Equal	`my_var != None`
Less Than	`my_var < my_other_var`
Greater Than	`my_var > my_other_var`
Less or Equal	`my_var <= my_other_var`
Greater or Equal	`my_var >= my_other_var`
Logical Or	`my_var or my_other_var`
Logical And	`my_var and my_other_var`
Conditional	`value1 if expr_1 else value2 if expr_2 else default`

See the Function Reference pages in the sidebar for the full function library, organized by category:

String — casting, searching, manipulation, case
Math — aggregation, statistics, rounding, risk metrics
Date — component extraction, period boundaries, format conversion, date arithmetic
List — slicing, filtering, mapping, transformation
Logic — existence, emptiness, membership checks
Miscellaneous — value retrieval, formatting, conditional logic, CNPJ/ISIN validation

Conclusion¶

The expression engine in Everysk offers an exceptional toolset for performing calculations, logic checks, and data manipulations for professional investors. Its flexible library and intuitive syntax enable you to craft complex expressions to customize your workflows.