sgspy 1.0.2__cp311-cp311-manylinux_2_28_x86_64.whl

sgspy/sample/systematic/systematic.py

@@ -0,0 +1,233 @@
+# ******************************************************************************
+#
+#  Project: sgs
+#  Purpose: simple random sampling (srs)
+#  Author: Joseph Meyer
+#  Date: June, 2025
+#
+# ******************************************************************************
+
+##
+# @defgroup user_systematic systematic
+# @ingroup user_sample
+
+import os
+import sys
+import site
+from typing import Optional
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+from sgspy.utils import (
+    SpatialRaster,
+    SpatialVector,
+    plot,
+)
+
+#ensure _sgs binary can be found
+site_packages = list(filter(lambda x : 'site-packages' in x, site.getsitepackages()))[0]
+sys.path.append(os.path.join(site_packages, "sgspy"))
+sys.path.append(os.path.join(os.path.dirname(__file__), ".."))
+from _sgs import systematic_cpp
+
+##
+# @ingroup user_systematic
+# This function conducts systematic sampling within the extent of
+# the raster given. The 'cellsize' parameter specifies the grid size,
+# the 'shape' parameter specifies the grid shape, and the 'location' 
+# parameter specifies where in the grid a sample should fall into.
+# 
+# shape can be one of 'square', and 'hexagon'.
+# location can be one of 'corners', 'centers', 'random'.
+# 
+# An access vector of LineString or MultiLineString type can be provided.
+# buff_outer specifies the buffer distance around the geometry which is
+# allowed to be included in the sampling, buff_inner specifies the geometry
+# which is not allowed to be included in the sampling. buff_outer must
+# be larger than buff_inner. For a multi-layer vector, layer_name
+# must be provided.
+# 
+# A vector containing existing sample points can be provided. If this is
+# the case then all of the points in the existing sample are automatically
+# added and random samples are then chosen as required until num_samples 
+# number of samples are chosen.
+# 
+# If the force parameter is True, then the the samples are forced to 
+# fall on an index which is NOT a no data value. This may result
+# in some grids not being sampled.
+# 
+# Examples
+# --------------------
+# rast = sgspy.SpatialRaster("raster.tif") @n
+# samples = sgspy.sample.systematic(rast, 500, "hexagon", "centers")
+# 
+# rast = sgspy.SpatialRaster("raster.tif") @n
+# samples = sgspy.sample.systematic(rast, 500, "square", "corners", plot=True, filename="systematic_samples.shp")
+# 
+# rast = sgspy.SpatialRaster("raster.tif") @n
+# samples = sgspy.sample.systematic(rast, 500, "hexagon", "random", force=True)
+# 
+# rast = sgspy.SpatialRaster("raster.tif") @n
+# access = sgspy.SpatialVector("access_network.shp") @n
+# samples = sgspy.sample.systematic(rast, 500, "hexagon", "corners", access=access, buff_outer=300)
+# 
+# rast = sgspy.SpatialRaster("raster.tif") @n
+# access = sgspy.SpatialVector("existing_samples.shp") @n
+# samples = sgspy.sample.systematic(rast, 500, "hexagon", "corners", existing=existing)
+# 
+# Parameters
+# --------------------
+# rast : SpatialRaster @n
+#     the raster to be sampled @n @n
+# cellsize : float @n
+#     the size of the grid cells to be sampled @n @n
+# shape : str @n
+#     the shape of the grid cells to be sampled @n @n
+# location : str @n
+#     the location within the grid cell to be sampled @n @n
+# existing (optional) : SpatialVector @n
+#     a vector specifying existing sample points @n @n
+# access (optional) : SpatialVector @n
+#     a vector specifying access network @n @n
+# layer_name (optional) : str @n
+#     the layer within access that is to be used for sampling @n @n
+# buff_inner (optional) : int | float @n
+#     buffer boundary specifying distance from access which CANNOT be sampled @n @n
+# buff_outer (optional) : int | float @n
+#     buffer boundary specifying distance from access which CAN be sampled @n @n
+# force : bool @n
+#     True if samples are not allowed to fall on a nodata pixel @n @n
+# plot : bool @n
+#     whether or not to plot the resulting samples @n @n
+# filename : str @n
+#     the filename to write to or "" if not to write @n @n
+# 
+# Returns
+# --------------------
+# a SpatialVector object containing point geometries of sample locations
+def systematic(
+    rast: SpatialRaster,
+    cellsize: int | float,
+    shape: str = "square",
+    location: str = "centers",
+    existing: Optional[SpatialVector] = None,
+    access: Optional[SpatialVector] = None,
+    layer_name: Optional[str] = None,
+    buff_inner: Optional[int | float] = None,
+    buff_outer: Optional[int | float] = None,
+    force: bool = False,
+    plot: bool = False,
+    filename: str = ""):
+        
+    if type(rast) is not SpatialRaster:
+        raise TypeError("'rast' parameter must be of type sgspy.SpatialRaster.")
+
+    if type(cellsize) not in [int, float]:
+        raise TypeError("'cellsize' parameter must be of type int or float.")
+
+    if type(shape) is not str:
+        raise TypeError("'shape' paramter must be of type str.")
+
+    if type(location) is not str:
+        raise TypeError("'location' parameter must be of type str.")
+
+    if existing is not None and type(existing) is not SpatialVector:
+        raise TypeError("'existing' parameter, if given, must be of type sgspy.SpatialVector.")
+
+    if access is not None and type(access) is not SpatialVector:
+        raise TypeError("'access' parameter, if given, must be of type sgspy.SpatialVector.")
+
+    if layer_name is not None and type(layer_name) is not str:
+        raise TypeError("'layer_name' parameter, if given, must be of type str.")
+
+    if buff_inner is not None and type(buff_inner) not in [int, float]:
+        raise TypeError("'buff_inner' parameter, if given, must be of type int or float.")
+
+    if buff_outer is not None and type(buff_outer) not in [int, float]:
+        raise TypeError("'buff_outer' parameter, if given, must be of type int or float.")
+
+    if type(force) is not bool:
+        raise TypeError("'force' parameter must be of type bool.")
+
+    if type(plot) is not bool:
+        raise TypeError("'plot' parameter must be of type bool.")
+
+    if type(filename) is not str:
+        raise TypeError("'filename' parameter must be of type str.")
+
+    if rast.closed:
+        raise RuntimeError("the C++ object which the raster object wraps has been cleaned up and closed.")
+
+    if cellsize <= 0:
+        raise ValueError("cellsize must be greater than 0")
+
+    if shape not in ["square", "hexagon"]:
+        raise ValueError("shape parameter must be one of 'square', 'hexagon'")
+
+    if location not in ["centers", "corners", "random"]:
+        raise ValueError("location parameter must be one of 'centers', 'corners', 'random'")
+
+    if (access):
+        if layer_name is None:
+            if len(access.layers) > 1:
+                raise ValueError("if there are multiple layers in the access vector, layer_name parameter must be passed.")
+            layer_name = access.layers[0]
+
+        if layer_name not in access.layers:
+            raise ValueError("layer specified by 'layer_name' does not exist in the access vector")
+
+        if buff_inner is None or buff_inner < 0:
+            buff_inner = 0
+
+        if buff_outer is None or buff_outer < 0:
+            raise ValueError("if an access vector is given, buff_outer must be a float greater than 0.")
+
+        if buff_inner >= buff_outer:
+            raise ValueError("buff_outer must be greater than buff_inner")
+
+        access_vector = access.cpp_vector
+    else:
+        access_vector = None
+        layer_name = ""
+        buff_inner = -1
+        buff_outer = -1
+
+    if (existing):
+        existing_vector = existing.cpp_vector
+    else:
+        existing_vector = None
+
+    [samples, points, grid] = systematic_cpp(
+        rast.cpp_raster,
+        cellsize,
+        shape,
+        location,
+        existing_vector,
+        access_vector,
+        layer_name,
+        buff_inner,
+        buff_outer,
+        force,
+        plot,
+        filename
+    )
+
+    #plot new vector if requested
+    if plot:
+        fig, ax = plt.subplots()
+        ax.set_xlim([rast.xmin, rast.xmax])
+        ax.set_ylim([rast.ymin, rast.ymax])
+        rast.plot(ax, band=rast.bands[0])
+        title="samples on " + rast.bands[0]
+        
+        #plot grid
+        for shape in grid:
+            ax.plot(shape[0], shape[1], '-k')
+
+        #plot sample points
+        ax.plot(points[0], points[1], '.r')
+        ax.set_title(label=title)
+        plt.show()
+
+    return SpatialVector(samples)

