soil-aggregation-tool 0.1.0__py3-none-any.whl

soil_aggregation_tool/__init__.py

@@ -0,0 +1,12 @@
+"""Aggregate SWAT soil classes and reclassify matching soil rasters."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .core import AggregationResult, aggregate_soils
+
+try:
+    __version__ = version("soil-aggregation-tool")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["AggregationResult", "aggregate_soils"]

soil_aggregation_tool/__main__.py

@@ -0,0 +1,6 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()
+

soil_aggregation_tool/cli.py

@@ -0,0 +1,112 @@
+"""Command-line interface for the soil aggregation tool."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from .core import aggregate_soils
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Aggregate a SWAT usersoil CSV and reclassify its soil raster."
+    )
+    parser.add_argument(
+        "--usersoil",
+        help="Path to the input SWAT usersoil CSV.",
+    )
+    parser.add_argument(
+        "--raster",
+        help="Path to the input soil GeoTIFF whose values match MUID.",
+    )
+    parser.add_argument(
+        "--output-dir",
+        help="Directory for the aggregated usersoil, raster, and lookup table.",
+    )
+    parser.add_argument(
+        "--max-optimal-clusters",
+        type=int,
+        default=15,
+        help="Maximum k tested per stratum (default: 15).",
+    )
+    parser.add_argument(
+        "--seed",
+        type=int,
+        default=123,
+        help="Random seed for k-means (default: 123).",
+    )
+    parser.add_argument(
+        "--ignore-raster-values",
+        type=int,
+        nargs="*",
+        default=[0, 65535],
+        metavar="VALUE",
+        help="Raster values treated as background/no-data (default: 0 65535).",
+    )
+    return parser
+
+
+def prompt_for_path(label: str, *, must_exist: bool) -> Path:
+    """Prompt for a path without displaying a bracketed default value."""
+
+    while True:
+        entered_path = input(f"{label}: ").strip().strip('"')
+        if not entered_path:
+            print("A path is required.")
+            continue
+
+        path = Path(entered_path)
+        if must_exist and not path.is_file():
+            print(f"File not found: {path}")
+            continue
+        return path
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not sys.stdin.isatty() and not (
+        args.usersoil and args.raster and args.output_dir
+    ):
+        parser.error(
+            "--usersoil, --raster and --output-dir are required when "
+            "input is not interactive."
+        )
+
+    usersoil_path = args.usersoil or prompt_for_path(
+        "Usersoil CSV path",
+        must_exist=True,
+    )
+    raster_path = args.raster or prompt_for_path(
+        "Soil raster path",
+        must_exist=True,
+    )
+    output_dir = args.output_dir or prompt_for_path(
+        "Output folder path",
+        must_exist=False,
+    )
+
+    result = aggregate_soils(
+        usersoil_path=usersoil_path,
+        raster_path=raster_path,
+        output_dir=output_dir,
+        max_optimal_clusters=args.max_optimal_clusters,
+        seed=args.seed,
+        ignore_raster_values=args.ignore_raster_values,
+    )
+
+    if result.missing_raster_muids:
+        print(
+            f"{len(result.missing_raster_muids)} raster MUID values were not found "
+            "in the usersoil CSV; those cells were written as 0."
+        )
+
+    print(f"Raster unique soil IDs: {result.raster_muid_count}")
+    print(f"Matched input soils: {result.matched_soil_count}")
+    print(f"Aggregated soil count: {result.aggregated_soil_count}")
+    print(f"Usersoil: {result.usersoil_path}")
+    print(f"Raster: {result.raster_path}")
+    print(f"Lookup: {result.lookup_path}")

soil_aggregation_tool/core.py

