DataCard Reference

The DataCard is a YAML file that describes your dataset for Pilz.

Complete Example

features:
  - name: age
    statistical: categorial
    type: int
    missing_value: 0
  - name: name
    statistical: categorial
    type: string
  - name: balance
    statistical: numerical
    type: float
    missing_value: 0.0
  - name: churn
    statistical: categorial
    type: string

target:
  feature_name: churn
  values:
    - 'Yes'
    - 'No'

infos:
  source: https://example.com/data
  license: MIT
  date: '2024-01-01'

Field Reference

features

List of all columns, including the target column.

Field	Type	Required	Description
name	string	Yes	Column name in the CSV or Parquet data
statistical	string	Yes	"categorial" or "numerical"
type	string	Yes	Free-form data type string (not validated); "int", "float", "string"/"str", or "bool"
missing_value	int \| str \| float \| bool \| None	No	Value to impute nulls; if omitted, nulls become their own "missing" category

target

Describes the target variable.

Field	Type	Required	Description
feature_name	string	Yes	Column name of target
values	list	Yes	All possible class values

infos

Metadata dictionary for documentation. Required — the DataCard model has no default for infos, so every datacard must provide it (auto-generation writes a single bla key holding the answer to the "Infos about the dataset" prompt).

infos:
  source: https://example.com
  license: MIT
  description: Customer churn dataset
  version: '1.0'

Note: Data file paths are not part of the DataCard anymore. train_files goes into the TrainSettings, test_files into the EvalSettings. See the Settings Reference.

FeatureType Values

Value	Use For	Example
categorial	Discrete values	"yes", "no", "admin", "blue-collar"
numerical	Continuous values	1.5, 100, -42

!> Important: Use categorial (not categorical)

DataType Values

Value	Description
int	Integer numbers
float	Decimal numbers
string	Text values
str	Alias for string, accepted by the loader
bool	Boolean values true/false (incl. nulls)

type itself is an unvalidated free string; these are the values the loader understands.

Boolean Features

Boolean columns are declared with type: bool. Internally they are treated as a categorical feature with exactly two categories (true and false) plus an optional missing category, and are always represented as the strings 'true'/'false' — never as the integers 1/0.

features:
  - name: is_active
    statistical: categorial
    type: bool

• In the source data the column may be a true boolean (Parquet) or true/false text (CSV). Both are normalized to the strings 'true'/'false' at load time.
• Nulls in a boolean column without missing_value become their own "missing" category (see Missing Values).
• missing_value must be one of true, false, 'true' or 'false':

features:
  - name: is_active
    statistical: categorial
    type: bool
    missing_value: false

• A boolean target uses string values too:

target:
  feature_name: is_click
  values:
    - 'true'
    - 'false'

Write the target values as quoted strings. Raw YAML booleans ([true, false]) are rejected because Pilz would otherwise silently turn them into 1/0.

Auto-Generation

Instead of writing manually, use:

pilz create-dc --src data.csv --out datacard.yaml

This interactive command:

1. Prompts for the target column until a valid column name is entered.
2. Derives each feature's type and statistical automatically from the column dtype (no user prompt); the target column is marked categorial.
3. Prompts once for a replacement missing_value for any column containing nulls or float NaN.
4. Prompts for "Infos about the dataset" and writes the answer as infos: {bla: <answer>}.

Missing Values

• With missing_value set: nulls are imputed with that value at load time (both train and eval).
• Without missing_value: nulls stay in the data and are treated as their own "missing" category during categorization. Training produces IS NULL / IS NOT NULL conditions in the spores, and eval scores those rows the same way.
• If the target column contains nulls and has no missing_value, those rows are excluded from training/eval (the SQL target filter never matches them).

Validation

The DataCard model performs only a few checks:

• A boolean feature's missing_value must be True, False, 'true' or 'false' (_validate_bool_missing_value).
• target.values must not contain raw YAML booleans; write them as the strings 'true'/'false' (_reject_bool_target_values).

Everything else is not validated up front:

• Feature names and target values are not checked against the data. A wrong feature name surfaces as a raw Polars error when the data is loaded.
• The datacard has no file-path fields, so there are no paths to validate; train_files/test_files live in the settings files (see the Settings Reference).