DataTile Codebook - succinct data map declaration

What is a Codebook?

DataTile allows you to upload a codebook as a structured Excel file (.dtcb.xlsx) that defines the complete variable structure and specifies how your data should be organized and interpreted in DataTile.

💡

Tip: Most one-off projects are faster to tidy in the UI; reserve codebooks for repeatable processing and distribution.

It can:

Standardise variable names and labels
Define multi-response sets and question arrays
Organise variables into folders
Control visibility of variables
Translate data to a clean, consistent data map.

Think of it as a reproducible data map: you set the rules once, reuse them across projects/waves/datasets, and get consistent outputs every time.

→ You can view and download the sample codebook v2 used in this manual.

What’s New in Version 2

💡

The Codebook v2 layout is the result of our team's extensive experience in working with international trackers, benchmark databases, and global syndicated studies.

This format is succinct, yet human-friendly and versatile.

Saves time by a magnitude in the creation and maintenance of the data map
Facilitates consistency of naming and brand lists
Reduces human errors by reusing the definitions
Reduces the size of the data map through patterns and removing repetitions

Key highlights

New capabilities – codebook v2 is a much more succinct and efficient way to describe a data map. It supports naming patterns, variable measures, new multi-response declarations, and other syntactic sugar.
Separation of variables and categories – The declarations of variables and value labels are separated in different worksheets, namely VARIABLES and VALUES, making them easier to navigate, observe, and maintain.
Incremental declaration – when no codebook is provided, DataTile derives a codebook from the data file by analysing its metadata, types of the values, etc. User-provided codebook works as a patch, overriding the default metadata extracted from the file. It’s not necessary to supply a codebook describing the entire database. Short partial codebooks can be used to update individual variables, categories, and labels.
Intuitive terms and column names – the first version of the codebook was purely an internal tool that was exposed for use by our clients. The new syntax uses widely accepted terminology in survey data processing, reducing learning barriers and making the overall framework more intuitive.
Old names from v1 are supported as aliases for new terms, where relevant, to ensure backward compatibility.

Codebook v2 is the primary version from August 2025. The previous version is deprecated, meaning new structures, syntax, and functionality will not be implemented for v1 but will remain available until April 2026.

Why use a codebook (and when)?

Creating a codebook is optional. For one-off uploads—such as ad hoc studies or the initial setup of a tracker—you can prepare and tidy your database more quickly using the DataTile interface, without the need to build a codebook manually.

💡

To save time, avoid building a codebook manually from scratch. Instead, upload your data file to create a new database in DataTile, review and reorganise the schema using the UI, and then export the resulting codebook for any further manual refinements.

Codebooks offer a clear advantage when you need to repeat data processing steps or distribute data consistently across multiple projects or teams. Here are the most common use cases for codebooks:

Syndicated databases – Managing and distributing syndicated data becomes far more efficient with a structured codebook that includes reusable dictionaries and naming patterns. What could otherwise be hundreds of thousands of mapping rows can be condensed into just a few hundred lines.
Merging multiple datasets – Combining different datasets into a single benchmark database is often complex and costly, delaying new product launches. For instance, a media brand can consolidate years of ad test results into one benchmark database to improve targeting and campaign effectiveness. The DataTile codebook simplifies this process, making it faster, more consistent, and easier to maintain.
Standardised delivery – Codebooks facilitate the consistent delivery of recurring study types or methodologies, enabling automated report generation and streamlined data distribution across markets while reducing operational costs.
Integration with external platforms – Online panels, fieldwork providers, and survey platforms can use DataTile as an OEM data delivery solution. By uploading collected data along with the associated metadata, they can enable automated reporting and self-service analytics for their clients.
Validation and quality control – Large tracking programmes that collect data across multiple markets and suppliers benefit from early schema validation. With a DataTile codebook, requirements are clearly defined, and each incoming dataset is automatically checked against the expected structure - minimising errors, improving reliability, and speeding up delivery.

If you’re planning a new data product and facing challenges with data processing, harmonisation, or report automation, don’t hesitate to reach out to us - or schedule a consultation with our experts here.

How to Apply a Codebook

You can apply a codebook in several ways – either manually through the DataTile interface or programmatically via the API:

