[FEAT] Add Predictive Modelling module

[fabiofelix]

💡 Feature Request

Welcome to the UrbanMapper feature request hub! 🎉

Hey there, before you jump in, take a quick sec to check out the
important stuff below—it’ll help us keep the magic flowing smoothly.

Important

Before you proceed, please confirm the following:

• I’ve checked the API docs and confirmed this feature doesn’t already exist (no duplicates, please!).
• I’ve scoured the existing issues to make sure this hasn’t been requested before.
• I get that feature requests are reviewed periodically and might take a little time—patience is key!

---

Describe the Feature Request

Add a module in which a user can run basic prediction tasks, such as clustering, classification, or regression.

1. With a small configuration effort, the library should run predefined models
2. Tasks like regression should use specific model implementations related to spatial distribution
   2.1 For datasets that have only latitude/longitude information, it could use libraries like pykriging
   2.2 For datasets with geometry (polygons, lines, etc.), it could use libraries like spreg from PySAL
   2.3 For other purposes, it could use scikit-learn, PyTorch, etc.
3. Other types of models that do not have a single output or need for data transformation should have a specialized class.
   3.1 Creation of a 3D mash
   3.2 Generate a heatmap

Describe Preferred Solution

Describe Alternatives

Related Code

There is a new branch feat/add_model

Additional Context

If the feature request is approved, would you be willing to submit a PR?

• Yes
• No

(No worries if you’re new to this—we’ll guide you every step of the way! 🤝)

[simonprovost]

So so cool feature @fabiofelix ! May I suggest that this is an optional module via uv add urban-mapper[ml] or pip install urban-mapper[ml], so that it does not overweight the package with default installation if people won't work with ML downstream tasks following a urban mapper pipeline analysis?

Sklearn, Pytorch can be quite heavy :) Much better to be installed only and only if you've got the wish to work with ML in downstream tasks.

Cheers!

[fabiofelix]

Scikit-learn is already a dependency, and PyTorch is only necessary if a user wants to implement a customized model with it.

[simonprovost]

I appreciate the quick response (see #79 based on your response)! Meanwhile, I briefly walked-through the code and look forward to this PR! It’s likely the largest enhancement to UM in a while ✅ Let me share some thoughts. I could be mistaken, so feel free to correct me.

1. with_model(.) seems to handle multiple scenarios simultaneously, which should be avoided for UX and long-term maintenance. Instead, chaining methods like with_classifier(<primitive of interest>), with_regressor(<primitive of interest>), and with_clusterer(<primitive of interest>) might be more efficient, transparent, and less opaque – for every1ne.

2. I am also wondering if perhaps we should not support with_pipeline(<sklearn_pipeline>) instead of building it out "internally" following a with_transform(.).with_classifier(.). To think even beyond, we can have only (1) with_sklearn_pipeline(.), (2) with_imblearn_pipeline(.) and (3) for Neural Nets via Pytorch: with_skorch_pipeline(.). This way it stays very pragmatic, simple & easy to maintain, as well as retroactively supports all ML stages' primitives. As a result of that we then do not need all the with_classifier, with_regressor, etc.

💡 View examples here (classifier, regression, imbalanced-learn & skorch)

scikit-learn (classification)

from sklearn.pipeline import Pipeline
# ... other imports ...

clf_pipeline = Pipeline(steps=[
    ("impute", SimpleImputer()),
    ("scale", StandardScaler()),
    ("model", LogisticRegression(max_iter=1000)),
])

model = (
    mapper
    .model
    .with_sklearn_pipeline(clf_pipeline)
    .with_columns(target_column="churned")
    .with_data(validation_size=0.2, stratify=True)
    .build()
)

scikit-learn (regression)

from sklearn.pipeline import Pipeline
# ... other imports ...

regression_pipeline = Pipeline(steps=[
    ("impute", SimpleImputer()),
    ("scale", StandardScaler()),
    ("model", Ridge(alpha=1.0)),
])

model = (
    mapper
    .model
    .with_sklearn_pipeline(regression_pipeline)
    .with_columns(target_column="sum_amount")
    .with_data(validation_size=0.1)
    .build()
)

---

imbalanced-learn (classification with SMOTE)

from imblearn.pipeline import Pipeline
# ... other imports ...

imb_clf_pipeline = Pipeline(steps=[
    ("impute", SimpleImputer()),
    ("scale", StandardScaler()),
    ("smote", SMOTE(random_state=42)),
    ("clf", LogisticRegression(max_iter=1000)),
])

model = (
    mapper
    .model
    .with_imblearn_pipeline(imb_clf_pipeline)
    .with_columns(target_column="churned")
    .with_data(validation_size=0.2, stratify=True)
    .build()
)

---

skorch (PyTorch wrapped in sklearn API)

from torch import nn
from skorch import NeuralNetClassifier
from sklearn.pipeline import Pipeline
# ... other imports ...

net = NeuralNetClassifier(
    module=MLP,
    module__n_features=50,
    module__n_classes=2,
    max_epochs=20,
    lr=1e-3,
    optimizer=torch.optim.Adam,
    batch_size=128,
    iterator_train__shuffle=True,
    device="cpu",
)

skorch_clf_pipeline = Pipeline(steps=[
    ("impute", SimpleImputer()),
    ("scale", StandardScaler()),
    ("net", net),
])

model = (
    mapper
    .model
    .with_skorch_pipeline(skorch_clf_pipeline)
    .with_columns(target_column="churned")
    .with_data(validation_size=0.2, stratify=True)
    .build()
)

Additionaly, to solve (1) and (2) from original description. These are not in the main core with the idea proposed above (i.e. with_pipeline_…) but in the mixins as specific use cases that behind uses with_pipeline_…. We cover non-skilled ML users and ML users very well in this direction.

Your thoughts @fabiofelix ?

[simonprovost]

Have you had the chance to read this above @fabiofelix ? What's your thoughts?

[simonprovost]

@fabiofelix Just changed the title as model only was confusing me all the time I am opening the issues tab. Feel free to change to something else for more accuracy if needed! cheers.