ifcfill 0.2.0

Transformer of tabular data into Integer, Float and Categorical (IFC) variables with missing data imputation.

ifcfill

ifcfill is a Python library for preparing tabular data for synthetic-data generation. It transforms real tabular data into Integer, Float, and Categorical (IFC) variables with fast NumPy-powered missing data imputation, then applies the same learned inverse transformation to generated synthetic data so it can be mapped back to the original table structure.

---

Purpose

ifcfill is designed to sit around tabular synthetic-data generators:

1. Fit IFCTransformer on real data.
2. Transform the real data into generator-friendly IFC variables.
3. Train or run any tabular generator on the transformed data.
4. Apply inverse_transform() to the synthetic output using the mappings learned from the real data.

The package is intentionally unsupervised: it does not require or model a target variable.

---

Features

• Flexible input — accepts a pandas.DataFrame or a path to a CSV file
• Automatic type inference — detects integer, float, categorical, and datetime columns automatically; user overrides supported per column
• Configurable imputation — choose fill strategy independently for each type:
  • Integer: mean, median, mode, zero
  • Float: mean, median, mode, zero
  • Categorical: constant (default), mode
• Categorical missingness as a category — missing categorical values are transformed into a learnable category and converted back to missing values during inverse_transform()
• Optional categorical label encoding — encode categories as integer codes while keeping enough mapping metadata for inverse_transform()
• Datetime → integer conversion — converts date/time columns to integers relative to a configurable anchor date and time unit (days, seconds, ms, …)
• Constant column removal — automatically detects and drops columns with a single unique value
• Missing value tracking — records the count and fraction of missing values per column at fit time, accessible via missing_report_
• Full transformation bookkeeping — inverse_transform() restores dropped constants, original column order, and optionally re-introduces missing values at the original rate
• Synthetic-data workflow support — apply one inverse transformation consistently to both transformed real data and generated synthetic data

---

Installation

pip install ifcfill

---

Quick Start

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 → will be dropped
})

tf = IFCTransformer(
    int_fill="median",
    float_fill="mean",
    datetime_anchor="1970-01-01",
    datetime_unit="D",
)

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

# Inspect missing-value distribution captured at fit time
print(tf.missing_report_)

# Restore original structure.
# Categorical missing categories are converted back to missing values.
restored = tf.inverse_transform(transformed, restore_missing=True, random_state=42)
print(restored)

From a CSV file

transformed = IFCTransformer().fit_transform("data.csv")

Override column types

tf = IFCTransformer(col_types={"age": "categorical", "score": "float"})
transformed = tf.fit_transform(df)

---

Documentation

Full documentation including the API reference is available at: https://eulerlettersai.github.io/ifcfill

---

License

Apache 2.0 — see LICENSE.