Metadata-Version: 2.4
Name: stsckm
Version: 1.0.1
Summary: Spatially constrained spatio-temporal K-means clustering
Author-email: Muh Akbar Idris <muhakbaridris@apps.ipb.ac.id>
License-Expression: MIT
Project-URL: Homepage, https://github.com/muhakbaridris/ST-SCKM
Project-URL: Documentation, https://github.com/muhakbaridris/ST-SCKM/tree/main/docs
Project-URL: Repository, https://github.com/muhakbaridris/ST-SCKM
Project-URL: Issues, https://github.com/muhakbaridris/ST-SCKM/issues
Project-URL: Publication, https://doi.org/10.1016/j.jnlssr.2026.100357
Keywords: clustering,spatial statistics,spatio-temporal,geospatial,machine learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scikit-learn>=1.3
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == "plot"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-cov>=5; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: furo>=2024.1.29; extra == "docs"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: matplotlib>=3.7; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: sphinx>=7; extra == "dev"
Requires-Dist: furo>=2024.1.29; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# stsckm

`stsckm` is a Python implementation of spatio-temporal spatially constrained
K-means (ST-SCKM) for point-event data. It combines weighted spatial and
temporal squared distances with a soft label-disagreement penalty on a spatial
K-nearest-neighbor graph.

The package implements the method associated with:

> Idris, M. A., Aidi, M. N., and Djuraidah, A. (2026). Performance Evaluation
> of ST-DBSCAN and Spatio-Temporal Spatially Constrained K-Means (ST-SCKM) for
> Wildfire Risk Zoning and Resilience Analysis. *Journal of Safety Science and
> Resilience*. <https://doi.org/10.1016/j.jnlssr.2026.100357>

## Scope

The estimator is intended for aligned spatial and temporal numeric matrices.
The KNN penalty encourages neighboring observations to share labels but does
not guarantee that every cluster is a single connected component. Context
variables such as event intensity can be retained for post hoc profiling
without entering the clustering objective.

## Installation

Install the published package from PyPI:

```bash
python -m pip install stsckm
```

Optional plotting support can be installed with:

```bash
python -m pip install "stsckm[plot]"
```

For development, testing, and documentation from a source checkout:

```bash
python -m pip install -e ".[dev]"
```

## Quick start

```python
import numpy as np

from stsckm import (
    STSCKM,
    add_default_features,
    evaluate_labels,
    load_sample_wildfire,
    standardize_features,
)

frame = add_default_features(load_sample_wildfire())
X_spatial, spatial_scaler = standardize_features(
    frame, ["x_proj", "y_proj"]
)
X_temporal, temporal_scaler = standardize_features(
    frame, ["time_days"]
)

model = STSCKM(
    n_clusters=4,
    spatial_weight=0.5,
    temporal_weight=1.5,
    lambda_spatial=1.0,
    n_neighbors=5,
    random_state=42,
)
labels = model.fit_predict(X_spatial, X_temporal)

metrics = evaluate_labels(
    np.column_stack([X_spatial, X_temporal]),
    labels,
)
print(model.n_iter_)
print(metrics)
```

## Main API

- `STSCKM.fit(X_spatial, X_temporal)`
- `STSCKM.fit_predict(X_spatial, X_temporal)`
- `weighted_spatiotemporal_distance(...)`
- `knn_indices(...)`
- `evaluate_labels(...)`
- `neighbor_disagreement(...)`
- `assign_risk_labels(...)`
- `load_sample_wildfire()`

The estimator follows scikit-learn parameter conventions and inherits from
`BaseEstimator` and `ClusterMixin`. The current release intentionally does not expose
out-of-sample `predict()`: defining neighbors for new points requires a
separate modeling choice.

## Reproduction

Run all manuscript-scale numerical results and figures with one command:

```bash
python replication/run_all.py
```

The script writes its outputs to `replication/output/` and checks the
sensitivity table against `replication/expected/sensitivity.csv`.

## Tests and build

```bash
python -m pytest
python -m build
python -m twine check dist/*
```

## License

MIT. This is a GPL-compatible free-software license.

## Author

Muh Akbar Idris<br>
IPB University<br>
ORCID: <https://orcid.org/0009-0000-2995-1975>
