Skip to main content
Population model creation is a paid feature on the Play and Launch pricing plans. Visit the account page in the dashboard to upgrade.
Custom populations allow you to make predictions for your specific audience segments, customers, or user groups. This guide shows how to create populations programmatically using the Semilattice API.

​
Prerequisites

Before creating a population, ensure you have:
  • Seed data from a target group of users or customers in the required CSV format
  • A valid Semilattice API key
  • A paid subscription on the Play or Launch pricing plans
  • The Semilattice SDK installed

​
Creating a population

from pathlib import Path
from semilattice import Semilattice

semilattice = Semilattice()

# See population options section below
population_options = json.dumps({
    "question_options": [
        {
            "question_number": 1,
            "question_type": "single-choice"
        },
        # { ... 18 other question option dicts ... }
        {
            "question_number": 20,
            "question_type": "multiple-choice",
            "limit": 3
        }
    ]
})

response = semilattice.populations.create(
    name="Developers",
    description="Model of professional software developers",
    seed_data=Path("developer_survey_data.csv"),
    reality_target="Software developers",
    data_source="Q4 developer survey",
    effective_date="2024-10-18",
    population_options=population_options,  # see below
    run_test=False
)
population = response.data

​
Parameters

ParameterTypeDescription
namestringDisplay name for your population
seed_datafile/pathCSV file containing tabular QA pair data
population_optionsobjectTells the API about the data in your seed data file
descriptionstringDetailed description or documentation link (optional)
reality_targetstringDescription of the target user profile (optional)
data_sourcestringDescription of where the seed data comes from (optional)
effective_datedateDate when the data was sourced in reality (optional)
run_testbooleanWhether to automatically test the population after creation

​
Population options

Population options tell the API how to process your seed data. Semilattice supports single-choice, multiple-choice, and open-ended question types in seed data, so the API needs to know which of these types each column in the dataset represents. 
population_options = json.dumps({
    "question_options": [
        {
            "question_number": 1,
            "question_type": "single-choice"
        },
        {
            "question_number": 2,
            "question_type": "multiple-choice",
            "limit": 2
        },
        # { ... question option dicts for all columns ... }
    ]
})
Population options object The populations options object must be a valid JSON object containing one question_options key. The value of question_options should be a valid JSON list containing one object for each question column in the dataset. The sim_id column does not need to be referenced. Question options field descriptions:
  • question_number: A 1-based index reference to the column in the seed data file these questions options describe. For example, when setting question objects for the 3rd question column in the dataset, which would be the 4th column in the CSV after the sim_id column, the question_number should be 3.
  • question_type: An enum describing the question type for that question column. Must be one of: single-choice, multiple-choice, open-ended.
  • limit (optional): For multiple-choice questions only, this sets the maximum number of choices respondents were allowed to select.
Requirements:
  • The question_options list must contain one object for each question column in the seed data file.
  • The question_number values should be integers corresponding to the 1-based column positions in your CSV file. The order of the question option objects doesn’t matter, but we suggest sequential ordering to avoid confusion.
  • The question_type specified for a column must match the actual data for that column in the CSV.
This configuration ensures test simulations run correctly when evaluating population accuracy. For more details on data format requirements, see Seed Data Requirements.

​
Population status flow

When you create a population, it goes through several status stages:

​
1. Processing

Initially, your population will have a status of Processing while Semilattice processes and stores your data. 
print(f"Population status: {population.status}")
# Output: Population status: Processing

​
2. Untested

Once processing completes, the status changes to Untested. At this point:
  • The population is ready to make predictions
  • We don’t yet know its estimated accuracy
# Check status periodically
response = semilattice.populations.get(population_id=population.id)
population = response.data
print(f"Status: {population.status}")
# Output: Status: Untested

​
3. Testing

When you trigger accuracy testing, either automatically or manually (see below), the status changes to Testing while Semilattice evaluates the population’s prediction accuracy.

​
4. Tested

Once testing completes, the status becomes Tested and the population will have accuracy metrics available for review.

​
Testing population accuracy

To understand how accurate your population will be, you need to run a population test.

​
Option 1: Automatic testing

Set run_test=True when creating the population: 
response = semilattice.populations.create(
    name="Developers",
    description="Model of professional software developers",
    seed_data=Path("developer_survey_data.csv"),
    reality_target="Software developers",
    data_source="Q4 developer survey",
    effective_date="2024-10-18",
    population_options=population_options,
    run_test=True  # Automatically test after processing
)
With automatic testing, your population will progress through these statuses: Processing → Untested → Testing → Tested

​
Option 2: Manual testing

Alternatively, you can trigger testing manually on an Untested population: 
# Trigger testing manually
response = semilattice.populations.test(
    population_id=population.id
)
population = response.data
# population.status will be "Testing"

​
Understanding test results

Once testing is complete, your population will have:
  • Status: Tested
  • Accuracy metrics: Estimated accuracy scores
Learn more about interpreting these metrics and performance thresholds in the Accuracy Evaluation section.
⌘I