sgspy/stratify/__init__.py

@@ -0,0 +1,27 @@
+##
+# @defgroup user_stratify stratify
+# @ingroup user
+#
+# Documentation for the stratification functions. 
+
+from . import (
+    breaks,
+    kmeans,
+    poly,
+    quantiles,
+    map,
+)
+
+from .breaks import breaks
+from .kmeans import kmeans
+from .poly import poly
+from .quantiles import quantiles
+from .map import map
+
+__all__ = [
+    "breaks",
+    "kmeans",
+    "poly",
+    "quantiles",
+    "map",
+]

sgspy/stratify/breaks/__init__.py

@@ -0,0 +1,2 @@
+from . import breaks
+from .breaks import breaks

sgspy/stratify/breaks/breaks.py

@@ -0,0 +1,222 @@
+# ******************************************************************************
+#
+#  Project: sgs
+#  Purpose: simple random sampling (srs)
+#  Author: Joseph Meyer
+#  Date: June, 2025
+#
+# ******************************************************************************
+
+##
+# @defgroup user_breaks breaks
+# @ingroup user_stratify
+
+import os
+import sys
+import site
+import tempfile
+import numpy as np
+from sgspy.utils import SpatialRaster
+
+#ensure _sgs binary can be found
+site_packages = list(filter(lambda x : 'site-packages' in x, site.getsitepackages()))[0]
+sys.path.append(os.path.join(site_packages, "sgspy"))
+sys.path.append(os.path.join(os.path.dirname(__file__), ".."))
+from _sgs import breaks_cpp
+
+GIGABYTE = 1073741824
+
+##
+# @ingroup user_breaks
+# This function conducts stratification on the raster given
+# according to the user defined breaks.
+# 
+# The breaks may be defined as a single list of ints or floats
+# in the case of a raster with a single band. Or, they may be defined
+# as a list of ints or floats where the index indicates the raster band.
+# Or, they may be defined as a dict where the (str) key represents
+# the raster band and the value is a list of ints or floats.
+# 
+# if the map parameter is given, an extra output band will be used which combines
+# all stratifications from the previous bands used. A single value in the mapped
+# output band corresponds to a single combination of values from the previous
+# bands.
+# 
+# the filename parameter specifies an output file name. Right now the only file format
+# excepted is GTiff (.tif).
+# 
+# the thread_count parameter specifies the number of threads which this function will 
+# utilize in the case where the raster is large and may not fit in memory. If the full
+# raster can fit in memory and does not need to be processed in blocks, this argument
+# will be ignored. The default is 8 threads, although the optimal number will depend significantly
+# on the hardware being used and my be less or more than 8.
+# 
+# The driver_options parameter is used to specify creation options for a the output raster.
+# See options for the Gtiff driver here: https://gdal.org/en/stable/drivers/raster/gtiff.html#creation-options
+# The keys in the driver_options dict must be strings, the values are converted to string.
+# The options must be valid for the driver corresponding to the filename, and if filename is not given
+# they must be valid for the GTiff format, as that is the format used to store temporary raster files.
+# Note that if this parameter is given, but filename is not and the raster fits entirely in memory, the
+# driver_options parameter will be ignored.
+# 
+# Examples
+# --------------------
+# rast = sgspy.SpatialRaster("multi_band_rast.tif") @n
+# srast = sgspy.stratify.breaks(rast, breaks={"band_name1": [3, 5, 11, 18]})
+# 
+# rast = sgspy.SpatialRaster("single_band_rast.tif") @n
+# srast = sgspy.stratify.breaks(rast, breaks=[20, 40, 60, 80], filename="breaks.tif", driver_options={"COMPRESS", "LZW"}))
+# 
+# rast = sgspy.SpatialRaster("multi_band_rast.tif") @n
+# srast = sgspy.stratify.breaks(rast, breaks={"band_name1": [3, 5, 11, 10], "band_name2": [20, 40, 60, 80]}, map=True)
+# 
+# rast = sgspy.SpatialRaster("multi_band_rast.tif") @n
+# srast = sgspy.stratify.breaks(rast, breaks=[[3, 5, 11, 18], [40, 60, 80], [2, 5]])
+# 
+# Parameters
+# --------------------
+# rast : SpatialRaster @n
+#     raster data structure containing the raster to stratify @n @n
+# breaks :  list[float | list[float]] | dict[str, list[float]], @n
+#     user defined breaks to stratify @n @n
+# map : bool @n
+#     whether to map the stratification of multiple raster bands onto a single band @n @n
+# filename : str @n
+#     filename to write to or '' if no file should be written @n @n
+# thread_count : int @n
+#     the number of threads to use when multithreading large images @n @n
+# driver_options : dict[] @n
+#     the creation options as defined by GDAL which will be passed when creating output files @n @n
+# 
+# Returns
+# --------------------
+# a SpatialRaster object containing stratified raster bands.
+def breaks(
+    rast: SpatialRaster,
+    breaks: list[float | list[float]] | dict[str, list[float]],
+    map: bool = False,
+    filename: str = '',
+    thread_count: int = 8,
+    driver_options: dict = None
+    ):
+
+    MAX_STRATA_VAL = 2147483647 #maximum value stored within a 32-bit signed integer to ensure no overflow
+    
+    if type(rast) is not SpatialRaster:
+        raise TypeError("'rast' parameter must be of type sgspy.SpatialRaster")
+
+    if type(breaks) not in [list, dict]:
+        raise TypeError("'breaks' parameter must be of type list or dict.")
+
+    if type(map) is not bool:
+        raise TypeError("'map' parameter must be of type bool.")
+
+    if type(filename) is not str:
+        raise TypeError("'filename' parameter must be of type str.")
+
+    if type(thread_count) is not int:
+        raise TypeError("'thread_count' parameter must be of type int.")
+
+    if driver_options is not None and type(driver_options) is not dict:
+        raise TypeError("'driver_options' parameter, if givne, must be of type dict.")
+
+    if rast.closed:
+            raise RuntimeError("the C++ object which the raster object wraps has been cleaned up and closed.")
+
+    breaks_dict = {}
+    large_raster = False
+    temp_folder = ""
+
+    if type(breaks) is list and len(breaks) < 1:
+        raise ValueError("breaks list must contain at least one element.")
+
+    if type(breaks) is list and type(breaks[0]) is list:
+        #error check number of rasters bands
+        if len(breaks) != rast.band_count:
+            raise ValueError("number of lists of breaks must be equal to the number of raster bands.")
+
+        for i in range(len(breaks)):
+            breaks_dict[i] = breaks[i]
+
+    elif type(breaks) is list and type(breaks[0]) in [int, float]:
+        #error check number of raster bands
+        if rast.band_count != 1:
+            raise ValueError("if breaks is a single list, raster must have a single band (has {}).".format(rast.band_count))
+
+        breaks_dict[0] = breaks
+
+    elif type(breaks) is list:
+        raise TypeError("if 'breaks' parameter is of type list, it must be filled with with values of type list, int, or float.")
+
+    else: #breaks is a dict
+        for key, val in breaks.items():
+            if type(key) is not str:
+                raise TypeError("if 'breaks' parameter is a dict, all keys must be of type str.")
+            if type(val) is not list:
+                raise TypeError("if 'breaks' parameter is a dict, all values in the key values pairs must be of type list[float].")
+            if key not in rast.bands:
+                raise ValueError("breaks dict key must be a valid band name (see SpatialRaster.bands for list of names)")
+            
+            breaks_dict[rast.band_name_dict[key]] = val
+
+    #error check max value for potential overflow error
+    max_mapped_strata = int(map)
+    for _, val in breaks_dict.items():
+        strata_count = len(val) + 1
+        if strata_count > MAX_STRATA_VAL:
+            raise ValueError("one of the breaks given will cause an integer overflow error because the max strata number is too large.")
+
+        max_mapped_strata = max_mapped_strata * strata_count
+
+    if max_mapped_strata > MAX_STRATA_VAL:
+        raise ValueError("the mapped strata will cause an overflow error because the max strata number is too large.")    
+
+    if thread_count < 1:
+        raise ValueError("number of threads can't be less than 1.")
+
+    #ensure driver options keys are string, and convert driver options vals to string
+    driver_options_str = {}
+    if driver_options:
+        for (key, val) in driver_options.items():
+            if type(key) is not str:
+                raise ValueError("the key for all key/value pairs in the driver_options dict must be a string.")
+            driver_options_str[key] = str(val)
+
+    raster_size_bytes = 0
+    height = rast.height
+    width = rast.width
+    for key, _ in breaks_dict.items():
+        pixel_size = rast.cpp_raster.get_raster_band_type_size(key)
+        band_size = height * width * pixel_size
+        raster_size_bytes += band_size
+        if band_size >= GIGABYTE:
+            large_raster = True
+            break
+
+    #if large_raster is true, the C++ function will process the raster in blocks
+    large_raster = large_raster or (raster_size_bytes > GIGABYTE * 4)
+
+    #make a temp directory which will be deleted if there is any problem when calling the cpp function
+    temp_dir = tempfile.mkdtemp()
+    rast.have_temp_dir = True
+    rast.temp_dir = temp_dir
+
+    #call stratify breaks function
+    srast = SpatialRaster(breaks_cpp(
+        rast.cpp_raster, 
+        breaks_dict, 
+        map, 
+        filename,
+        large_raster,
+        thread_count,
+        temp_dir,
+        driver_options_str
+    ))
+
+    #now that it's created, give the cpp raster object ownership of the temporary directory
+    rast.have_temp_dir = False
+    srast.cpp_raster.set_temp_dir(temp_dir)
+    srast.temp_dataset = filename == "" and large_raster
+    srast.filename = filename
+
+    return srast

sgspy/stratify/kmeans/__init__.py

@@ -0,0 +1,2 @@
+from . import kmeans
+from .kmeans import kmeans

sgspy/stratify/kmeans/kmeans.py

@@ -0,0 +1,3 @@
+def kmeans():
+    print(__file__)
+    raise NotImplementedError

sgspy/stratify/map/__init__.py

@@ -0,0 +1,2 @@
+from . import map_stratifications
+from .map_stratifications import map