@@ -0,0 +1,396 @@
+"""Core soil-reduction workflow."""
+
+from __future__ import annotations
+
+import os
+import warnings
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+# Silences a joblib warning and traceback on Windows machines where the number
+# of physical CPU cores cannot be detected. A user-set value is kept.
+os.environ.setdefault("LOKY_MAX_CPU_COUNT", "4")
+
+import numpy as np
+import pandas as pd
+import rasterio
+from sklearn.cluster import KMeans
+from sklearn.metrics import silhouette_score
+from sklearn.preprocessing import StandardScaler
+
+
+CLUSTER_COLS = ["SOL_K1", "SOL_AWC1", "SOL_BD1", "USLE_K1"]
+STRATA_COLS = ["HYDGRP", "TEXTURE", "SOL_ZMX", "NLAYERS"]
+REQUIRED_COLS = {"MUID", "SNAM", *CLUSTER_COLS, *STRATA_COLS}
+
+
+@dataclass(frozen=True)
+class AggregationResult:
+    """Paths and summary counts produced by an aggregation run."""
+
+    usersoil_path: Path
+    raster_path: Path
+    lookup_path: Path
+    raster_muid_count: int
+    matched_soil_count: int
+    aggregated_soil_count: int
+    missing_raster_muids: tuple[int, ...]
+
+
+def _unlocked_path(path: Path) -> Path:
+    if not path.exists():
+        return path
+
+    try:
+        with path.open("a"):
+            return path
+    except PermissionError:
+        stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        new_path = path.with_name(f"{path.stem}_{stamp}{path.suffix}")
+        warnings.warn(
+            f"{path} is locked by another program; writing {new_path.name} instead.",
+            stacklevel=2,
+        )
+        return new_path
+
+
+def _write_csv(df: pd.DataFrame, path: Path) -> Path:
+    output_path = _unlocked_path(path)
+    df.to_csv(output_path, index=False)
+    return output_path
+
+
+def _read_raster_area_by_muid(
+    raster_path: Path,
+    ignore_values: tuple[int, ...],
+) -> pd.DataFrame:
+    with rasterio.open(raster_path) as src:
+        if src.count != 1:
+            raise ValueError("The input soil raster must contain exactly one band.")
+
+        values = src.read(1, masked=True).compressed()
+        if np.issubdtype(values.dtype, np.floating):
+            values = values[~np.isnan(values)]
+
+        values = values.astype(np.int64)
+        if ignore_values:
+            values = values[
+                ~np.isin(values, np.asarray(ignore_values, dtype=np.int64))
+            ]
+        if values.size == 0:
+            raise ValueError("The soil raster contains no usable MUID values.")
+
+        unique_values, cell_counts = np.unique(values, return_counts=True)
+        pixel_area = abs(src.transform.a * src.transform.e)
+
+    return pd.DataFrame(
+        {
+            "MUID": unique_values.astype(np.int64),
+            "raster_cell_count": cell_counts.astype(np.int64),
+            "raster_area": cell_counts.astype(float) * pixel_area,
+        }
+    )
+
+
+def _fix_layer_count(df: pd.DataFrame) -> pd.DataFrame:
+    layer_depth_cols = [f"SOL_Z{i}" for i in range(1, 11)]
+    if not all(col in df.columns for col in layer_depth_cols):
+        return df
+
+    positive_layer_count = (
+        df[layer_depth_cols].apply(pd.to_numeric, errors="coerce") > 0
+    ).sum(axis=1)
+    current_layer_count = pd.to_numeric(df["NLAYERS"], errors="coerce")
+    bad = current_layer_count != positive_layer_count
+    if bad.any():
+        df.loc[bad, "NLAYERS"] = positive_layer_count.loc[bad].astype(int)
+    return df
+
+
+def _build_cluster_keys(df: pd.DataFrame) -> pd.DataFrame:
+    features = df[CLUSTER_COLS].apply(pd.to_numeric, errors="coerce")
+    if features.isna().any().any():
+        bad_cols = features.columns[features.isna().any()].tolist()
+        raise ValueError(
+            "Cluster columns contain non-numeric or missing values: "
+            f"{bad_cols}"
+        )
+
+    features["SOL_K1"] = np.log10(
+        np.maximum(features["SOL_K1"].to_numpy(), 0.001)
+    )
+    return features
+
+
+def _choose_clusters(
+    x_scaled: np.ndarray,
+    max_optimal_clusters: int,
+    seed: int,
+) -> np.ndarray:
+    """Return 1-based cluster labels for the k with the best silhouette score."""
+
+    sample_count = x_scaled.shape[0]
+    unique_point_count = np.unique(x_scaled, axis=0).shape[0]
+    maximum_k = min(
+        max_optimal_clusters,
+        sample_count - 1,
+        unique_point_count,
+    )
+    best_labels = np.ones(sample_count, dtype=int)
+    if maximum_k < 2:
+        return best_labels
+
+    best_score = -np.inf
+    for cluster_count in range(2, maximum_k + 1):
+        model = KMeans(
+            n_clusters=cluster_count,
+            n_init=20,
+            max_iter=100,
+            random_state=seed,
+        )
+        labels = model.fit_predict(x_scaled)
+        if len(np.unique(labels)) < 2:
+            continue
+
+        score = silhouette_score(x_scaled, labels)
+        if score > best_score:
+            best_labels = labels + 1
+            best_score = score
+
+    return best_labels
+
+
+def _cluster_study_soils(
+    study_soils: pd.DataFrame,
+    cluster_keys: pd.DataFrame,
+    max_optimal_clusters: int,
+    seed: int,
+) -> pd.DataFrame:
+    clustered = study_soils.copy()
+    clustered["_stratum"] = clustered[STRATA_COLS].astype(str).agg(
+        "__".join,
+        axis=1,
+    )
+    clustered["_cluster_global"] = np.nan
+    next_cluster_id = 1
+
+    for indices in clustered.groupby("_stratum", sort=True).groups.values():
+        indices = list(indices)
+        features = cluster_keys.loc[indices].copy()
+        variable_columns = features.std(axis=0, ddof=0) > 0
+
+        if len(indices) < 3 or not variable_columns.any():
+            local_clusters = np.ones(len(indices), dtype=int)
+        else:
+            scaled = StandardScaler().fit_transform(
+                features.loc[:, variable_columns]
+            )
+            local_clusters = _choose_clusters(
+                scaled,
+                max_optimal_clusters=max_optimal_clusters,
+                seed=seed,
+            )
+
+        local_to_global: dict[int, int] = {}
+        for local_id in sorted(np.unique(local_clusters)):
+            local_to_global[int(local_id)] = next_cluster_id
+            next_cluster_id += 1
+
+        clustered.loc[indices, "_cluster_global"] = [
+            local_to_global[int(local_id)] for local_id in local_clusters
+        ]
+
+    clustered["_cluster_global"] = clustered["_cluster_global"].astype(int)
+    return clustered
+
+
+def _weighted_mode(values: pd.Series, weights: pd.Series):
+    weighted_counts = weights.groupby(values).sum().sort_values(ascending=False)
+    if weighted_counts.empty:
+        return values.iloc[0]
+    return weighted_counts.index[0]
+
+
+def _aggregate_cluster(
+    group: pd.DataFrame,
+    new_muid: int,
+    original_columns: list[str],
+) -> pd.Series:
+    output = group.iloc[0][original_columns].copy()
+    weights = group["raster_area"].astype(float)
+    if weights.sum() <= 0:
+        weights = group["raster_cell_count"].astype(float)
+
+    for column in original_columns:
+        if pd.api.types.is_numeric_dtype(group[column]):
+            output[column] = group[column].mean()
+        else:
+            output[column] = _weighted_mode(group[column], weights)
+
+    output["MUID"] = new_muid
+    if "SEQN" in output.index:
+        output["SEQN"] = new_muid
+    if "OBJECTID" in output.index:
+        output["OBJECTID"] = new_muid
+    output["SNAM"] = f"Soil_{new_muid}"
+    if "S5ID" in output.index:
+        output["S5ID"] = 0
+    if "CMPPCT" in output.index:
+        output["CMPPCT"] = 100
+    return output
+
+
+def _make_reduced_and_mapping(
+    study_soils: pd.DataFrame,
+    original_columns: list[str],
+) -> tuple[pd.DataFrame, pd.DataFrame]:
+    reduced_rows: list[pd.Series] = []
+    mapping_rows: list[pd.DataFrame] = []
+
+    groups = study_soils.groupby("_cluster_global", sort=True)
+    for new_muid, (_, group) in enumerate(groups, start=1):
+        reduced_rows.append(
+            _aggregate_cluster(group, new_muid, original_columns)
+        )
+        mapping_rows.append(
+            pd.DataFrame(
+                {
+                    "old_muid": group["MUID"].to_numpy(),
+                    "new_muid": new_muid,
+                }
+            )
+        )
+
+    reduced = pd.DataFrame(reduced_rows, columns=original_columns)
+    mapping = pd.concat(mapping_rows, ignore_index=True)
+    return reduced, mapping
+
+
+def _reclassify_raster(
+    input_raster: Path,
+    output_raster: Path,
+    mapping: pd.DataFrame,
+    ignore_values: tuple[int, ...],
+) -> Path:
+    order = np.argsort(mapping["old_muid"].to_numpy(dtype=np.int64))
+    old_muids = mapping["old_muid"].to_numpy(dtype=np.int64)[order]
+    new_muids = mapping["new_muid"].to_numpy(dtype=np.int32)[order]
+
+    with rasterio.open(input_raster) as src:
+        profile = src.profile.copy()
+        input_values = src.read(1)
+        output_values = np.zeros(input_values.shape, dtype=np.int32)
+
+        valid_mask = np.ones(input_values.shape, dtype=bool)
+        if np.issubdtype(input_values.dtype, np.floating):
+            valid_mask &= ~np.isnan(input_values)
+        if src.nodata is not None:
+            valid_mask &= input_values != src.nodata
+        if ignore_values:
+            valid_mask &= ~np.isin(
+                input_values.astype(np.int64),
+                np.asarray(ignore_values, dtype=np.int64),
+            )
+
+        # Vectorized lookup: MUIDs absent from the mapping are written as 0.
+        old_values = input_values[valid_mask].astype(np.int64)
+        positions = np.searchsorted(old_muids, old_values)
+        positions = np.clip(positions, 0, old_muids.size - 1)
+        found = old_muids[positions] == old_values
+        output_values[valid_mask] = np.where(found, new_muids[positions], 0)
+        profile.update(dtype=rasterio.int32, nodata=0, compress="lzw")
+
+        actual_output_path = _unlocked_path(output_raster)
+        with rasterio.open(actual_output_path, "w", **profile) as dst:
+            dst.write(output_values, 1)
+
+    return actual_output_path
+
+
+def aggregate_soils(
+    usersoil_path: str | Path,
+    raster_path: str | Path,
+    output_dir: str | Path,
+    *,
+    max_optimal_clusters: int = 15,
+    seed: int = 123,
+    ignore_raster_values: list[int] | tuple[int, ...] = (0, 65535),
+) -> AggregationResult:
+    """Aggregate a usersoil table and reclassify its matching soil raster."""
+
+    usersoil_path = Path(usersoil_path)
+    raster_path = Path(raster_path)
+    output_dir = Path(output_dir)
+
+    if not usersoil_path.is_file():
+        raise FileNotFoundError(f"Usersoil CSV not found: {usersoil_path}")
+    if not raster_path.is_file():
+        raise FileNotFoundError(f"Soil raster not found: {raster_path}")
+    if max_optimal_clusters < 1:
+        raise ValueError("max_optimal_clusters must be at least 1.")
+
+    ignored_values = tuple(int(value) for value in ignore_raster_values)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    usersoil = pd.read_csv(usersoil_path)
+    missing_columns = sorted(REQUIRED_COLS.difference(usersoil.columns))
+    if missing_columns:
+        raise ValueError(
+            f"Usersoil CSV is missing required columns: {missing_columns}"
+        )
+    original_columns = usersoil.columns.tolist()
+
+    numeric_muids = pd.to_numeric(usersoil["MUID"], errors="coerce")
+    if numeric_muids.isna().any():
+        raise ValueError("The usersoil MUID column must contain only integers.")
+    usersoil["MUID"] = numeric_muids.astype(np.int64)
+
+    raster_area = _read_raster_area_by_muid(raster_path, ignored_values)
+    raster_muids = set(raster_area["MUID"].astype(int).tolist())
+    usersoil_muids = set(usersoil["MUID"].astype(int).tolist())
+    missing_raster_muids = tuple(sorted(raster_muids.difference(usersoil_muids)))
+
+    study_soils = usersoil[usersoil["MUID"].isin(raster_muids)].copy()
+    if study_soils.empty:
+        raise ValueError("No raster MUID values matched the usersoil CSV.")
+
+    study_soils = study_soils.merge(raster_area, on="MUID", how="left")
+    if study_soils["raster_cell_count"].isna().any():
+        raise ValueError("Some matched MUIDs did not receive raster area weights.")
+
+    study_soils = _fix_layer_count(study_soils)
+    cluster_keys = _build_cluster_keys(study_soils)
+    clustered = _cluster_study_soils(
+        study_soils,
+        cluster_keys,
+        max_optimal_clusters=max_optimal_clusters,
+        seed=seed,
+    )
+    reduced, mapping = _make_reduced_and_mapping(clustered, original_columns)
+    lookup = reduced[["MUID", "SNAM"]].copy()
+
+    usersoil_output = _write_csv(
+        reduced,
+        output_dir / "Soil_usersoil.csv",
+    )
+    lookup_output = _write_csv(
+        lookup,
+        output_dir / "Soil_lookup.csv",
+    )
+    raster_output = _reclassify_raster(
+        raster_path,
+        output_dir / "Soil.tif",
+        mapping,
+        ignored_values,
+    )
+
+    return AggregationResult(
+        usersoil_path=usersoil_output.resolve(),
+        raster_path=raster_output.resolve(),
+        lookup_path=lookup_output.resolve(),
+        raster_muid_count=len(raster_muids),
+        matched_soil_count=len(study_soils),
+        aggregated_soil_count=len(reduced),
+        missing_raster_muids=missing_raster_muids,
+    )

