Filters and quotas

4.1 Overview¶

TickStat provides a comprehensive filtering and quota management system that controls how many respondents of each demographic or behavioural profile complete a survey. The system supports two complementary approaches:

Independent filters on questions -- quotas and screen-out rules are configured directly on individual question answers. This is the simpler approach, suitable when you need basic quotas on a single variable (e.g., "accept at most 50 men and 50 women").
Personalized (hierarchical) filters -- multiple filter dimensions are defined centrally in the Edit > Filters panel and combined into a cross-tabulated quota matrix. This is the more powerful approach, used when you need to control quotas across several variables simultaneously (e.g., gender x age x region).

Both approaches can coexist in the same survey. Regardless of approach, the system handles concurrent respondents safely by reserving quota slots and releasing them automatically if a respondent abandons the survey.

4.2 Setting Up Filters¶

To access filter management, open the survey in the admin panel and navigate to Edit > Filters in the left-hand menu. The Filter Management page contains three sections:

Filters table (top section)

Each row in the table represents one filter dimension with the following columns:

Column	Description
Delete	Removes the filter (a confirmation dialog warns that existing quotas will need to be re-entered).
Filter name	A descriptive name for the filter (e.g., "Gender", "Region").
Filter type	The type of filter -- determines how respondent answers are matched to quota categories. See Section 4.3 for all available types.
Select question associated with the filter	The survey question whose answers will be evaluated by this filter.

Action buttons (middle section)

Add filter -- adds a new empty row to the filter table.
Save filters -- persists the current filter configuration. A confirmation dialog warns that existing quotas will need to be re-entered if filters have changed.
Manually generate quotas -- opens a file upload dialog to upload an Excel file containing the target quota numbers for each filter combination.
Download quota template -- downloads an Excel template pre-populated with all quota categories derived from the current filters. Fill in the target numbers and re-upload.

Enable/Disable Filters and Quota List sections are displayed below the main filters table (see Sections 4.6.5 and 4.6.3).

4.3 Filter Types¶

The following filter types are available when defining filters. Each type determines how the associated question's answer is interpreted and matched to quota categories.

4.3.1 Radio Question Filter (Single/Multiple Choice)¶

Type code: 1 (Radio question filter)

Used for standard radio-button ("one possibility") or checkbox ("several possibilities") questions. Each answer option in the linked question becomes a separate quota category. The quota name defaults to the answer identifier unless a Filter Tag (see Section 4.4.2) is specified on the answer, in which case the filter tag text is used.

Example use case: Gender (Male/Female), Product preference, Yes/No screening questions.

4.3.2 Age Filter¶

Type code: 5 (Age filter)

An interval-based filter for numeric age values. The linked question should collect a numeric input (e.g., a line-of-input question asking for year of birth or age). Quota categories are defined as numeric ranges with lower and upper bounds (e.g., 18-25, 26-35, 36-50).

During execution, the respondent's numeric answer is compared against each interval. If the value falls within a range (inclusive on both bounds), the corresponding quota is matched.

Example use case: Age brackets for demographic segmentation.

4.3.3 Spain Region Filter¶

Type code: 2 (Spain Region filter)

Designed for surveys targeting the Spanish market. When quotas are generated, the system automatically creates one quota category for each Autonomous Community of Spain using the official INE (Instituto Nacional de Estadistica) codes. The linked question should be a preconfigured list question of type "Town of Spain," from which the respondent's municipality is resolved to its corresponding Autonomous Community.

4.3.4 Spain Region NUTS Zones Filter¶

Type code: 8 (Spain Region NUTS zones filter)

Similar to the Spain Region filter but uses the European NUTS (Nomenclature of Territorial Units for Statistics) classification instead of Spanish Autonomous Communities. Useful for surveys that need to align with Eurostat regional classifications.

4.3.5 Spain Provinces Filter¶

Type code: 3 (Spain Provinces filter)

