choicedesign.expressions

Symbolic expression system for ChoiceDesign utility functions.

All expression nodes support arithmetic operators (+, -, *, /, **, unary -) and comparison operators (==, !=, <, <=, >, >=). Comparison operators return indicator expressions (1.0 / 0.0) rather than Python booleans, enabling dummy-coded attributes:

beta_A_2 * (alt1_A == 2) + beta_A_3 * (alt1_A == 3)

Every node implements symbolic differentiation via Expression.differentiate(), used by MNLModel to build the Fisher information matrix without numerical approximation.

User-facing classes

Attribute: A design column (attribute with discrete levels).
Parameter: A model parameter with a prior value.
ASC: An alternative-specific constant (excluded from D-error).
exp(), log(): Symbolic exponential and logarithm.
get_unique_params(): Extract unique parameters from a utility-function dict.

Functions

`exp`(expr)	Natural exponential of an expression.
`get_unique_params`(V)	Collect all unique Parameter objects from a utility-function dict.
`log`(expr)	Natural logarithm of an expression.

Classes

`ASC`(name, prior)	Alternative-specific constant.
`Add`(left, right)	Expression node for addition (`left + right`).
`Attribute`(name, levels)	A design attribute — a column of the design matrix.
`Constant`(value)	A fixed numeric constant.
`Div`(left, right)	Expression node for division (`left / right`).
`Equal`(left, right)	Indicator expression: 1.0 where `left == right`, 0.0 elsewhere.
`Exp`(expr)	Element-wise natural exponential of an expression.
`Expression`()	Base class for all ChoiceDesign expressions.
`GreaterEqual`(left, right)	Indicator expression: 1.0 where `left >= right`, 0.0 elsewhere.
`GreaterThan`(left, right)	Indicator expression: 1.0 where `left > right`, 0.0 elsewhere.
`LessEqual`(left, right)	Indicator expression: 1.0 where `left <= right`, 0.0 elsewhere.
`LessThan`(left, right)	Indicator expression: 1.0 where `left < right`, 0.0 elsewhere.
`Log`(expr)	Element-wise natural logarithm of an expression.
`MonteCarlo`(expr)	Averages an expression over Monte Carlo draws.
`Mul`(left, right)	Expression node for multiplication (`left * right`).
`Neg`(expr)	Expression node for unary negation (`-expr`).
`NotEqual`(left, right)	Indicator expression: 1.0 where `left != right`, 0.0 elsewhere.
`Parameter`(name, prior[, prior_std])	A model parameter with a prior value.
`Pow`(base, exponent)	Expression node for exponentiation (`base ** exponent`).
`Sub`(left, right)	Expression node for subtraction (`left - right`).

class choicedesign.expressions.ASC(name: str, prior: float)

Alternative-specific constant.

Identical to Parameter but semantically tagged so that the optimiser excludes it from the D-error computation (ASCs are not part of the design being optimised). The prior should reflect the expected log-odds of choosing that alternative.

Parameters:

name (str) – Constant name.
prior (float) – Prior value (typically derived from market-share expectations).

Examples

>>> asc_1 = ASC('asc_1', 0.5)

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params() → list

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.Add(left: Expression, right: Expression)

Expression node for addition (left + right).

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.Attribute(name: str, levels: int | list)

A design attribute — a column of the design matrix.

Parameters:

name (str) – Column name as it will appear in the design DataFrame.
levels (list or int) – Discrete levels this attribute can take. Pass a list of values (e.g. [100, 200, 300]) or an integer n to get levels [0, 1, ..., n-1].

Examples

>>> cost = Attribute('cost', [100, 200, 300])
>>> dummy_attr = Attribute('mode', 3)  # levels = [0, 1, 2]

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params() → list

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.Constant(value: float)

A fixed numeric constant.

Parameters:: value (float) – The numeric value wrapped in the expression tree.

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params() → list

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.Div(left: Expression, right: Expression)

Expression node for division (left / right).

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.Equal(left: Expression, right: Expression)

