Recoder API Reference

In the MX8 platform, recoding scripts transform respondent data after survey responses are collected.

Recoding scripts should always start with the code block:

from survey import Recoder

r = Recoder(**globals())

Use reporting IDs to read existing answers with get_value, get_values, or get_dict. Store derived variables with store_value or store_values; these appear as recode-sourced variables in reporting output.

`Recoder`

Recoder for transforming respondent data.

Use Recoder in a recoding script to read source survey answers, update recodes, mark poor-quality respondents, and store calculated variables for reporting.

`respondent`

@property
respondent: Respondent

Return normalized context for the current respondent.

Use this read-only property when recode logic needs to branch based on respondent metadata that was supplied at launch time.

Available fields

The respondent context exposes:

source: respondent source supplied at launch time.
country: canonical MX8 country code, or None when unavailable.
languages: tuple of canonical MX8 language codes in preference order.
browser: browser family parsed from the user agent, or None.
device: device family parsed from the user agent, or None.
os: operating system family parsed from the user agent, or None.
device_type: one of "mobile", "tablet", "pc", "bot", "other", or None.

Matching helpers

Use is_country(...), is_any_country(...), has_language(...), and has_any_language(...) to match country or language values by code, name, or synonym. Use get_provider_metadata(...) to read provider metadata values as strings.

Example

from survey import Recoder
r = Recoder(**globals())

if r.respondent.is_country("United States"):
    r.store_value("Country group", "US")

if r.respondent.device_type == "mobile":
    r.store_value("Device group", "Mobile")

`respondent_id`

@property
respondent_id: str

Return the current respondent id.

`tag`

tag(**kwargs: Any) -> dict[str, Any]

Create tags for stored recode values.

Tags are stored with calculated variables and can be used to describe the source, category, or dimensional breakdown of the derived value. Pass the returned dictionary to store_value or store_values with the tags argument. Returns: A tag dictionary to pass to store_value or store_values with the tags argument.

Parameters

Name	Type	Description
`**kwargs`	`Any`	Key-value pairs to attach as tags.

`recode`

recode(reporting_id: str, recodes: dict[str, str]) -> None

Recode the response to a question.

Recoding changes how source answer values are labeled in reporting. It does not create a new calculated variable.

Parameters

Name	Type	Description
`reporting_id`	`str`	the reporting id of the question to recode.
`recodes`	`dict[str, str]`	the recodes to apply.

`mark_poor_quality`

mark_poor_quality(respondent_ids: list[str] | str) -> None

Mark one or more respondents as poor quality.

Recoding executes one audience at a time. IDs that are not part of the current recoding pass are ignored.

Parameters

Name	Type	Description
`respondent_ids`	`list[str] \| str`	the respondent id or ids to mark.

`get_values`

get_values(reporting_id: str) -> list[ResponseType]

Get all values for a specific question.

Use this for multiselect, repeated, list, or topic-based questions that can produce more than one response for a respondent.

Values are returned in the order they were asked.

Parameters

Name	Type	Description
`reporting_id`	`str`	the reporting id of the question.

`get_dict`

get_dict(reporting_id: str) -> DictResponse

Get a dict-shaped response for list/grid style questions.

Always returns a DictResponse; wraps multiple structured responses in a top-level DictResponse keyed by index when necessary. The returned value is keyed by the question's reportable topics.

Parameters

Name	Type	Description
`reporting_id`	`str`	the reporting id of the question.

`get_value`

get_value(reporting_id: str) -> ResponseType | None

Get the single value for a specific question.

Use this for questions that produce at most one response per respondent. If the question has multiple responses, use get_values instead.

Returns None when no response is present.

Parameters

Name	Type	Description
`reporting_id`	`str`	the reporting id of the question.

`store_value`

store_value(
    name: str,
    value: str | int | bool,
    tags: dict[str, Any] | None = None,
    **kwargs: Any,
) -> None

Store one calculated value for the current respondent.

The stored value is added as a recode-generated reportable variable and can be used in reporting like a normal single-select or numeric value.

Parameters

Name	Type	Description
`name`	`str`	the label to give the value.
`value`	`str \| int \| bool`	the value to store.
`tags`	`dict[str, Any] \| None`	Tags to store with the calculated value, from r.tag(...).
`**kwargs`	`Any`	Legacy tag keywords to store with the calculated value.

`store_values`

store_values(
    name: str,
    values: list[str | int | bool],
    tags: dict[str, Any] | None = None,
    **kwargs: Any,
) -> None

Store multiple calculated values for the current respondent.

The stored values are added as a recode-generated reportable multiselect variable.

Parameters

Name	Type	Description
`name`	`str`	the label to give the values.
`values`	`list[str \| int \| bool]`	the values to store.
`tags`	`dict[str, Any] \| None`	Tags to store with the calculated values, from r.tag(...).
`**kwargs`	`Any`	Legacy tag keywords to store with the calculated values.