Getting Started¶

Requirements¶

Python 3.9–3.12
numpy >= 1.23
pandas >= 1.5

Installation¶

Install from PyPI:

pip install ifcfill

To install the optional notebook dependencies for the examples:

pip install "ifcfill[examples]"

Your First Transformation¶

1 — From a pandas DataFrame¶

import numpy as np
import pandas as pd
from ifcfill import IFCTransformer

df = pd.DataFrame({
    "age":    [25, 30, None, 40],
    "salary": [50_000.5, None, 75_000.0, 90_000.25],
    "city":   ["London", None, "Paris", "London"],
    "joined": pd.to_datetime(["2020-01-01", "2021-06-15", None, "2023-03-10"]),
    "flag":   ["yes", "yes", "yes", "yes"],  # constant column
})

tf = IFCTransformer()
transformed = tf.fit_transform(df)
print(transformed)

Output:

   age       salary    city  joined
0   25   50000.500  London   18262
1   30   71666.917  __ifcfill_missing__  18793
2   30   75000.000   Paris   19063    ← NaT filled with median
3   40   90000.250  London   19426

Note

The flag column is automatically dropped because it is constant.

2 — From a CSV file¶

tf = IFCTransformer()
transformed = tf.fit_transform("path/to/data.csv")

3 — Fit once, transform many times¶

tf = IFCTransformer()
tf.fit(train_df)

transformed_train = tf.transform(train_df)
transformed_test  = tf.transform(test_df)   # same rules applied

4 — Save the fitted transformation state¶

Save the fitted state when inverse transformation may happen later or on another machine:

tf.save("ifcfill-state.json")

Load it back without fitting again:

loaded_tf = IFCTransformer.load("ifcfill-state.json")
restored = loaded_tf.inverse_transform(synthetic_ifc)

5 — Use label encoding for categorical generator inputs¶

tf = IFCTransformer(cat_encoding="label")
transformed = tf.fit_transform(df)

print(tf.get_category_mappings())

Categorical values are filled first, then the label encoder maps the resulting categories to integer codes. During inverse transformation, integer codes are decoded before IFCFill applies its authoritative reconstructed missingness mask.

6 — Check what happened¶

# See types detected for each column
print(tf.column_types_)

# See fill values chosen for each column
print(tf.fill_values_)

# Full missing-value report
print(tf.missing_report_)

7 — Restore the original structure¶

restored = tf.inverse_transform(
    transformed,
    missingness_restore="marginal",  # fitted P(M_j); this is the default
    random_state=42,
)
print(restored)

Use missingness_restore="joint" to reconstruct the fitted empirical row-wise distribution P(M_1, ..., M_p) instead. Both modes cover all original column types. The categorical synthesis sentinel is internal and does not decide which final values are missing.

Next Steps¶

Examples — notebook walkthrough of the main workflow
User Guide — detailed walkthrough of every feature
API Reference — complete parameter and return-type documentation