Creates one quota category for each province of Spain. Like the Region filter, this requires a "Town of Spain" list question. The respondent's municipality is resolved to its province.

4.3.6 Municipalities of Spain Filter¶

Type code: 13 (Municipalities of Spain)

Creates quota categories at the municipality level. This is the most granular geographic filter and requires a "Town of Spain" list question.

4.3.7 Population Size Filter¶

Type code: 4 (Population size filter)

An interval-based filter that segments respondents by the population size of their municipality. Quota categories are defined as numeric ranges (e.g., 1-2000, 2001-10000, 10001-50000). Requires a "Town of Spain" list question from which the municipality population is obtained.

Example use case: Urban vs. rural segmentation based on city size.

4.3.8 Grouped Education Level Filter¶

Type code: 10 (Grouped education level filter)

Groups the answers of a "one possibility" question into aggregated education level categories. The grouping works by position of the selected answer:

Level 1: First 3 answer options (e.g., no education, primary incomplete, primary complete)
Level 2: Next 2 answer options (e.g., secondary education stages)
Level 3: Next 3 answer options (e.g., university and postgraduate levels)

The linked question must be a radio question whose answer options are ordered from lowest to highest education level.

4.3.9 Wage Level Filter¶

Type code: 11 (Wage level filter)

Similar in structure to the grouped education level filter but applied to income/wage bracket questions. Groups the answer options of the linked question into aggregated wage level categories.

4.3.10 Custom-Capital Filter¶

Type code: 7 (Custom-Capital)

A specialized filter for custom segmentation based on the linked question. Used in scenarios where a custom classification logic is needed beyond the standard filter types.

4.3.11 Uniform Branch Filter¶

Type code: 9 (Uniform branch filter)

Used for experimental designs where respondents must be uniformly distributed across branches (e.g., different versions of the survey). The linked question must have a uniformInterval configuration that defines the branches (e.g., "1,2,3" for three branches). Each branch becomes a quota category (named "Branch:1", "Branch:2", etc.).

At runtime, the system assigns respondents to the branch with the fewest completions, ensuring a balanced distribution. Branches are ordered by occupancy (ascending), and the respondent is assigned to the least-filled branch that still has available quota.

Key difference from other filters: The Uniform Branch filter does not evaluate the respondent's answer. Instead, it selects a branch for the respondent based on current occupancy levels.

4.3.12 Weighted Branch Filter¶

Type code: 14 (Weighted branch filter)

Similar to the Uniform Branch filter, but allows different target quota numbers per branch. While the Uniform Branch filter distributes respondents equally, the Weighted Branch filter respects the specific target quotas defined in the uploaded Excel file.

The linked question must have a uniformInterval configuration in the format "1-P7,2-P8,3-P9" where the first number is the branch identifier and the second is the destination question for that branch. Each branch becomes a quota category (named "Branch:1-P7", "Branch:2-P8", etc.).

Example use case: An A/B/C test where version A needs 100 respondents, version B needs 200, and version C needs 50.

4.3.13 Meat Consumer Filter¶

Type code: 12 (Meat consumer filter)

A domain-specific filter for food science surveys that segments respondents based on meat consumption patterns. Works as a value-based filter on the linked question.

4.4 Independent Filters on Questions¶

Independent filters are configured directly on individual question answers, without using the centralized Filter Management panel. This approach is suitable for simple, single-variable quotas.

4.4.1 Quota per Answer¶

When editing a question's answers (in the question editor), each answer has a Quota field (cuotaNeeded). Enter a number in this field to set the maximum number of respondents that can select that answer. Once the quota is reached, subsequent respondents who select that answer will be screened out.

This field is available on "One possibility" (radio) and "Several possibilities" (checkbox) question types, as well as on preconfigured list questions where quotas can be uploaded via Excel.

For preconfigured list questions (e.g., "Town of Spain"), quotas are uploaded through an Excel file that specifies the code value, quota label, and target number for each list item.

4.4.2 Filter Tag¶

