dune-params

dune-params identifies the main geometric parameters of coastal dunes from cross-shore profile datasets:

• dune toe (d_toe_final, z_toe_final)
• dune crest (d_crest, z_crest)
• dune heel / landward dune limit (d_heel_final, z_heel_final)

The package is designed for operational coastal datasets where profiles are stored as GeoDataFrames and dune areas are provided as coastal-structure polygons.

---

Installation

Recommended installation

pybeach==0.1.3 works only in a Python 3.9 environment with scikit-learn==0.24.2. The recommended installation is therefore:

git clone https://github.com/IHCantabria/dune_params.git
cd dune_params

conda env create -f environment-pybeach.yml
conda activate dunes_pybeach

pip install -e ".[pybeach,examples]"

---

Install directly from GitHub

conda create -n dunes_pybeach python=3.9
conda activate dunes_pybeach

pip install "scikit-learn>=0.24.2,<0.25"
pip install "dune-params[pybeach,examples] @ git+https://github.com/IHCantabria/dune_params.git"

Input data

Profiles

Supported profile formats:

• GeoParquet (.parquet)
• GeoPackage (.gpkg)

The profile table must contain, either as arrays or reconstructable from geometry:

Concept	Default column	Notes
profile id	id	Optional but recommended
beach name	Playa	Used for longshore smoothing
profile distance	d	Must increase seaward
elevation	z_corregido	Falls back to z if configured
profile x-coordinates	X	Full array or two endpoints
profile y-coordinates	Y	Full array or two endpoints
geometry	active GeoDataFrame geometry	Profile LineString

Dune polygons

The structures layer is usually a GeoPackage with a class column:

Clase = "Duna"

Only profiles crossing dune polygons are passed to the detector.

---

Detection modes

The main configuration is DuneDetectionConfig.detection_mode:

"ensemble"               # internal topographic ensemble only
"ensemble_with_pybeach"  # internal ensemble + pybeach candidates
"pybeach_only"           # pybeach toe/crest, internal fallback for heel

Recommended operational mode:

detection_mode="ensemble_with_pybeach"

In this mode, pybeach does not replace the internal detector. It contributes additional toe/crest candidates, while the final heel-crest-toe geometry is selected by the physical ensemble score.

The pybeach input profile is lightly smoothed by default:

pybeach_use_smoothed_profile=True
pybeach_smooth_median_window_m=7.0
pybeach_smooth_mean_window_m=17.0

Final elevations are still interpolated from the original/corrected profile, not from the smoothed input.

---

Basic Python usage

from dune_params import DuneDetectionConfig, detect_dune_parameters, save_outputs

config = DuneDetectionConfig(
    detection_mode="ensemble_with_pybeach",
    profile_id_col="id",
    d_col="d",
    z_col="z_corregido",
    x_col="X",
    y_col="Y",
    beach_col="Playa",
    structure_class_col="Clase",
    dune_values=("Duna",),
    search_landward_buffer_m=50.0,
    search_seaward_buffer_m=50.0,
    progress_bars=True,
)

gdf = detect_dune_parameters(
    profiles="examples/data/cantabria/Cantabria_profiles_35m_checked.parquet",
    structures="examples/data/cantabria/defensas_costeras.gpkg",
    config=config,
)

# Inspect and quality-control the returned GeoDataFrame before exporting.
print(gdf[["id", "Playa", "is_dune", "d_toe_final_smooth", "d_crest_smooth", "d_heel_final_smooth", "detection_confidence"]].head())

save_outputs(
    gdf,
    output_dir="outputs_cantabria",
    config=config,
    basename="cantabria_dune_parameters",
    formats=("gpkg", "shp", "parquet", "pkl", "csv"),
    features=("toe", "crest", "heel"),
)

---

Outputs

detect_dune_parameters(...) returns the original profile GeoDataFrame plus columns such as:

is_dune
Y_df_AI_proxy
x_df_AI_proxy, y_df_AI_proxy
d_dune_landward_polygon, d_dune_seaward_polygon
d_toe_final, z_toe_final, d_toe_final_smooth
d_crest, z_crest, d_crest_smooth
d_heel_final, z_heel_final, d_heel_final_smooth
detection_status, detection_confidence
geometry_score, toe_confidence, crest_confidence, heel_confidence
toe_source, crest_source, heel_source
pybeach_enabled, pybeach_available, pybeach_used

save_outputs(...) can export:

• profile table with detection columns: .pkl, .parquet, .csv
• point layers for toe, crest and heel: Shapefile and/or GeoPackage

---

Example notebook

See:

examples/notebooks/01_cantabria_dune_parameter_identification.ipynb

The notebook loads the Cantabria example, runs the detector, shows the quality-control columns, plots a few cross-shore profiles with the detected toe/crest/heel, draws a plan-view map for one beach (optionally with basemap), and saves toe, crest and heel point layers.

---

Quick plotting helpers

The package also exposes two lightweight plotting helpers, useful for notebooks and quality control:

from dune_params import plot_profile_detections, plot_planview_map

# profile QC plots
figs = plot_profile_detections(gdf, config=config, n_profiles=4)

# plan-view map for one beach
fig, ax = plot_planview_map(
    gdf,
    structures=structures_path,
    config=config,
    beach="Somo",
    basemap=True,
)

plot_planview_map will use contextily when available; if it is not installed, the figure is still produced without a basemap.