Skip to main content
The spatial module computes descriptive statistics and the Average Nearest Neighbor (ANN) index for each cluster, generates visualisation plots, and exports results in GeoJSON format for use in GIS tools such as QGIS. 
from archeo_cluster.core.spatial import (
    run_spatial_analysis,
    compute_ann_index,
    generate_descriptive_stats,
    export_clusters_to_geojson,
    ImageReference,
)

​
run_spatial_analysis

Run the complete spatial analysis pipeline on a clustered CSV file. This is the primary entry point for the analysis stage. 
from archeo_cluster.core.spatial import run_spatial_analysis

desc_stats, ann_results = run_spatial_analysis(
    csv_path="./clusters/image/image_clustered.csv",
    output_dir="./plots",
)

for ann in ann_results:
    print(f"Cluster {ann.cluster_id}: R={ann.r_index} — {ann.interpretation}")
The function:
  1. Loads the clustered CSV and validates required columns (area, perimeter, cluster, centroid_x, centroid_y).
  2. Computes descriptive statistics and saves descriptive_stats.csv.
  3. Generates boxplots for morphological features and a spatial distribution map.
  4. Computes the ANN index per cluster and saves ann_results.csv and ann_results.png.
​
csv_path
Path | str
required
Path to the clustered CSV file produced by KMeansAnalyzer.process_features_csv. Must contain area, perimeter, cluster, centroid_x, and centroid_y columns.
​
output_dir
Path | str
default:"plots"
Directory for output files. Created automatically if it does not exist.
Returns tuple[list[DescriptiveStats], list[ANNResult]]

​
compute_ann_index

Compute the Average Nearest Neighbor R-index for each cluster in a DataFrame. 
import pandas as pd
from archeo_cluster.core.spatial import compute_ann_index

df = pd.read_csv("./clusters/image/image_clustered.csv")
ann_results = compute_ann_index(df, cluster_col="cluster")
​
df
pd.DataFrame
required
DataFrame containing centroid_x, centroid_y, and a cluster column.
​
cluster_col
str
default:"cluster"
Name of the column holding cluster labels.
Returns list[ANNResult]

​
ANN R-index interpretation

The R-index is the ratio of the observed mean nearest-neighbor distance to the expected mean distance for a random Poisson process at the same density:
R valueInterpretation
R < 0.9Clustered — objects are closer together than expected by chance
0.9 ≤ R ≤ 1.1Random — distribution consistent with a random process
R > 1.1Dispersed — objects are spread further apart than expected
When a cluster has fewer than 2 points, or the study area has zero extent, r_index is None and interpretation is "Insufficient points".

​
generate_descriptive_stats

Generate descriptive statistics for each cluster in a DataFrame. 
from archeo_cluster.core.spatial import generate_descriptive_stats

stats = generate_descriptive_stats(df, cluster_col="cluster")
for s in stats:
    print(f"Cluster {s.cluster_id}: n={s.count}, mean_area={s.area_mean:.1f}")
​
df
pd.DataFrame
required
DataFrame containing area, perimeter, and a cluster column.
​
cluster_col
str
default:"cluster"
Name of the column holding cluster labels.
Returns list[DescriptiveStats]

​
export_clusters_to_geojson

Convenience function that reads a clustered CSV and exports it directly to a GeoJSON file. 
from archeo_cluster.core.spatial import export_clusters_to_geojson, ImageReference

# Export with optional georeferencing
ref = ImageReference(
    origin_x=14.5983,
    origin_y=89.4167,
    pixel_size_x=0.0001,
    pixel_size_y=0.0001,
    crs="EPSG:4326",
)
export_clusters_to_geojson(
    csv_path="./clusters/image/image_clustered.csv",
    output_path="./output.geojson",
    image_reference=ref,
)
​
csv_path
Path | str
required
Path to the input clustered CSV file.
​
output_path
Path | str
required
Destination path for the GeoJSON file.
​
image_reference
ImageReference | None
default:"None"
Optional georeferencing data. When None, pixel coordinates are written directly to the GeoJSON and a warning is logged.
Returns None

​
export_to_geojson

Export an in-memory DataFrame to a GeoJSON file. 
import pandas as pd
from archeo_cluster.core.spatial import export_to_geojson

df = pd.read_csv("./clusters/image/image_clustered.csv")
export_to_geojson(df, output_path="./output.geojson")
​
df
pd.DataFrame
required
DataFrame with centroid_x, centroid_y, and other properties to include as GeoJSON feature attributes.
​
output_path
Path | str
required
Destination path for the GeoJSON file.
​
image_reference
ImageReference | None
default:"None"
Optional georeferencing data.
Returns None

​
Data classes

​
ANNResult

Result of Average Nearest Neighbor analysis for a single cluster.
​
cluster_id
int
required
Zero-based cluster identifier.
​
r_index
float | None
required
The computed R-index value, rounded to 3 decimal places. None when the cluster has fewer than 2 points or the study area has zero extent.
​
interpretation
str
required
Human-readable label: "Clustered", "Random", "Dispersed", or "Insufficient points".

​
DescriptiveStats

Descriptive statistics for objects belonging to a single cluster.
​
cluster_id
int
required
Zero-based cluster identifier.
​
count
int
required
Number of objects in the cluster.
​
area_mean
float
required
Mean object area in pixels.
​
area_std
float
required
Standard deviation of object area. 0.0 when the cluster has only one object.
​
area_min
float
required
Minimum object area in pixels.
​
area_max
float
required
Maximum object area in pixels.
​
perimeter_mean
float
required
Mean object perimeter in pixels.
​
perimeter_std
float
required
Standard deviation of object perimeter. 0.0 when the cluster has only one object.

​
ImageReference

Georeferencing metadata for converting pixel coordinates to a real-world coordinate system. 
from archeo_cluster.core.spatial import ImageReference

ref = ImageReference(
    origin_x=14.5983,
    origin_y=89.4167,
    pixel_size_x=0.0001,
    pixel_size_y=0.0001,
    crs="EPSG:4326",
)
geo_x, geo_y = ref.pixel_to_geo(pixel_x=320, pixel_y=240)
​
origin_x
float
required
X coordinate of the image origin in real-world units.
​
origin_y
float
required
Y coordinate of the image origin in real-world units.
​
pixel_size_x
float
required
Size of one pixel in the X direction (real-world units per pixel).
​
pixel_size_y
float
required
Size of one pixel in the Y direction (real-world units per pixel). The Y axis is inverted during conversion to match the typical image coordinate system.
​
crs
str | None
default:"None"
Coordinate reference system identifier (e.g. "EPSG:4326"). None indicates pixel / local coordinates.

​
pixel_to_geo

Convert a pixel coordinate pair to geographic (or projected) coordinates.
​
pixel_x
float
required
X coordinate in pixels.
​
pixel_y
float
required
Y coordinate in pixels.
Returns tuple[float, float] — (geo_x, geo_y) in the target CRS, or (x, y) in local units when crs is None.

Build docs developers (and LLMs) love

Get started for freeTalk to us