Each answer also has a Filter Tag field (etiquetaFiltro). This field serves two purposes:

Naming quota categories: When using personalized filters with a Radio Question filter type, the filter tag text is used as the quota category name instead of the answer identifier. This provides more readable quota reports (e.g., "Male" instead of "R1").
Triggering early screen out: If the filter tag is set to the literal value earlyscreenout, selecting that answer will immediately trigger an early screen-out for the respondent (see Section 4.10.1).

4.4.3 The Run Filters Checkbox¶

Each question in the question editor has a Run filters toggle checkbox (ejecutarFiltros). This toggle is critical for personalized filters.

When enabled: After the respondent answers this question and clicks "Next," the system evaluates all personalized filters and attempts to reserve a quota slot.
When disabled (default): No filter evaluation occurs when advancing past this question.

Important: Enable the "Run filters" toggle only on the last question that is associated with a filter. If filter questions are spread across multiple steps, only the final filter question should have this toggle enabled. Enabling it prematurely (before all filter questions have been answered) will cause the system to evaluate filters with incomplete data.

4.5 Personalized (Hierarchical) Filters¶

Personalized filters create a cross-tabulated quota matrix from multiple filter dimensions. All filters must be satisfied simultaneously for a respondent to be accepted. For example, if you define filters for Gender (Male/Female) and Age (18-30/31-50/51+), the system creates a matrix with 6 cells (2 x 3), each with its own target quota.

4.5.1 Step-by-Step Setup¶

Follow these steps to configure personalized filters:

Define filters in Edit > Filters:
Navigate to Edit > Filters in the left-hand menu.
Click Add filter for each dimension you need.
For each filter, enter a name, select the filter type, and associate it with the corresponding survey question.
Click Save filters to persist the configuration.
Generate quota categories:
After saving, click Download quota template to get an Excel file with all possible quota combinations.
The template contains columns for each filter and a TARGET column.
Fill in quotas in the Excel template:
Open the downloaded Excel file.
For each row (representing a unique combination of filter values), enter the desired number of respondents in the TARGET column.
Save the Excel file.
Upload the filled quotas:
Click Manually generate quotas on the Filter Management page.
Select the filled Excel file and upload it.
The quota list will appear at the bottom of the page showing all combinations and their targets.
Enable personalized filters in survey settings:
Go to Edit survey (the survey settings form).
Set the Apply filters dropdown to Personalized filters.
Enable "Run filters" on the last filter question:
Edit the last question that is associated with a filter.
Enable the Run filters toggle in the question configuration.
Leave this toggle disabled on all other questions (the default value).
Enable individual filters:
In the Enable/Disable Filters section of the Filter Management page, set each filter to Enable.
Filters that are disabled are skipped during evaluation (but their column in the quota matrix must still have a valid value).

4.5.2 How Personalized Filters Work at Runtime¶

When a respondent advances past the question marked with "Run filters," the following process occurs:

The system collects the respondent's answers to all questions linked to enabled filters.
For each filter, the appropriate filter executor determines which quota category the respondent falls into (e.g., "Female" for a gender filter, "26-35" for an age filter).
The system constructs a query against the encuestaFilter table, looking for a row that matches all the respondent's quota categories and has an available slot.
If a matching slot is found, it is reserved for the respondent (see Section 4.7).
If no matching slot exists because the combination is not in the quota matrix, the respondent receives an early screen out.
If the combination exists but all slots are occupied, the respondent receives a quota full exit.

The system supports up to 6 filter dimensions simultaneously (Q1 through Q6 in the quota matrix).

4.6 Quota Management¶

4.6.1 Download Quota Template¶

Click Download quota template on the Filter Management page. The system generates an Excel file with one row for each unique combination of quota categories across all defined filters. Each row contains the quota category names and a TARGET column where you enter the desired number of respondents.

Important: Always download a fresh template after modifying filters, as changes to filters invalidate existing quota configurations.

4.6.2 Upload Quotas Manually¶

