funpack.parsing.value_expression

Logic for parsing categorical recoding/replacement values.

The --recoding command-line option, also specified via the RawLevels / NewLevels columns in the variable table, accepts both literal values, and value expressions.

As an example of literal values, this option would cause FUNPACK to replace values 555 and 444 with 0.5``and ``4 respectively, in the data field 123:

--recoding 123 "555,444" "0.5,4"

As an example of value expressions, this option would cause FUNPACK to replace the value “-818” with one plus the data maximum in data-field 123:

--recoding 123 "-818" "1 + max()"

This module contains the logic used to parse and evaluate these value expressions.

Value expressions can use the following functions and binary operators. Both functions and operators accept numbers and other expressions as arguments:

• min(): If called without arguments (i.e. min()), returns the minimum

  of the input data. Otherwise returns the minimum of the arguments, e.g. min(1,2,3,4)

• max(): If called without arguments (i.e. max()), returns the maximum

  of the input data. Otherwise returns the maximum of the arguments, e.g. max(1,2,3,4)

• +: Adds two operands, e.g. 1 + 2

• -: Subtracts two operands, e.g. 1 - 2

• *: Multiplies two operands, e.g. 1 * 2

• /: Divides two operands, e.g. 1 / 2

The parseValueExpressions() function is the primary function provided by this module. It accepts a string containing a comma-separated sequence of literal values and value expressions, and will return a list containing those literal values, and ValueExpression objects for each expression.

A ValueExpression object can be invoked on some data to evaluate the expression on that data.

funpack.parsing.value_expression.Literal

Type representing a literal primitive value.

alias of float | int | str

class funpack.parsing.value_expression.ValueExpression(expr: str)

Bases: object

Class which parses and evaluates a single value expression.

ValueExpression objects are created by the parseValueExpression() function. A ValueExpression object can be called with some data to evaluate the expression against that data.

add(v1, v2)

Evaluates v1 + v2.

div(v1, v2)

Evaluates v1 / v2.

property expression: str

Return the expression string that this ValueExpression will evaluate.

max(*vals)

Evaluates max([values]). Return the maximum of vals. If no values are specified, returns the maximum of the data set.

min(*vals)

Evaluates min([values]). Return the minimum of vals. If no values are specified, returns the minimum of the data set.

mul(v1, v2)

Evaluates v1 * v2.

sub(v1, v2)

Evaluates v1 - v2.

funpack.parsing.value_expression.makeValueExpressionParser(valexpr: ValueExpression | None = None) → Any

Create a pyparsing parser which can be used to evaluate a value expression.

If valexpr is not None, it must be a ValueExpression instance. In this case, the parser will produce a callable object which can be evaluated by valexpr. The callable is for the exclusive use of valexpr, as the functions/expressions contained within will be bound to methods of valexpr.

If valexpr is None, the returned parser can still be used, but will just re-construct the expression as a string. This sounds pointless, but it is used by the parseValueExpressions() function, to parse comma-separated sequences of expressions.

funpack.parsing.value_expression.parseValueExpressions(exprs: str, ctype: Enum) → List[ValueExpression | float | int | str]

Parse a comma-separated sequence of value expressions/literal values.

Returns a list containing literal values and ValueExpression objects - these can be used to evaluate each expression against some data at a later point in time.

Parameters:

• exprs – String containing a comma-separated sequence of value expressions/literal values

• ctype – UKBiobank data type of the data-field against which the expressions will be applied. Used to infer a suitable data type into which any literal values will be coerced.