Single-select, exported one-hot
Collapse the option columns into one categorical field. This makes “exactly one choice” part of the data itself.
| brand_a | brand_b | brand_c |
|---|---|---|
| 1 | 0 | 0 |
| brand |
|---|
| A |
Data preparation
How to prepare survey data for Simulacra
Format the data as a flat file: rows are observations, columns are variables. Standardize the blanks so that a blank always means not asked or not answered. Choose complete or preserve when you create the dataset, and review the fitted schema before generation.
The upload shape
One respondent per row.
Upload one rectangular, respondent-level table (CSV, Excel, SPSS .sav, Parquet, Feather, or Arrow) with at least 24 unique rows before and after preparation. Remove contact details, known IDs, administrative fields, and open-ended text responses.
| segment | satisfaction | purchased | monthly_spend |
|---|---|---|---|
| Core | 8 | TRUE | 84.50 |
| Growth | 6 | FALSE | 42.00 |
| Core | blank | TRUE | 71.25 |
| question | answer | timestamp | |
|---|---|---|---|
| a@company.com | Q1 | 8 | 10:31:04 |
| a@company.com | Q2 | TRUE | 10:31:12 |
| b@company.com | Q1 | 6 | 10:34:18 |
Remove known identifiers before upload. A randomized
numeric ID can look exactly like a legitimate measure, such as spend,
weight, or a precise age, so automated cleaning may keep it. If you
know a column is an ID, drop it.
Decide what missing means
A blank, FALSE, and zero are different answers.
Use the questionnaire and codebook to decide what each blank, zero, and unchecked box means. Do not fill missing cells simply to make the file look complete.
What happened in the survey
Upload as
Not asked, or asked but left unanswered
Blank / true missing
Unchecked means “not selected”
FALSE
Not asked truly means zero amount or frequency
0
| purchased_30d | spend | what happened |
|---|---|---|
| TRUE | 84.50 | Answered — upload the amount. |
| TRUE | blank | Asked, no answer — leave blank. |
| FALSE | blank | Not asked — leave blank. |
| FALSE | 0 | Not asked, and the questionnaire counts no purchase as zero spend — upload 0. |
Routed skips and unanswered questions both remain blank. Keep the
routing field (for example, purchased_30d)
so the relationship stays in the upload; do not add a separate reason
code to the blank cell. Keep offered responses such as “Prefer not to
answer” as labels.
Choose a missing-data mode
Choose complete or preserve at dataset creation.
complete (the default) returns categorical missingness as a modeled category and predicts missing continuous values. preserve returns missing values according to patterns learned from the uploaded data. Changing modes requires creating a new dataset.
Source state
complete delivery
preserve delivery
Categorical blank
Modeled N/A category
Blank
Continuous blank
Predicted value
Blank
This comparison shows how missing values are represented. Simulacra generates new rows; it does not fill the uploaded rows one by one.
Preserve is learned, not enforced. Preserve learns
missingness patterns; it does not turn questionnaire routing into a
hard rule. Check generated routed fields against the questionnaire
before release.
Conditioning changes the conditioned field. When you
condition a field on an observed value, missingness is excluded on
that field. Compatible missingness on other fields is generated under
the requested condition.
Survey structures
Represent each question in the form you want delivered.
Survey platforms often export one question as several technical columns. Collapse single-select exports, keep true multi-select options separate, and use the same coding or labels you want back in delivery.
True multi-select
Keep one Boolean field per option when each option is an independent yes/no answer. A blank remains missing when the respondent was not shown the battery.
- Unchecked and shown: FALSE
- Checked: TRUE
- Not shown: blank / true missing
Sentinel codes
With CSV or Excel, convert declared missing codes such as -1 or 99 to blanks before upload. SPSS .sav files declare user-missing codes in their metadata, and those declarations are honored automatically.
- Convert only codes the codebook declares as missing: on a 0–100 scale, 99 can be a real answer.
- Keep the codebook used for the decision.
- Keep substantive refusal labels, such as “Prefer not to answer,” as labels.
Sparse routed scales
For numeric codes that represent categories or fixed-integer answers, prefer a typed file such as .sav. With CSV, use answer labels in a text column rather than relying on numeric inference.
- CSV does not preserve ordering metadata.
- Verify the fitted type after upload.
- Verify generated values remain among the answers the survey allowed.
The fitted schema
Review the fitted schema before generation.
The raw upload stays your source record; the fitted schema is the contract for what generation delivers. The Studio shows it after upload, and the API returns it from GET /v1/datasets/{dataset_id}/schema.
Raw upload
Keep the received file and codebook. Reconcile row counts, meanings, and deliberate column removals.
Fitted schema
Review the final names, types, levels, and column order, plus the dropped columns and warnings in the cleaning summary.
Delivery
Generated columns must match the fitted schema. Use these names when building conditions and downstream checks.
What may change
- Uploaded names may be normalized.
- Constants and clearly non-modeling fields may be removed, and every drop is listed with its reason.
- Date and time fields are not modeled and are dropped with a visible reason.
- Yes/no questions that contain blanks may appear categorically.
- Some typed ordinal fields may appear as unordered categories.
What to verify
- Expected fields are present in the fitted schema.
- Known IDs and contact fields are absent.
- Categorical values stay inside the answers the survey actually offered.
- Declared integer scales remain whole numbers in delivery.
Before dataset creation
Eight checks before you upload.
Keep this list with the upload and the returned schema.
One row represents one respondent.
Known IDs, contact details, administrative fields, and open-ended text are removed.
Declared missing sentinels are converted without changing substantive codes.
One-hot single-select questions are collapsed into one categorical field.
Every routed blank, FALSE, and zero has its intended questionnaire meaning.
complete or preserve is chosen for this dataset.
The returned names, types, levels, drops, warnings, and column order are reviewed.
Categorical values are valid survey answers, and declared integer scales contain only whole numbers.
Print this page for a paper checklist; only the checklist prints.
Next steps
Put your cleaned data to use.
Use the Studio for an interactive upload. For an API integration, follow the dataset-creation and schema endpoints in the API reference.