Click Manually generate quotas to open the upload dialog. Select the completed Excel file containing the target quotas. The system parses the file and creates one quota slot per respondent. For example, if a combination has a target of 5, the system creates 5 slots for that combination.

Warning: Uploading quotas replaces any previously configured quotas. All existing quota data for the survey will be cleared before the new data is imported.

4.6.3 Quota List View¶

The Quota List section appears at the bottom of the Filter Management page. It displays a table with the following columns:

Column	Description
Filter Id	The database identifier of the filter.
Filter name	The name given to the filter.
Quota name	The name of the quota category (e.g., "Andalucia", "18-25", "Male").
Associated Question	The question identifier linked to the filter.
Quota Id	The database identifier of the quota category.
Initial Value	The first value defining the category (e.g., the answer ID for value filters, the lower bound for interval filters).
End value	The second value (e.g., the upper bound for interval filters; empty for value filters).
Associated quota	The target number of respondents for this category.

During and after fieldwork, you can monitor quota progress by navigating to Results > Quota Report in the left-hand menu. The quota report shows, for each unique combination of filter values:

Target: The total number of respondent slots configured for the combination.
Completed: The number of slots occupied by respondents who finished the survey.
Pending: The difference between target and completed.

This report is essential for monitoring fieldwork progress and identifying combinations that are filling slowly or have already reached their targets.

4.6.5 Enable and Disable Individual Filters¶

The Enable/Disable Filters section on the Filter Management page allows you to control each filter independently:

Column	Description
Filter Name	Editable name field for the filter.
Enable/Disable	Dropdown to enable or disable the filter. Disabled filters are skipped during quota evaluation -- the system still requires the corresponding column in the matrix to have a value, but any value is accepted (no filtering on that dimension).
Num Tree	The quota tree number this filter belongs to (see Section 4.6.6). Default is 1.

Click Save info to persist changes.

4.6.6 Multiple Quota Trees (Num Tree)¶

TickStat supports up to 4 independent quota trees within a single survey. Each quota tree is an independent set of filters and quotas that are evaluated separately.

The Num Tree field on each filter specifies which quota tree (1, 2, 3, or 4) the filter belongs to. By default, all filters belong to tree 1.

Use case: You need to apply two independent sets of quotas. For example, tree 1 controls demographic quotas (gender x age) while tree 2 controls geographic quotas (region x city size). Each tree is evaluated independently, and the respondent must satisfy all trees to be accepted.

Each quota tree reserves its own slot independently, and if a respondent is screened out, all reserved slots across all trees are released.

4.7 Quota Reservation and Release¶

When the personalized filter system finds an available quota slot for a respondent, it reserves that slot by recording a timestamp. This reservation mechanism prevents two concurrent respondents from claiming the same slot.

How reservation works:

When filters are evaluated (triggered by the "Run filters" question), the system searches for an available quota slot that matches the respondent's filter profile.
An available slot is one that is currently unoccupied — either it has never been reserved, or the previous reservation has expired.
When found, the system marks the slot as reserved by the current respondent and records the reservation timestamp.
When the respondent completes the survey, the slot is permanently assigned to that respondent.

Default reservation timeout: 30 minutes. If a respondent does not complete the survey within 30 minutes of reservation, the system considers the slot abandoned. The next respondent needing that slot will automatically reclaim it.

The timeout is configurable per survey through the Maximum time field in the survey settings (see Section 4.8.2). If a maximum time is configured, that value is used as the reservation timeout. If it is set to 0, the default of 1800 seconds (30 minutes) applies.

Automatic release on exit: When a respondent exits the survey due to quota full, early screen out, or quality terminate conditions, all their reserved quota slots (across all quota trees) are immediately released, making them available for other respondents.

Thread safety: The quota reservation process is synchronized at the application level. Only one thread at a time can execute the filter evaluation and reservation logic. This ensures that two concurrent respondents cannot reserve the same slot, even under high load.

4.8 Time Filters¶

