Skip to main content
Chat with us

Search

What can we help you with?

How to Upload Custom Variables

Custom Variable Uploads let you append additional data to your survey, customize your data set, and create new filter options.

In This Article

Before you begin

  • You must be an admin or owner of the survey to upload custom variables.
  • Custom Variable Uploads are available on select plans. If you don't see Upload CSV/XLSX in the Filters menu, or it appears disabled with an upgrade link, your plan may not include this feature.
  • Custom Variable Uploads only append data to respondents already in your stats report. You can't add new respondents to an existing stats report with this feature. If you need to merge surveys, reach out to support for assistance.

Creating a custom variable

  1. With the Original - as fielded report open on the Results page, click the Export options menu and select Excel. Under Data type, choose Numerically coded with labels, then download the file.
  2. In the first column, make sure the first column is titled exactly Id or UID. The coded export already uses Id; don't rename it to anything else.
  3. After the ID column, create a custom variable column with the prefix aytm: (e.g., aytm:custom_state, aytm:group).
  4. Populate the columns with the appropriate variable data. Spaces and special characters are acceptable within the data cells.
  5. Save your edited file as a CSV or XLSX file. The older .xls format isn't supported.
  6. On the Results page, click the Filters menu, scroll to the bottom, and click Upload CSV/XLSX.

Variable naming rules

  • Each variable needs a unique label.
  • Names are limited to 25 characters and can't contain spaces. A column name with a space in it is ignored.
  • Use letters, numbers, and the underscore symbol (e.g., aytm:abcd_123). Periods and hyphens are accepted, but are converted to underscores.
  • If a name starts with a number or an underscore, or matches a name the platform already uses (such as MSA or a question code like Q1), the platform automatically adds custom_ to the beginning of the variable name.

You can upload multiple files, and new variables are created for each unique label. If you upload data for a label that already exists on the stats page, the new data overwrites the existing data.

raw_data_sheet.png

⚠️ Note: You can only append data to the existing data set. You can't add new respondents to an existing stats report with this feature.

Creating Custom Variable Upload for Checkboxes

If you want to create a filter that contains multiple variables, like a Checkbox question type, upload each answer choice in its own column.

For example, a Checkbox question has three answer choices: A1, A2, and A3. Each answer choice is coded 0 if the respondent does not have that characteristic, or 1 if the respondent does. Once the custom variable is uploaded, you can filter by answer choice.

  1. With the Original - as fielded report open on the Results page, click the Export options menu and select Excel. Under Data type, choose Numerically coded with labels, then download the file.
  2. After the ID column, create a custom variable column for each answer choice with the prefix aytm:. Add an underscore and a number (_1, _2, _3, etc.) to the end of each column name to group the columns under one filter (e.g., aytm:example_1, aytm:example_2, aytm:example_3).
  3. Fill every cell in these columns with a 0 or a 1. Enter 0 if the respondent doesn't have that characteristic and 1 if they do.
  4. Save your edited file as a CSV or XLSX file.
  5. On the Results page, click the Filters menu, scroll to the bottom, and click Upload CSV/XLSX.

⚠️ Note: Every column in the group must end in an underscore followed by a number, and must contain only 0s and 1s. A column named aytm:example3 (no underscore) isn't grouped with the others.

raw_data_map_sheet.png 

Filtering Custom Variable Upload for Checkboxes

  1. Click the Filters menu.
  2. Scroll to the Uploaded Variables group.
  3. Click the drop-down menu next to your uploaded variable and select the answers you want to filter by.
  4. Click Apply filters at the top of the Filters menu.

apply variables.gif 

Creating Virtual Questions with Custom Variable Uploads for Checkboxes

  1. Select Data Lab from the Results page.
  2. Drag and drop a virtual question into the study.
  3. Click the Optional Presets drop-down menu.
  4. Scroll to Variables, select the custom variable upload for checkboxes (in our case, test), and populate its answer choices (1, 2, 3, etc.).
  5. Select the answer choices you would like to filter by.
  6. Click Generate Visualization.

vq weighted optional presets.gif 

Summary of Limits

Limits are enforced on uploaded files to make sure they process correctly.

Limit Default
Variables per survey 100
Variable name length 25 characters
Characters per variable value 5,000

⚠️ Note: These are default limits. They can be adjusted for individual surveys, so the limits on your survey may differ.

Troubleshooting

Having trouble with your file? Check for these common issues. The system displays a warning message if a file can't be processed or if it had to adjust the file to upload it.

  1. Is your file saved as a CSV or XLSX? The file picker may show .xls files, but they can't be uploaded. Re-save the file as .xlsx or .csv.
  2. Is your first column (respondent ID) titled Id or UID? If the column has any other title, the file won't be processed.
  3. Variable names are too long: The platform automatically trims names to 25 characters.
  4. Variable names contain spaces: Columns with spaces in the name are ignored. Use underscores instead.
  5. Variable names are repeated: If multiple columns share the same variable name (for example, columns Q, R, and S are all titled "custom_var16"), the platform imports data from the first column and ignores the rest. This also applies when names become identical after being trimmed to 25 characters.
  6. Too many variables: The default maximum is 100 unique variables per survey.
  7. Variable has too many characters: Variables can contain up to 5,000 characters by default. Anything after that is cut off.
  8. Variable name conflicts with our naming convention: If you name a column MSA, which the system already uses, the platform automatically adds custom_ to the variable name when it uploads.
  9. The file type isn't compatible: The system accepts CSV or XLSX, but the file can't contain a double header. Both the raw Excel and CSV exports contain double headers. Use the Numerically coded with labels Excel export, or create a new sheet in Excel and save it as a CSV.
  10. You don't see the upload option: You must be an admin or owner of the survey, and your plan must include Custom Variable Uploads.