Skip to content

parameters

Analysis parameter models: what a configuration declares and how a value is validated.

AnalysisParameter pydantic-model

Bases: BaseModel

Represents an analysis-specific parameter.

Analysis parameters are used to configure the analysis and can be of type 'str', 'int', or 'float'. Can be set by the user unless there is only a single choice in which case it is considered a hard coded parameters.

Fields:

Validators:

api_name property

Return the name a request uses for this parameter: its key.

Kept as a computed field so the API schema and every client keep the name they have always read; it is the key by another name.

choices = None pydantic-field

The list of choices for the parameter. If set, the parameter is considered a choice parameter and the user must select one of the choices. If choises is a length 1 list the parameter is considered a hard coded parameter and the user cannot change the value. Must be set if range is not set.

default pydantic-field

The default value of the parameter. Must be one of the choices if choices is set or must be in range if range is set. REQUIRED: All parameters must have a default for consistent hash computation.

description pydantic-field

A brief description of the parameter.

key pydantic-field

The machine key of the parameter, unique within the analysis: what a request names it by, the key it has in the analysis manifest's parameters, and the name the parameter hash is computed over. Lowercase letters, digits, hyphens and underscores.

name pydantic-field

The name of the parameter. Must be unique among all parameters of the analysis. The name must be a contain only lowercase alphabetical characters and underscores ('_') and be between 2 and 32 characters long.

range = None pydantic-field

The range of acceptable values for the parameter. Must be set if choices is not set.

type pydantic-field

The type of the parameter. Can be 'str', 'int', 'float', or 'bool'.

validated_regime = None pydantic-field

The value(s) of this parameter at which the analysis has been validated — its validated regime. Every other accepted value stays fully supported and runnable, but is a research setting: the analysis was not characterised there, so its outputs are exploratory and should be interpreted as such. This is a different statement from 'default', which only says which value is pre-selected for the user; an analysis may pre-select a value it was never validated at, or be validated at several values of which only one is pre-selected. List every validated value when more than one qualifies. Leave unset (null) when the validated regime is not declared, in which case no value is claimed to be a research setting and none is claimed to be validated. Each entry must be an accepted value of this parameter: one of 'choices', or inside 'range'.

get_validated_value_or_default(value)

Return the value if it is not None, otherwise return the default value.

Every parameter declares a default, so a value is always returned.

is_research_mode(value)

Return whether value falls outside this parameter's validated regime.

Always False when no validated regime is declared: an undeclared regime makes no claim about any value, so nothing is presented as research mode.

Pass a normalized value — the output of :meth:validate_value or :meth:get_validated_value_or_default. A raw, uncoerced submission such as the string "3840" does not match the integer 3840 and would be reported as research.

validate_choices(choices) pydantic-validator

Validate that all choices are unique and of the same type.

validate_default() pydantic-validator

Validate that the default value is one of the choices if choices is set.

validate_range(range) pydantic-validator

Validate that the range values are of the same type and either int or float.

validate_range_choices(data) pydantic-validator

Validate the range and choices fields.

Validate that only one of 'range' and 'choices' can be set and that at least one of them is set.

validate_validated_regime() pydantic-validator

Validate that every declared validated-regime value is an accepted value.

A validated regime that names a value the parameter does not accept could never be selected, so it would silently mark every selectable value as research mode.

validate_value(value)

Validate the value of the parameter and return the value if it is valid.

Parameters pydantic-model

Bases: BaseModel

The analysis-specific parameters a configuration declares.

Every parameter reaches the container through the analysis manifest, keyed by its key and typed as declared here; the platform passes nothing else.

Fields:

Validators:

custom pydantic-field

Parameters the analysis accepts. Empty when it takes none.

research_parameters(submitted)

Return the API names of parameters whose effective value is research mode.

The effective value of each custom parameter is the submitted value (matched on :attr:AnalysisParameter.api_name) or, when absent, the parameter's default — a default can itself lie outside the validated regime. Parameters of configurations that declare no validated regime never appear.

Raises:

Type Description
ValueError

A submitted value does not resolve against this configuration (wrong type, not a choice, out of range). The caller decides whether that means "invalid submission" or, when classifying a historical analysis against a configuration that has since changed, "unknown".

validate_unique_keys(custom) pydantic-validator

Keys and names are unique within one configuration.