layeredcompmodel 0.1.0__tar.gz

layeredcompmodel-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install & Test
+      run: |
+        pip install -e .[dev]
+        pytest tests/ --cov=layeredcompmodel --cov-report=term-missing --cov-fail-under=75 -ra 
+        mypy src/layeredcompmodel
+        ruff check src/ tests/
+        python -m build
+        pip install twine
+        twine check dist/*

layeredcompmodel-0.1.0/.gitignore

@@ -0,0 +1,134 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.PyInstaller/
+result/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are covered by other .gitignore patterns already,
+#  but this one is useful for ensuring that the deployment directory is available
+.PyInstaller/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.pytest_cache/
+hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.venv/
+env/
+ENV/
+env.bak/
+venv/
+ENV/
+env.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# VSCode
+.vscode/
+
+# JetBrains IDEs
+.idea/
+
+# uv
+uv.lock

layeredcompmodel-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.1.0] - 2026-04-22
+### Added
+- Initial release: Hierarchical tree-based regressor using path-weighted Wilson means (95% trimmed) for robust predictions (e.g., parcel sale prices).
+- NaN handling: Categorical NaNs as distinct "NaN" category (`fillna("NaN").unique()`); numeric NaNs excluded from splits via `notna()` masks (per SPEC.md); target `y` must be finite (raises `ValueError`).
+- Scikit-learn compliance: `BaseEstimator`/`RegressorMixin`; works with `Pipeline`, `GridSearchCV`, `cross_val_score`, pickling; partial `check_estimator` pass (intentional NaN trade-off).
+- Development: Full type hints (`py.typed`, mypy-ready), 16+ unittest/pytest tests (splits/NaN/explain/pickle/sklearn), `examples/quickstart.py` (MAE ~127k), `src/` layout, Hatchling build, dev deps (ruff/black/mypy).
+
+Future releases will include Sphinx docs, benchmarks (vs XGBoost/LinearR), CI/CD.

layeredcompmodel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

layeredcompmodel-0.1.0/MODEL_SPEC.md

@@ -0,0 +1,48 @@
+# Layered Comp Model
+
+# Overview:
+
+The idea is to build "hierarchical" predictions that start with a general predicted price, then refine the prediction to be more specific by adding information and narrowing the comparison group.
+
+You take the "Wilson mean" of all your parcels, then you find a filter that splits them into the best submarkets you can find and produce a "child node" for each variant of that filter (using a one-vs-rest approach for categorical data). Then you repeat until you've filtered down to a single data point. The value is a weighted average that prioritizes comparing well against closer matches and comparing slightly less well against further matches.
+
+To get the predictions back out, you find the most specific bucket your subject matches, then you trace its path up the tree, taking and weighting the Wilson means as you go.
+
+# Method:
+
+## Training
+
+1. Build a tree.
+2. Plot sale prices.
+3. Take the Wilson mean: This is defined as the mean after trimming the top 2.5% and the bottom 2.5% (the middle 95%).
+4. Find a set of filters to use (segmentation score based on weighted MAE reduction (MAE of sale prices vs the mean of the subset)).
+5. Make child nodes (one-vs-rest for categorical, or binary split for numeric using binary search for the breakpoint). We choose the split that results in the lowest ratio of weighted child MAE to parent MAE.
+6. Repeat from step 3 until we've filtered down to a single parcel (leaf node) or cannot split further (minimum node size = 2).
+
+## Predicting
+
+1. Find the node furthest down in the hierarchy that matches your parcel.
+2. Note its Wilson mean and the Wilson means of all nodes above it in the hierarchy.
+3. Calculate weights for each node in the path:
+   - Use the formula $w(x)=(1−x)^{weight\_falloff}$.
+   - $x$ is normalized from 0 to 1, evenly spaced by the depth of the node.
+   - $x = 0$ for the most specific (leaf) node.
+   - $x = 1$ for the root node.
+4. Take the weighted average of the Wilson means.
+5. There's your prediction.
+
+# Hyperparameters
+
+weight_falloff: 0 to 1. Will be used in w(x)=(1−x)^weight_falloff where x is normalized from 0 to 1
+
+# Nuances:
+
+The Wilson Mean keeps the prediction from going too crazy on the large sets, and it also penalizes the small sets so when the test set gets specific, the value won't swing wildly.
+
+No parcel will get mapped to its own sale price because the weight falloff of the means will add some noise to it, in the direction of the broader market.
+
+Every parcel should compare well because this model is fundamentally doing a hierarchical version of comp analysis to determine the value.
+
+If a predicted parcel has a feature that wasn't in the training set, that particular level of nuance will be missed, but the parcel will still slot into a node slightly higher up the tree, so the model should still perform reasonably well even for things we don't have representative sales for.
+
+The function that the weighted medians follows will determine a lot of how this model handles accuracy vs equity. A fast falloff will give good accuracy but may miss broader market trends. A slow falloff will promote "normativity" in predictions, but may miss market nuance and not assign correct values to particularly rare but valuable features.

layeredcompmodel-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: layeredcompmodel
+Version: 0.1.0
+Summary: Hierarchical tree-based model for robust parcel sale price predictions using weighted Wilson means.
+Project-URL: Homepage, https://github.com/JohnKossa/layeredcompmodel
+Project-URL: Repository, https://github.com/JohnKossa/layeredcompmodel.git
+Project-URL: Bug Tracker, https://github.com/JohnKossa/layeredcompmodel/issues
+Author: John Kossa
+License: MIT License
+        
+        Copyright (c) 2026 Your Name
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: hierarchical-model,real-estate,regression,scikit-learn
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: scipy>=1.10.0
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: scikit-learn[dev]; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# LayeredCompModel
+
+[![PyPI version](https://badge.fury.io/py/layeredcompmodel.svg)](https://pypi.org/project/layeredcompmodel/)
+[![Documentation Status](https://readthedocs.org/projects/layeredcompmodel/badge/?version=latest)](https://layeredcompmodel.readthedocs.io/en/latest/?badge=latest)
+[![Tests](https://github.com/JohnKossa/layeredcompmodel/actions/workflows/ci.yml/badge.svg)](https://github.com/JohnKossa/layeredcompmodel/actions)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Hierarchical tree-based regressor for robust predictions (e.g., parcel sale prices) using path-weighted Wilson means (95% trimmed means for outlier resistance).
+
+* [MODEL_SPEC.md](MODEL_SPEC.md): High-level method.
+* [SPEC.md](SPEC.md): Detailed implementation specs.
+
+## Features
+
+- **Scikit-learn compatible**: Inherits `BaseEstimator`/`RegressorMixin`; works with `Pipeline`, `GridSearchCV`, `cross_val_score`, pickling.
+- **Automatic feature handling**: Categorical (one-vs-rest splits), numeric (binary search breakpoints), NaNs/missing values.
+- **Robust statistics**: Wilson means prevent outlier swings.
+- **Configurable weighting**: `weight_falloff` balances local accuracy vs. market normativity.
+- **Explainable**: `explain_value(row)` shows path, weights, means.
+- **Serializable**: `to_json()`, `to_dict()`.
+- **Parallel**: `n_jobs` support.
+
+### NaN Handling
+- **Categorical**: Treated as distinct "NaN" category.
+- **Numeric**: Excluded from splits (robust; per SPEC.md).
+- **Target `y`**: Must be finite (raises `ValueError`).
+- Strict checks: Use `Pipeline([('imputer', SimpleImputer()), ('model', LayeredCompModel())])`.
+
+## Installation
+
+```bash
+pip install layeredcompmodel
+```
+
+For development:
+
+```bash
+git clone https://github.com/JohnKossa/layeredcompmodel.git
+cd layeredcompmodel
+pip install -e .[dev]
+```
+
+## Quickstart
+
+```python
+import pandas as pd
+import numpy as np
+from layeredcompmodel import LayeredCompModel
+
+# Synthetic real-estate-like data
+rng = np.random.default_rng(42)
+n_samples = 100
+data = {
+    'neighborhood': rng.choice(['North', 'South', 'East'], n_samples),
+    'size_sqft': rng.normal(2000, 500, n_samples),
+    'price': rng.normal(500000, 100000, n_samples) + 100 * rng.normal(0, 1, n_samples) * (rng.normal(0, 1, n_samples) * 2000)
+}
+df = pd.DataFrame(data)
+X = df[['neighborhood', 'size_sqft']]
+y = df['price']
+
+# Train
+model = LayeredCompModel(weight_falloff=0.8, n_jobs=1)
+model.fit(X, y)
+
+# Predict
+predictions = model.predict(X)
+print(f"Predictions shape: {predictions.shape}")
+print(f"MAE: {np.mean(np.abs(predictions - y)):.0f}")
+
+# Explain single prediction
+explanation = model.explain_value(X.iloc[0:1].squeeze())
+print(explanation)
+```
+
+## API Reference
+
+### LayeredCompModel(weight_falloff=0.5, split_metric='mae', n_jobs=1)
+
+- `fit(X, y)`: Build tree from features `X` (DataFrame), target `y` (Series).
+- `predict(X)`: Predict using path-weighted means.
+- `explain_value(row)`: Dict with path nodes, depths, weights, wilson_means.
+- `to_json(indent=4)`: JSON tree dump.
+- `tree_`: Root `CompNode` (filter_col, filter_val, wilson_mean, children).
+
+See [docs](https://layeredcompmodel.readthedocs.io) (TBD).
+
+## Examples
+
+See [`examples/quickstart.py`](examples/quickstart.py) for a runnable example (code matches Quickstart above).
+
+**Run it:**
+```bash
+python examples/quickstart.py
+```
+
+**Expected output:**
+```
+Predictions shape: (100,)
+MAE: 126914
+{'final_prediction': 530354.0426294187, 'weight_falloff': 0.8, 'path': [{'depth': 0, 'wilson_mean': 476353.91361128056, 'count': 100, 'is_leaf': False, 'filter_col': 'size_sqft', 'filter_val': 2101.366485546922}, {'depth': 1, 'wilson_mean': 553953.0606894617, 'count': 42, 'is_leaf': False, 'filter_col': 'neighborhood', 'filter_val': 'North'}, {'depth': 2, 'wilson_mean': 525096.3185716979, 'count': 13, 'is_leaf': True}], 'calculation': '0.199*476354 + 0.512*553953 + 0.289*525096 = 530354'}
+```
+
+## Development & Testing
+
+```bash
+pytest tests/ --cov=layeredcompmodel
+black src/
+mypy src/
+```
+
+CI/CD, Sphinx docs: planned.
+
+## Citing
+
+Kossa, J. (2026). LayeredCompModel. GitHub. https://github.com/JohnKossa/layeredcompmodel
+
+## License
+
+[MIT](LICENSE)

layeredcompmodel-0.1.0/README.md

@@ -0,0 +1,120 @@
+# LayeredCompModel
+
+[![PyPI version](https://badge.fury.io/py/layeredcompmodel.svg)](https://pypi.org/project/layeredcompmodel/)
+[![Documentation Status](https://readthedocs.org/projects/layeredcompmodel/badge/?version=latest)](https://layeredcompmodel.readthedocs.io/en/latest/?badge=latest)
+[![Tests](https://github.com/JohnKossa/layeredcompmodel/actions/workflows/ci.yml/badge.svg)](https://github.com/JohnKossa/layeredcompmodel/actions)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Hierarchical tree-based regressor for robust predictions (e.g., parcel sale prices) using path-weighted Wilson means (95% trimmed means for outlier resistance).
+
+* [MODEL_SPEC.md](MODEL_SPEC.md): High-level method.
+* [SPEC.md](SPEC.md): Detailed implementation specs.
+
+## Features
+
+- **Scikit-learn compatible**: Inherits `BaseEstimator`/`RegressorMixin`; works with `Pipeline`, `GridSearchCV`, `cross_val_score`, pickling.
+- **Automatic feature handling**: Categorical (one-vs-rest splits), numeric (binary search breakpoints), NaNs/missing values.
+- **Robust statistics**: Wilson means prevent outlier swings.
+- **Configurable weighting**: `weight_falloff` balances local accuracy vs. market normativity.
+- **Explainable**: `explain_value(row)` shows path, weights, means.
+- **Serializable**: `to_json()`, `to_dict()`.
+- **Parallel**: `n_jobs` support.
+
+### NaN Handling
+- **Categorical**: Treated as distinct "NaN" category.
+- **Numeric**: Excluded from splits (robust; per SPEC.md).
+- **Target `y`**: Must be finite (raises `ValueError`).
+- Strict checks: Use `Pipeline([('imputer', SimpleImputer()), ('model', LayeredCompModel())])`.
+
+## Installation
+
+```bash
+pip install layeredcompmodel
+```
+
+For development:
+
+```bash
+git clone https://github.com/JohnKossa/layeredcompmodel.git
+cd layeredcompmodel
+pip install -e .[dev]
+```
+
+## Quickstart
+
+```python
+import pandas as pd
+import numpy as np
+from layeredcompmodel import LayeredCompModel
+
+# Synthetic real-estate-like data
+rng = np.random.default_rng(42)
+n_samples = 100
+data = {
+    'neighborhood': rng.choice(['North', 'South', 'East'], n_samples),
+    'size_sqft': rng.normal(2000, 500, n_samples),
+    'price': rng.normal(500000, 100000, n_samples) + 100 * rng.normal(0, 1, n_samples) * (rng.normal(0, 1, n_samples) * 2000)
+}
+df = pd.DataFrame(data)
+X = df[['neighborhood', 'size_sqft']]
+y = df['price']
+
+# Train
+model = LayeredCompModel(weight_falloff=0.8, n_jobs=1)
+model.fit(X, y)
+
+# Predict
+predictions = model.predict(X)
+print(f"Predictions shape: {predictions.shape}")
+print(f"MAE: {np.mean(np.abs(predictions - y)):.0f}")
+
+# Explain single prediction
+explanation = model.explain_value(X.iloc[0:1].squeeze())
+print(explanation)
+```
+
+## API Reference
+
+### LayeredCompModel(weight_falloff=0.5, split_metric='mae', n_jobs=1)
+
+- `fit(X, y)`: Build tree from features `X` (DataFrame), target `y` (Series).
+- `predict(X)`: Predict using path-weighted means.
+- `explain_value(row)`: Dict with path nodes, depths, weights, wilson_means.
+- `to_json(indent=4)`: JSON tree dump.
+- `tree_`: Root `CompNode` (filter_col, filter_val, wilson_mean, children).
+
+See [docs](https://layeredcompmodel.readthedocs.io) (TBD).
+
+## Examples
+
+See [`examples/quickstart.py`](examples/quickstart.py) for a runnable example (code matches Quickstart above).
+
+**Run it:**
+```bash
+python examples/quickstart.py
+```
+
+**Expected output:**
+```
+Predictions shape: (100,)
+MAE: 126914
+{'final_prediction': 530354.0426294187, 'weight_falloff': 0.8, 'path': [{'depth': 0, 'wilson_mean': 476353.91361128056, 'count': 100, 'is_leaf': False, 'filter_col': 'size_sqft', 'filter_val': 2101.366485546922}, {'depth': 1, 'wilson_mean': 553953.0606894617, 'count': 42, 'is_leaf': False, 'filter_col': 'neighborhood', 'filter_val': 'North'}, {'depth': 2, 'wilson_mean': 525096.3185716979, 'count': 13, 'is_leaf': True}], 'calculation': '0.199*476354 + 0.512*553953 + 0.289*525096 = 530354'}
+```
+
+## Development & Testing
+
+```bash
+pytest tests/ --cov=layeredcompmodel
+black src/
+mypy src/
+```
+
+CI/CD, Sphinx docs: planned.
+
+## Citing
+
+Kossa, J. (2026). LayeredCompModel. GitHub. https://github.com/JohnKossa/layeredcompmodel
+
+## License
+
+[MIT](LICENSE)

layeredcompmodel-0.1.0/SPEC.md

@@ -0,0 +1,76 @@
+# Goal
+
+The goal of the Layered Comp Model is to create a hierarchical prediction system that starts with a general predicted price and refines it by adding information and narrowing the comparison group. This is achieved by building a tree of nodes, each representing a filtered subset of the data, and calculating a weighted average of the Wilson means to produce a final prediction. The model aims to balance accuracy and equity by penalizing large sets and promoting normativity in predictions. The implementation should be a scikit-learn compatible estimator.
+
+More details can be found in MODEL_SPEC.md
+
+# Tech Stack
+
+* pandas
+* python
+* numpy
+* scipy
+* scikit-learn
+
+# Key Processes
+
+## Training
+
+### Accepts
+A pandas dataframe
+
+A target prediction field
+
+A list of columns to use
+
+A list of columns to use
+
+### Produces
+
+A trained scikit-learn compatible model object (e.g., `LayeredCompModel`) with `fit` and `predict` methods.
+
+## Prediction
+
+### Accepts
+A pandas dataframe
+
+A weight_falloff hyperparameter.
+
+### Produces
+
+A "prediction" field decorated on the dataframe and returns it.
+
+# Variable classification
+
+We will need to be able to determine whether a column is numeric or categorical so the correct segmentation test can be applied.
+
+# Segmentation Scoring
+
+Uses a simple linear regression under the hood to fit sale price vs mean and evaluates the split quality by calculating the reduction in Mean Absolute Error (MAE).
+
+1. Calculate the base MAE for the current set of data by fitting a linear regression (sale price vs mean) and calculating the MAE ($MAE_{total}$).
+
+## Categorical
+
+1. For each variant in the categorical (one-vs-rest), treating missing values as a distinct category:
+   1. filter to only that variant, calculate its MAE vs its mean ($MAE_v$), and get its count ($N_v$).
+   2. filter to the inverse of that variant, calculate its MAE vs its mean ($MAE_{inv}$), and get its count ($N_{inv}$).
+   3. Calculate the weighted MAE for the split: $MAE_{weighted} = (MAE_v \times N_v + MAE_{inv} \times N_{inv}) / N_{total}$.
+   4. The segmentation score is the ratio: $Score = MAE_{weighted} / MAE_{total}$.
+2. Find the lowest segmentation score among all variants. In case of ties, choose the variant that splits the count most evenly. If still tied, choose the first one.
+
+## Numeric 
+1. Exclude NaNs from numeric features during this process.
+2. Set num_iterations to minimum of 10 and log2(current population size).
+3. Perform a binary search for an optimal breakpoint:
+   1. Set the initial midpoint to the median of the feature values.
+   2. filter to the entries below the midpoint, calculate its MAE ($MAE_{low}$) and count ($N_{low}$).
+   3. filter to the entries above the midpoint, calculate its MAE ($MAE_{high}$) and count ($N_{high}$).
+   4. Calculate the weighted MAE for the split: $MAE_{weighted} = (MAE_{low} \times N_{low} + MAE_{high} \times N_{high}) / N_{total}$.
+   5. The segmentation score is the ratio: $Score = MAE_{weighted} / MAE_{total}$.
+   6. Move the midpoint to the side that resulted in a better scoring split (lower ratio) and reform the "above" and "below" subsets for each step of the search.
+4. Return the lowest segmentation score and corresponding midpoint found. In case of ties, choose the split that splits the count most evenly. If still tied, choose the first one.
+
+# Node Size Constraints
+
+Minimum node size is 2. Do not attempt to split a node if its size is below this threshold.

layeredcompmodel-0.1.0/examples/quickstart.py

@@ -0,0 +1,28 @@
+import pandas as pd
+import numpy as np
+from layeredcompmodel import LayeredCompModel
+
+# Synthetic real-estate-like data
+rng = np.random.default_rng(42)
+n_samples = 100
+data = {
+    'neighborhood': rng.choice(['North', 'South', 'East'], n_samples),
+    'size_sqft': rng.normal(2000, 500, n_samples),
+    'price': rng.normal(500000, 100000, n_samples) + 100 * rng.normal(0, 1, n_samples) * (rng.normal(0, 1, n_samples) * 2000)
+}
+df = pd.DataFrame(data)
+X = df[['neighborhood', 'size_sqft']]
+y = df['price']
+
+# Train
+model = LayeredCompModel(weight_falloff=0.8, n_jobs=1)
+model.fit(X, y)
+
+# Predict
+predictions = model.predict(X)
+print(f"Predictions shape: {predictions.shape}")
+print(f"MAE: {np.mean(np.abs(predictions - y)):.0f}")
+
+# Explain single prediction
+explanation = model.explain_value(X.iloc[0:1].squeeze())
+print(explanation)