Time filters are configured in the survey settings form (Edit survey) and apply globally to the entire survey.

4.8.1 Minimum Time¶

Enter the minimum number of seconds required to complete the survey in the Minimum time field. If a respondent completes the survey faster than this threshold, they are flagged for poor quality.

The respondent is redirected to the Quality Terminate URL configured in the survey's exit URLs.
Any quota reserved by this respondent is released.
The Quality Terminate counter is incremented by one (visible in the survey list).

Note: Minimum time is checked at the end of the survey, upon final submission.

4.8.2 Maximum Time¶

Enter the maximum number of seconds allowed to complete the survey in the Maximum time field. Each time the respondent clicks "Next" to advance to the next step, the system checks whether the elapsed time exceeds this threshold.

If the maximum time is exceeded, the respondent is removed from the survey.
The respondent is redirected to the Quality Terminate URL.
Any quota reserved by this respondent is released.
The Quality Terminate counter is incremented by one.

Important: The maximum time setting also serves as the quota reservation timeout (see Section 4.7). If set to 0, the reservation timeout defaults to 30 minutes.

4.9 Quota to Collect (Global Quota)¶

To limit the total number of completed responses regardless of filter criteria, configure the target number in the survey settings form (Edit survey). The field is labeled "Number of people to complete the survey."

If this value is set to a number greater than 0, the survey will automatically close once the specified number of completions is reached. No new respondents will be accepted after the global quota is met.

This setting is independent of the personalized filter quotas. Even if individual filter cells still have available slots, the survey will close when the global target is reached.

4.10 Early Screen Out¶

An early screen out removes a respondent from the survey before completion because they do not meet the required criteria. The respondent is redirected to the Early Screen Out URL configured in the survey's exit URLs, and the Early Screen Out counter is incremented (visible in the survey list).

4.10.1 From Answer Labels¶

You can trigger an early screen out based on the respondent's answer to a "one possibility" or "one option with validation" question. To configure this:

Edit the question and locate the answer that should trigger the screen out.
In the Filter Tag field (etiquetaFiltro) of that answer, enter the literal text earlyscreenout.
Save the question.

When a respondent selects that answer and advances to the next step, the system sets the earlyScreenOut flag, and the respondent is redirected to the early screen out URL.

This mechanism works on the following question types: one option, one option with validation, and general validation questions.

4.10.2 From Personalized Filters¶

When using personalized filters, an early screen out occurs automatically if the respondent's combination of answers does not match any row in the quota matrix. This happens when either:

One of the filter questions has no quotas defined (configuration error).
The specific combination of the respondent's answers across all filter dimensions does not exist in the uploaded quota matrix.

In both cases, the system flags the respondent for early screen out and redirects them to the configured URL.

Distinction from quota full: A "quota full" exit occurs when the combination exists in the matrix but all slots for that combination are already occupied. An "early screen out" occurs when the combination itself is not present in the matrix.

When a survey is offered in multiple languages (e.g., Spanish and Catalan), you typically create separate survey instances for each language. However, filters and quotas should be managed centrally in a single master survey to ensure consistent quota tracking across all language variants.

Configuration steps:

Define all filters and quotas in the master survey (the original language version) using the standard process described in Section 4.5.1.
Duplicate the survey for each additional language. The configuration is cloned during duplication.
In each language variant, go to the survey settings form and enter the ID of the master survey in the "Interviewer telephones" field. This tells the system to use the master survey's filter and quota configuration instead of its own.

How it works at runtime: When a respondent takes a language variant, the system loads the filter definitions and quota matrix from the master survey (identified by the ID in the "Interviewer telephones" field). Quota slots are reserved and counted against the master survey's quotas. This ensures that the total number of respondents across all language variants respects the configured targets.

Important: The question configuration (identifiers, answer order, filter associations) in all language variants must be identical to the master survey. Since they are duplicates, this should be the case automatically -- but any structural changes made to one variant must be replicated across all others.