When creating a new database in DataTile.
When appending new data to an existing database in DataTile.
When reloading data in an existing database in DataTile.
When importing a codebook, import it into an existing database directly to update or refine metadata without uploading a data file.

Supply Codebook with Data File

Creation, append, and reload operations involve changes to the data within a database; therefore, the codebook can be supplied together with the data file.

To provide a codebook and a data file (e.g. *.sav, *.zsav) in one upload:

Rename the codebook file to include the secondary extension *.dtcb.xlsx. The ‘dtcb’ tag stands for ‘DataTile codebook’ and allows the platform to identify it automatically.
Zip both files – the data file and the renamed codebook – into a single archive.
Upload the zip bundle to DataTile. DataTile will recognise the codebook by its *.dtcb.xlsx extension and apply it during the loading process.

Codebook Import

To download a codebook from an existing database, go to Settings → META-EDITOR and select the Download codebook option from the menu.

Import-export codebook menu is under Database Settings section — Import/Export codebook menu

To update a database, import the revised codebook using the Upload codebook menu option.

Older versions of the codebook can also be uploaded through the same menu. DataTile automatically detects the codebook version based on its internal structure and applies it accordingly.

Codebook v2: Structure and Layout

VARIABLES Sheet

Variables are defined on the VARIABLES sheet of the codebook. This sheet contains two mandatory columns – TYPE and NAME.

A detailed description of all variable types that can be declared in a codebook, including their specific properties and configuration options, is provided in a separate article. Here, we focus on the general codebook structure and the key concepts needed to understand how it works.

Each row defines either a single variable, a multi-response declaration, or a pattern representing a group of related variables that capture responses to a matrix-style question.

For greater stability, DataTile treats sheet names, column headers, variable types, and variable names as case-insensitive. Character case is only significant for labels, where it is preserved exactly as entered.

TYPE mandatory – Specifies the type of the variable. It can take one of the following values:

Variables: CAT, DATE, NUM, TXT.
Multi-response sets: MC (categorical), MD (dichotomous).
Ignored variable: IGN signals DataTile to ignore the specified variable in the dataset.

Each variable in the VARIABLES sheet of the Codebook must have a declared TYPE that defines how DataTile interprets and processes it. Find a detailed explanation in the dedicated article.

NAME mandatory – Specifies the variable name as it appears in the SPSS file or as a column header in the Excel data file described by the codebook. Follow DataTile’s naming best practices to ensure consistency and compatibility across systems and scripts.

LABEL optional – Provides the variable’s label, usually the text of the survey question. On multilingual servers, you can include labels in up to three languages by adding separate columns identified with the two-letter ISO 639 language codes.
For example: label_en, label_ja, label_zh — for English, Japanese, and Chinese labels, respectively.

VALUES optional – If left blank, DataTile automatically searches for a value-label dictionary with the same name as the variable in the VALUES sheet.

You can override this by specifying a dictionary name in this column. This approach enables efficient reuse of shared dictionaries such as scoring scales, Likert scales, or brand lists across multiple variables.

Variable NAME defines a value dictionary, but the reference can be overridden by content of the VALUES cell — Variable `NAME` defines a value dictionary, but can be overridden by `VALUE`

EXP optional – Expression represents a Logical Condition on Numeric Values.
The interpretation of the expression depends on the variable type.

For dichotomous multi-response (MD) variables, it defines the “counted value”, which, unlike in SPSS, can be expressed as a logical condition rather than a single fixed value.

FOLDER – Specifies the folder where the variable is located. The folder name must reference a folder defined in the FOLDERS sheet.

MEASURE – Defines the variable's subtype.

For categorical variables: NOMINAL (default) or ORDINAL
For numeric variables: PLAIN (default), WT (weight), or PROB (probability)

If no measure is specified, DataTile automatically applies the appropriate default.

When you change a variable’s type during a codebook reload, remember to update the MEASURE column accordingly:

Categorical → Numeric: leave Measure blank.
Don’t set NOMINAL or ORDINAL for numerics; it causes the dataset loading error.
Numeric → Categorical: set Measure to NOMINAL or ORDINAL as needed (if empty, NOMINAL is applied by default).

HIDDEN optional – A Boolean or binary flag (true/false or 1/0) indicating that the variable should be hidden in the DataTile database and excluded from user-facing views or analyses.