soil_aggregation_tool-0.1.0.dist-info/METADATA

@@ -0,0 +1,368 @@
+Metadata-Version: 2.4
+Name: soil-aggregation-tool
+Version: 0.1.0
+Summary: Aggregate SWAT usersoil classes and reclassify a matching soil raster.
+Author: Yashas Kumar
+Maintainer-email: Chandan Kumar <chandankr014@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/chandankr014/swatplus-soil-aggregation-tool
+Project-URL: Issues, https://github.com/chandankr014/swatplus-soil-aggregation-tool/issues
+Keywords: SWAT,SWAT+,soil,hydrology,raster,clustering
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: rasterio>=1.3
+Requires-Dist: scikit-learn>=1.3
+Dynamic: license-file
+
+# Soil Aggregation Tool
+
+`Soil_aggregation_tool` is an installable Python package for aggregating SWAT
+usersoil classes and reclassifying a matching soil raster. It groups comparable
+soils, selects an appropriate number of k-means clusters, and produces a smaller
+usersoil table, a matching raster, and a two-column lookup table.
+
+Developed by Yashas Kumar. Packaged and maintained by
+[chandankr014](https://github.com/chandankr014).
+
+## Outputs
+
+Each run creates exactly these three files:
+
+| Output file | Contents |
+| --- | --- |
+| `Soil_usersoil.csv` | Aggregated usersoil table with the same columns as the input usersoil CSV. |
+| `Soil_lookup.csv` | Lookup containing only `MUID` and `SNAM`, copied from `Soil_usersoil.csv`. |
+| `Soil.tif` | Input soil raster reclassified to the new aggregated MUID values. |
+
+Generated soil names are `Soil_1`, `Soil_2`, `Soil_3`, and so on. Therefore,
+the `MUID` and `SNAM` pairs in `Soil_lookup.csv` always match those in
+`Soil_usersoil.csv`.
+
+The program does not delete unrelated files already present in the output
+folder. For a folder containing only these three files, use a new or empty
+output folder.
+
+## How the tool works
+
+1. It reads the unique MUID values and cell areas from the input soil raster.
+2. It selects usersoil rows whose `MUID` values occur in that raster.
+3. It divides the selected soils into comparable strata using `HYDGRP`,
+   `TEXTURE`, `SOL_ZMX`, and `NLAYERS`.
+4. Within each stratum, it clusters soils using `SOL_K1`, `SOL_AWC1`,
+   `SOL_BD1`, and `USLE_K1`.
+5. It compares candidate cluster counts using the silhouette score.
+6. It aggregates each selected cluster into one usersoil row and assigns new
+   sequential MUIDs beginning with `1`.
+7. It reclassifies the raster from the original MUID values to the new MUIDs.
+8. It copies `MUID` and `SNAM` from the output usersoil into the lookup file.
+
+## Input requirements
+
+### Usersoil CSV
+
+The input CSV must contain these columns:
+
+| Column | Use |
+| --- | --- |
+| `MUID` | Soil identifier corresponding to raster cell values. |
+| `SNAM` | Soil name. Output names are replaced with `Soil_1`, `Soil_2`, etc. |
+| `HYDGRP` | Hydrologic soil group used to define strata. |
+| `TEXTURE` | Soil texture used to define strata. |
+| `SOL_ZMX` | Maximum soil depth used to define strata. |
+| `NLAYERS` | Number of soil layers used to define strata. |
+| `SOL_K1` | Layer-one saturated hydraulic conductivity used for clustering. |
+| `SOL_AWC1` | Layer-one available water capacity used for clustering. |
+| `SOL_BD1` | Layer-one bulk density used for clustering. |
+| `USLE_K1` | Layer-one soil erodibility factor used for clustering. |
+
+All other input usersoil columns are retained in `Soil_usersoil.csv`. If the
+input includes every column from `SOL_Z1` through `SOL_Z10`, the tool corrects
+an inconsistent `NLAYERS` value from the number of positive layer depths.
+
+### Soil raster
+
+The raster must:
+
+- be a single-band GeoTIFF;
+- contain cell values corresponding to `MUID` values in the usersoil CSV; and
+- contain valid raster dimensions, transform, and coordinate-system metadata.
+
+Values `0` and `65535` are treated as background or no-data by default. Raster
+MUIDs that do not occur in the usersoil CSV are written as `0` in `Soil.tif`
+and reported in the terminal.
+
+## Software requirements
+
+- Python 3.10 or newer
+- NumPy
+- pandas
+- Rasterio
+- scikit-learn
+
+Python installs the package dependencies from `pyproject.toml`.
+
+## Download and install from GitHub
+
+First, install Git and Python 3.10 or newer. Then follow these steps.
+
+### 1. Download the repository
+
+Open PowerShell or a terminal and run:
+
+```powershell
+git clone https://github.com/chandankr014/swatplus-soil-aggregation-tool.git
+```
+
+### 2. Enter the downloaded folder
+
+```powershell
+cd swatplus-soil-aggregation-tool
+```
+
+### 3. Create a virtual environment
+
+```powershell
+python -m venv .venv
+```
+
+Activate it on Windows PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+On macOS or Linux, activate it with:
+
+```bash
+source .venv/bin/activate
+```
+
+### 4. Install the package
+
+```powershell
+python -m pip install .
+```
+
+The required Python packages are installed automatically. Confirm that the
+installation succeeded:
+
+```powershell
+soil-aggregation-tool --help
+```
+
+### Install directly without cloning
+
+The package can also be installed directly from GitHub:
+
+```powershell
+python -m pip install "git+https://github.com/chandankr014/swatplus-soil-aggregation-tool.git"
+```
+
+### Install in Jupyter Notebook
+
+Run this command in a notebook cell to install the package into the environment
+used by the current notebook kernel:
+
+```python
+%pip install "git+https://github.com/chandankr014/swatplus-soil-aggregation-tool.git"
+```
+
+Restart the notebook kernel after installation. The Python API can then be used
+directly in another cell:
+
+```python
+from soil_aggregation_tool import aggregate_soils
+
+result = aggregate_soils(
+    usersoil_path="usersoil.csv",
+    raster_path="soil_input.tif",
+    output_dir="soil_output",
+)
+
+print(result.usersoil_path)
+print(result.lookup_path)
+print(result.raster_path)
+```
+
+## Running with interactive input
+
+Run the command without file arguments:
+
+```powershell
+soil-aggregation-tool
+```
+
+The program asks for the inputs as follows:
+
+```text
+Usersoil CSV path:
+Soil raster path:
+Output folder path:
+```
+
+Enter a complete or relative path after each prompt. The prompts do not use
+default filenames or square brackets.
+
+Example:
+
+```text
+Usersoil CSV path: D:\data\usersoil.csv
+Soil raster path: D:\data\soil_input.tif
+Output folder path: D:\data\soil_output
+```
+
+## Running with command-line arguments
+
+File paths can be supplied directly to avoid interactive prompts:
+
+```powershell
+soil-aggregation-tool `
+  --usersoil "D:\data\usersoil.csv" `
+  --raster "D:\data\soil_input.tif" `
+  --output-dir "D:\data\soil_output"
+```
+
+The Python module form is equivalent:
+
+```powershell
+python -m soil_aggregation_tool `
+  --usersoil "D:\data\usersoil.csv" `
+  --raster "D:\data\soil_input.tif" `
+  --output-dir "D:\data\soil_output"
+```
+
+Paths are quoted so paths containing spaces work correctly. The output folder
+is created automatically when it does not exist.
+
+### Optional settings
+
+| Argument | Default | Description |
+| --- | ---: | --- |
+| `--max-optimal-clusters` | `15` | Maximum number of clusters evaluated within each soil stratum. |
+| `--seed` | `123` | Random seed that makes k-means results reproducible. |
+| `--ignore-raster-values` | `0 65535` | Space-separated raster values treated as background. |
+
+Example using `0` and `-9999` as ignored values:
+
+```powershell
+soil-aggregation-tool `
+  --usersoil "D:\data\usersoil.csv" `
+  --raster "D:\data\soil_input.tif" `
+  --output-dir "D:\data\soil_output" `
+  --ignore-raster-values 0 -9999
+```
+
+## Using the package from Python
+
+```python
+from soil_aggregation_tool import aggregate_soils
+
+result = aggregate_soils(
+    usersoil_path="usersoil.csv",
+    raster_path="soil_input.tif",
+    output_dir="soil_output",
+)
+
+print(result.usersoil_path)
+print(result.lookup_path)
+print(result.raster_path)
+print(result.aggregated_soil_count)
+```
+
+## Running the tests
+
+Run the automated test from the repository folder:
+
+```powershell
+python -m unittest discover -s tests -v
+```
+
+The tests create a small usersoil CSV and GeoTIFF, run the complete workflow,
+and check that:
+
+- only the three documented output files are created;
+- `Soil_lookup.csv` has only the `MUID` and `SNAM` columns;
+- lookup values exactly match `Soil_usersoil.csv`;
+- the new MUID values are written into `Soil.tif`;
+- raster MUIDs missing from the usersoil CSV are written as `0`; and
+- a missing required column raises a clear error.
+
+The same tests run in GitHub Actions before each release is published.
+
+## Publishing a release to PyPI
+
+Pushing a tag that starts with `v` runs `.github/workflows/publish.yml`, which
+tests, builds, and uploads the package to PyPI. The package version is taken
+from the tag, so there is no version number to edit by hand.
+
+One-time setup: create a PyPI API token and add it on GitHub under
+**Settings → Secrets and variables → Actions** as `PYPI_API_TOKEN`.
+
+To release a new version:
+
+```powershell
+git add .
+git commit -m "Release v0.1.0"
+git push origin main
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Check progress in the repository's **Actions** tab. After it finishes, install
+with:
+
+```powershell
+pip install --no-cache-dir soil-aggregation-tool
+```
+
+## License
+
+Released under the MIT License. See [LICENSE](LICENSE).
+
+## Repository structure
+
+```text
+Soil_aggregation_tool/
+|-- .github/
+|   `-- workflows/
+|       `-- publish.yml
+|-- .gitignore
+|-- LICENSE
+|-- README.md
+|-- pyproject.toml
+|-- src/
+|   `-- soil_aggregation_tool/
+|       |-- __init__.py
+|       |-- __main__.py
+|       |-- cli.py
+|       `-- core.py
+`-- tests/
+    `-- test_aggregation.py
+```
+
+Large CSV and TIFF datasets are excluded by `.gitignore`. Keep input data
+outside the repository, or check that it is not staged before committing.
+
+## Common errors
+
+- **Usersoil CSV not found:** check the path entered at `Usersoil CSV path` or
+  supplied to `--usersoil`.
+- **Soil raster not found:** check the path entered at `Soil raster path` or
+  supplied to `--raster`.
+- **Missing required columns:** add or rename the columns listed in the usersoil
+  input section.
+- **No raster MUID values matched:** confirm that raster cell values and the
+  usersoil `MUID` column use the same identifiers.
+- **Output file is open:** close the file in other software and run the tool
+  again. When an output is locked, the tool warns and uses a timestamped
+  filename rather than overwriting the open file.
+- **Arguments are required when input is not interactive:** when running from
+  a script or scheduled job, pass `--usersoil`, `--raster`, and `--output-dir`.

soil_aggregation_tool-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+soil_aggregation_tool/__init__.py,sha256=k6dC6QRhOxAsPXdiT7SaN9kUikDuqJujZd8I7tbV734,352
+soil_aggregation_tool/__main__.py,sha256=14FfnaF7zY550dRxcOV5XinMWDf5fRBJZkgTBoqeVj8,63
+soil_aggregation_tool/cli.py,sha256=hsLHBqyjtKhF9L2DP2wcieow7emIIaDC6nBaGEJzG_w,3320
+soil_aggregation_tool/core.py,sha256=4-GUHP9cM66g5Aru7AyOgvX-BLL9Dz8c-w6LaBlVnDk,13059
+soil_aggregation_tool-0.1.0.dist-info/licenses/LICENSE,sha256=H6QFaHy6sKBIVk65VwwNQIupZJ_oUPmYqCDBtS2QYek,1087
+soil_aggregation_tool-0.1.0.dist-info/METADATA,sha256=YDsjhvr_ComjnaGQolBJIkQnjUCqX2Jw4_om2MqEYq0,10793
+soil_aggregation_tool-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+soil_aggregation_tool-0.1.0.dist-info/entry_points.txt,sha256=-E9Es9NNie9FI3Htr8cueNEs99lRdbyJ7RNKrkPGef8,73
+soil_aggregation_tool-0.1.0.dist-info/top_level.txt,sha256=TLiLDFMwe4cWnd2Mn0ZQPT5MZ61LBjlSckXcqN7mZCk,22
+soil_aggregation_tool-0.1.0.dist-info/RECORD,,

soil_aggregation_tool-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

soil_aggregation_tool-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+soil-aggregation-tool = soil_aggregation_tool.cli:main

soil_aggregation_tool-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yashas Kumar and Chandan Kumar
+
+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.

soil_aggregation_tool-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+soil_aggregation_tool