5-minute introduction to data exploration, filtering, and summaries
Tutorials
Getting Started
Sample Object
Python
Learn the svy Sample object - your central interface for survey data exploration, filtering, summaries, and analysis. Master data inspection, weighted summaries, and immutable transformations.
Author
Mamadou S. Diallo, Ph.D.
Published
January 18, 2026
Modified
April 11, 2026
Keywords
survey data exploration Python, weighted summary statistics Python, survey data filtering Python, complex survey object Python, survey data inspection Python, weighted descriptive statistics Python, Polars DataFrame survey analysis, survey data wrangling Python, design-based summary statistics
5-minute introduction to Sample—the core object you’ll use throughout these tutorials.
What is Sample?
Sample wraps your survey data (a Polars DataFrame) with design information, providing a unified interface for data exploration, wrangling, weighting, and estimation.
Think of Sample as:
Your survey dataset + design metadata
A gateway to all svy functionality
Immutable by default (transformations return new Sample objects)
╭────────────── Sample ──────────────╮│Survey Data││ Rows : 5 ││ Columns : 7 ││ Strata : 3 ││ PSUs : None ││││Survey Design││ Row index svy_row_index ││ Stratum region ││ PSU None ││ SSU None ││ Weight weight ││ With replacement False ││ Prob None ││ Hit None ││ MOS None ││ Population size None ││ Replicate weights None │╰────────────────────────────────────╯
Quick Data Inspection
Preview Data
# First 3 rowssample.show_data(n=3)# Specific columns onlysample.show_data(columns=["id", "region", "age"], n=3)# Last 2 rows, sorted by agesample.show_data(n=2, order_by="age", order_type="descending")# Random sample (reproducible with seed)sample.show_data(n=3, rstate=42)
shape: (3, 6)
svy_row_index
id
region
age
income
weight
u32
i64
str
i64
i64
f64
0
1
"North"
22
45000
1.0
1
2
"South"
47
62000
1.2
2
3
"North"
35
51000
0.9
Filter Records
# Filter by values (dictionary syntax)sample.show_data(where={"region": ["North", "East"]}, columns=["id", "region", "age"])# Filter with expressionssample.show_data( where=[svy.col("age") >30, svy.col("region") =="South"], order_by="income", order_type="descending",)
shape: (1, 6)
svy_row_index
id
region
age
income
weight
u32
i64
str
i64
i64
f64
1
2
"South"
47
62000
1.2
Sample Properties
Access key information about your sample:
print(f"Number of records: {sample.n_records}\n")print(f"Number of columns: {sample.n_columns}\n")print(f"Number of strata: {sample.n_strata}\n")print(f"Number of psus: {sample.n_psus}\n")print(f"Strata: {sample.strata}")# Access underlying data (defensive copy)df_copy = sample.dataprint(df_copy.head())# Access designdesign_copy = sample.designprint(design_copy)
Number of records: 5
Number of columns: 7
Number of strata: 3
Number of psus: 0
Strata: shape: (3, 1)
┌────────┐
│ region │
│ --- │
│ str │
╞════════╡
│ East │
│ North │
│ South │
└────────┘
shape: (5, 6)
┌───────────────┬─────┬────────┬─────┬────────┬────────┐
│ svy_row_index ┆ id ┆ region ┆ age ┆ income ┆ weight │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ u32 ┆ i64 ┆ str ┆ i64 ┆ i64 ┆ f64 │
╞═══════════════╪═════╪════════╪═════╪════════╪════════╡
│ 0 ┆ 1 ┆ North ┆ 22 ┆ 45000 ┆ 1.0 │
│ 1 ┆ 2 ┆ South ┆ 47 ┆ 62000 ┆ 1.2 │
│ 2 ┆ 3 ┆ North ┆ 35 ┆ 51000 ┆ 0.9 │
│ 3 ┆ 4 ┆ East ┆ 61 ┆ 78000 ┆ 1.1 │
│ 4 ┆ 5 ┆ South ┆ 29 ┆ 43000 ┆ 0.8 │
└───────────────┴─────┴────────┴─────┴────────┴────────┘
╭───────────── Design ─────────────╮│ Row index svy_row_index ││ Stratum region ││ PSU None ││ SSU None ││ Weight weight ││ With replacement False ││ Prob None ││ Hit None ││ MOS None ││ Population size None ││ Replicate weights None │╰──────────────────────────────────╯
Note:sample.data and sample.design return defensive copies—safe to inspect without modifying the original Sample.