Indicator expression: 1.0 where left == right, 0.0 elsewhere.

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.Exp(expr: Expression)

Element-wise natural exponential of an expression.

Parameters:: expr (Expression) – The argument expression.

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.Expression

Base class for all ChoiceDesign expressions.

Subclasses implement evaluate(data, draws) and optionally differentiate(param) for symbolic differentiation. Arithmetic operators are overloaded so that utility functions can be written naturally:

V1 = beta_A * alt1_A + beta_B * alt1_B

differentiate(param: Parameter) → Expression

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params() → list

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.GreaterEqual(left: Expression, right: Expression)

Indicator expression: 1.0 where left >= right, 0.0 elsewhere.

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.GreaterThan(left: Expression, right: Expression)

Indicator expression: 1.0 where left > right, 0.0 elsewhere.

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.LessEqual(left: Expression, right: Expression)

Indicator expression: 1.0 where left <= right, 0.0 elsewhere.

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.LessThan(left: Expression, right: Expression)

Indicator expression: 1.0 where left < right, 0.0 elsewhere.

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.Log(expr: Expression)

Element-wise natural logarithm of an expression.

Parameters:: expr (Expression) – The argument expression. Must be positive when evaluated.

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.MonteCarlo(expr: Expression)

Averages an expression over Monte Carlo draws.

When the inner expression returns a 2-D array of shape (draws, ncs), this wrapper collapses the draw dimension by taking the row-wise mean. For deterministic expressions it is a no-op.

Parameters:: expr (Expression) – The expression to average over draws.

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.Mul(left: Expression, right: Expression)

Expression node for multiplication (left * right).

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.Neg(expr: Expression)

Expression node for unary negation (-expr).

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.NotEqual(left: Expression, right: Expression)

Indicator expression: 1.0 where left != right, 0.0 elsewhere.

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.Parameter(name: str, prior: float, prior_std: float = None)

A model parameter with a prior value.

Parameters:

name (str) – Parameter name.
prior (float) – Prior (point) value used in D-efficient design. For Bayesian (Db-efficient) designs this is the mean of the prior distribution.
prior_std (float, optional) – Standard deviation of the normal prior distribution. When set, the parameter is treated as uncertain and participates in Db-error averaging. None (default) means a fixed point prior.

Examples

>>> beta_cost = Parameter('beta_cost', -0.01)
>>> beta_time = Parameter('beta_time', -0.05, prior_std=0.02)

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params() → list

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.Pow(base: Expression, exponent: Expression)

Expression node for exponentiation (base ** exponent).

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

class choicedesign.expressions.Sub(left: Expression, right: Expression)

Expression node for subtraction (left - right).

differentiate(param)

Return the symbolic derivative with respect to param.

Parameters:: param (Parameter) – The parameter to differentiate with respect to.
Return type:: Expression

evaluate(data=None, draws=None)

Evaluate the expression and return a NumPy array or scalar.

Parameters:

data (pandas.DataFrame, optional) – Design matrix. Required for Attribute expressions.
draws (int, optional) – Number of Monte Carlo draws. Required for RandomParameter.

Return type:

np.ndarray or float

get_params()

Return a list of all Parameter objects in the expression tree.

The list may contain duplicates; use get_unique_params for a deduplicated version.

choicedesign.expressions.exp(expr) → Exp

Natural exponential of an expression.

Parameters:: expr (Expression or float) – The argument.
Return type:: Exp

choicedesign.expressions.get_unique_params(V: dict) → List[Parameter]

Collect all unique Parameter objects from a utility-function dict.

Parameters:: V (dict) – Dictionary mapping alternative indices to Expression objects, e.g. {1: V1, 2: V2}.
Returns:: Ordered list of unique Parameter objects (by object identity), preserving first-seen order.
Return type:: list[Parameter]

choicedesign.expressions.log(expr) → Log

Natural logarithm of an expression.

Parameters:: expr (Expression or float) – The argument. Must be positive when evaluated.
Return type:: Log