MAP optional – Allows you to map variables from the source data file to differently named variables in DataTile. Translation maps are useful when merging datasets with inconsistent naming conventions, enabling integration into a single benchmark or tracking database without modifying the original files.

Example:
If NAME = GEN and MAP = SEX, the SEX variable from the source data file will be imported into DataTile under the name GEN.

VALUES Sheet

Value labels are grouped by NAME, which identifies the dictionary they belong to.

The row order within each dictionary defines the display order of categories in DataTile.

NAME mandatory – The identifier of the value-label dictionary. Avoid using spaces in dictionary names. For best compatibility across systems and locales, follow the stricter naming convention described here.

VALUE mandatory – Most commonly, it’s a single number (integer in most cases) representing the category code. It can also be used to address alphanumeric values in Excel or CSV files.

LABEL optional – The category label. If no label is provided, DataTile uses the category’s VALUE as its label. On multilingual servers, you can include labels in up to three languages by adding columns identified with two-letter ISO 639 language codes — for example, label_en, label_ja, label_zh for English, Japanese, and Chinese, respectively.

MIDPOINT optional – The numeric equivalent of a category, used in volume or mean calculations. For example, when calculating the average age from an age_cat variable, DataTile automatically uses the specified midpoints corresponding to each age band.

REF optional – Reference to the variable names that make up a multi-response set, linking the dictionary entries to the corresponding variables in the dataset. Read more about it in the dedicated article.

HIDDEN optional – A Boolean or binary flag (true/false or 1/0) indicating that the category should be hidden in the DataTile database and excluded from standard user views or analyses.

MAP optional – Allows you to translate or recode values from the source data file into different values or categories within DataTile on the fly during the loading process. Each entry in this column represents a logical condition on numeric values. When a source value satisfies the condition specified in MAP, it is mapped to the corresponding VALUE in the dictionary.

FOLDERS sheet

The FOLDERS sheet defines the folder hierarchy that appears in DataTile’s left-hand navigation. Variables reference these folders via the FOLDER column on the VARIABLES sheet. The sheet lets you standardise names, order, visibility, and localisation for every folder.

If the FOLDERS sheet is not present in the codebook, the existing folder hierarchy in the DataTile database will be preserved. However, if the database is created from scratch, all variables will appear in the root folder.

As elsewhere in the codebook, sheet names, column headers, and folder paths are case-insensitive. Labels are case-sensitive and are preserved exactly as entered.

FOLDER mandatory – A stable identifier for the folder can be thematic (e.g., demo, firm, brand) or hierarchical (e.g., 1, 1.2, 3.2.1).

Must be unique within the sheet.
This is the value that variables reference from the FOLDER column on the VARIABLES sheet.

LEVEL mandatory – An integer indicating the depth in the tree where the folder is located.

The top level is 1.
Higher than the previous row → becomes a child of the previous row.
Equal to the previous row → becomes a sibling under the same parent.
Lower than the previous row → “climb up” accordingly and attach at the new level.
Omission rule: if a LEVEL cell is left blank, it inherits the last stated LEVEL above (useful for consecutive siblings).
Max hierarchy depth is 5.

TYPE OPTIONAL – Display name shown in the UI. Labels are case-sensitive and preserved as entered.

Best practices for defining a folder hierarchy:

Choose durable identifiers: Use concise, stable FOLDER IDs.
Keep it shallow: Most surveys are easiest to navigate at 2–3 levels.
Keep it readable: For the best user experience, design folders to contain between a few and a few dozen variables, allowing users to browse them without excessive scrolling.
Batch siblings: For sequences of siblings at the same depth, set LEVEL on the first and omit on subsequent rows to reduce clutter.
Rename safely: If you need to rename a folder in the UI, change its LABEL; if you change the FOLDER identifier, update FOLDER references on the VARIABLES sheet accordingly.

This model keeps the sheet compact while making the hierarchy explicit, predictable, and easy to maintain – even for large, multi-market projects.

When uploading a codebook, you can also define database parameters, including settings that control how empty or missing values are handled. These parameters are declared on the ‘Properties' sheet of the Codebook.

Codebook: variable declaration and syntax

Codebook: bulk declarations of variables

Codebook: database loading properties