A3S / LA3S: Adaptive Ratio Imputation for Compositional Data

A3S (Adaptive Ratio Imputer) is a fast, constraint-guaranteed imputation method for compositional data — e.g. alloy compositions, glass formulations, cement recipes — where all components must sum to a fixed total (e.g. 100%).

🔑 Key Features

• Strict constraint satisfaction: Sum deviation = 0 (machine precision), non-negative guaranteed
• No covariance estimation: Only needs column medians — robust for n < d (small samples, many features)
• No log-ratio transforms: Works natively with zeros (no pseudo-counts needed)
• Three variants:
  • A3S (global profile) — simple & fast, best for low missing rates (< 15%)
  • LA3S (local k-NN profile) — adaptive, best for high missing rates (≥ 15%)
  • Auto-A3S — automatically selects between A3S and LA3S
• Single-pass, no iteration: O(n·d) complexity, orders of magnitude faster than iterative methods

⚡ Quick Start

import numpy as np
from a3s_imputer import a3s, la3s, auto_a3s, check_compositional_validity

# Example: 3 alloy compositions, missing Fe and C
X = np.array([
    [70.0, 15.0, 15.0],   # Fe, C, Mn — complete
    [np.nan, 20.0, 10.0], # Fe missing
    [65.0, np.nan, 20.0], # C missing
])

# A3S: global profile (fast, simple)
X_a3s = a3s(X, comp_idx=[0, 1, 2], total=100.0)
print(X_a3s)
# [[70.0  15.0  15.0]
#  [70.0  20.0  10.0]   <- Fe allocated from global profile
#  [65.0  15.0  20.0]]  <- C allocated from global profile

# Check constraints
valid = check_compositional_validity(X_a3s, comp_idx=[0, 1, 2], total=100.0)
print(valid["sum_dev_mean"])  # ~1e-15 (machine precision zero)

# LA3S: local k-NN profile (for high missing rates)
X_la3s = la3s(X, comp_idx=[0, 1, 2], total=100.0, n_neighbors=2)

# Auto-A3S: let the algorithm decide
X_auto = auto_a3s(X, comp_idx=[0, 1, 2], total=100.0)

📖 When to use which?

Variant	Missing rate	Speed	Use case
A3S	< 15%	⚡ Fastest	Default choice; simple & robust
LA3S	≥ 15%	⚡ Fast	When global profile is unreliable
Auto-A3S	Unknown	⚡ Fast	When you don't want to decide

🧪 Validation Results

Tested on 6 synthetic material datasets + MatMiner steel_strength (312 real samples, 14 compositional features):

Dataset	Missing rate	A3S MAE	LA3S MAE	MICE MAE	SumDev (A3S)
Steel (real)	5%	0.306	0.088	0.255	~0
Steel (real)	10%	0.605	0.239	0.486	~0
Steel (real)	20%	0.934	0.508	0.704	~0

Note: MICE, KNN, MissForest violate constraints (SumDev = 0.3–3.3%). A3S/LA3S guarantee SumDev = 0.

🔧 Installation

pip install numpy pandas scikit-learn

Then copy a3s_imputer.py to your project directory.

📚 API Reference

a3s(X, comp_idx, total=100.0) — Global profile

a3s(X, comp_idx=[0,1,2], total=100.0)

la3s(X, comp_idx, n_neighbors=5, total=100.0) — Local k-NN profile

la3s(X, comp_idx=[0,1,2], n_neighbors=5, total=100.0)

auto_a3s(X, comp_idx, threshold=0.15, total=100.0) — Adaptive switch

auto_a3s(X, comp_idx=[0,1,2], threshold=0.15, total=100.0)

project_to_simplex(x, total=100.0) — Post-hoc constraint projection

project_to_simplex([70, 15, 15], total=100.0)  # [70.0, 15.0, 15.0]

check_compositional_validity(X, comp_idx, total=100.0) — Verify constraints

check_compositional_validity(X_imp, comp_idx=[0,1,2], total=100.0)
# Returns: {'sum_dev_mean': 0.0, 'valid': True, ...}

📝 Citation

If you use A3S / LA3S in your research, please cite:

@software{a3s_imputer,
  title = {A3S/LA3S: Adaptive Ratio Imputation for Compositional Data},
  author = {Your Name},
  year = {2026},
  url = {https://github.com/wenyu2026/a3s-imputer}
}

📄 License

MIT License — see LICENSE for details.

🙏 Acknowledgments

A3S was developed as part of the SmallMatPrep toolkit for small-sample materials data preprocessing.