sgspy 1.0.2__cp312-cp312-manylinux_2_28_x86_64.whl

sgspy/stratify/quantiles/quantiles.py

@@ -0,0 +1,276 @@
+# ******************************************************************************
+#
+#  Project: sgs
+#  Purpose: stratification by user defined quantiles
+#  Author: Joseph Meyer
+#  Date: September, 2025
+#
+# ******************************************************************************
+
+##
+# @defgroup user_quantiles quantiles
+# @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 quantiles_cpp
+
+GIGABYTE = 1073741824
+
+##
+# @ingroup user_quantiles
+# This function conducts stratification on the raster given by generating quantile
+# probabilities according to the 'num_strata' argument given by the user.
+# 
+# The quantiles may be defined as an integer, indicating the number of quantiles
+# of equal size. Quantiles may also be defined as a list of probabilities between 0
+# and 1. In the case of a raster with a single band, the quantiles may be passed directly
+# to the num_strata argument as either type: int | list[float].
+# 
+# In the case of a multi-band raster image, the specific bands can be specified by the index
+# of a list containing an equal number of quantiles as bands (list[int | list[float]). 
+# 
+# If not all raster bands should be stratified, specific bands can be selected in 
+# the form of a dict where the key is the name of a raster band and the value is the 
+# quantiles (dict[str, int | list[float]).
+# 
+# if the map parameter is given, an extra output band will be used which combines
+# all stratifications from the bands used into an extra outpu band. A single
+# value in the mapped output band corresponds to a combination a single combination
+# of values from the previous bands.
+# 
+# The thread_count parameter specifies the number of threads which this function 
+# will utilize the 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 may be more or less
+# than 8.
+# 
+# the driver_options parameter is used to specify creation options for 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.
+# 
+# the eps parameter is used only if batch processing is used to calculate the quantiles
+# for a raster. Quantile streaming algorithms cannot be perfectly accurate, as this
+# would necessitate having the entire raster in memory at once. A good approximation
+# can be made, and the error is controlled by this epsilon (eps) value.
+# The Quantile streaming method is the method introduced by  Zhang et al. and utilized by MKL:
+#     https://web.cs.ucla.edu/~weiwang/paper/SSDBM07_2.pdf
+#     https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-summary-statistics-notes/2021-1/computing-quantiles-with-vsl-ss-method-squants-zw.html
+# 
+# Examples
+# --------------------
+# rast = sgspy.SpatialRaster('rast.tif') @n
+# srast = sgspy.stratify.quantiles(rast, num_strata=5)
+# 
+# rast = sgspy.SpatialRaster('rast.tif') @n
+# srast = sgspy.stratify.quantiles(rast, num_strata=[.1, .2, .3, .5, .7], filename="srast.tif")
+# 
+# rast = sgspy.SpatialRaster('multi_band_rast.tif') @n
+# srast = sgspy.stratify.quantiles(rast, num_strata=[5, 5, [.5, .75]], map=True)
+# 
+# rast = sgspy.SpatialRaster('multi_band_rast.tif') @n
+# srast = sgspy.stratify.quantiles(rast, num_strata={'zq90': 5})
+# 
+# Parameters
+# --------------------
+# rast : SpatialRaster @n
+#     raster data structure containing the raster to stratify @n @n
+# num_strata : int | list[float] | list[int|list[float]] | dict[str,int|list[float]] @n
+#     specification of the quantiles to stratify @n @n
+# map : bool @n
+#     whether to map the stratifiction 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
+# eps : float @n
+#     the epsilon value, controlling the error of stream-processed quantiles @n @n
+# 
+# Returns
+# --------------------
+# a SpatialRaster object containing stratified raster bands.
+def quantiles(
+    rast: SpatialRaster,
+    num_strata: int | list[float] | list[int|list[float]] | dict[str,int|list[float]],
+    map: bool = False,
+    filename: str = '',
+    thread_count: int = 8,
+    driver_options: dict = None,
+    eps: float = .001):
+    
+    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(num_strata) not in [int, list, dict]:
+        raise TypeError("'num_strata' parameter must be of type int, 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 type(eps) is not float:
+        raise TypeError("'eps' parameter must be of type float.")
+
+    if rast.closed:
+            raise RuntimeError("the C++ object which the raster object wraps has been cleaned up and closed.")
+
+    if type(num_strata) is list and len(num_strata) < 1:
+        raise ValueError("num_strata list must contain at least one element")
+
+    probabilities_dict = {}
+    if type(num_strata) is int:
+        #error check number of raster bands
+        if rast.band_count != 1:
+            raise ValueError("num_strata int is for a single rast band, but the raster has {}".format(rast.band_count))
+
+        #add quantiles to probabilities_dict
+        inc = 1 / num_strata
+        probabilities_dict[0] = np.array(range(1, num_strata)) / num_strata
+
+    elif type(num_strata) is list and type(num_strata[0]) is float:
+        #error check number of raster bands
+        if rast.band_count != 1:
+            raise ValueError("num_strata list[float] type is for a single raster band, but the raster has {}".format(rast.band_count))
+
+        #error check list values
+        if min(num_strata) < 0:
+            raise ValueError("list[float] must not contain a value less than 0")
+        elif max(num_strata) > 1:
+            raise ValueError("list[float] must not contain a value greater than 1")
+
+        #add quantiles to probabilities_dict and ensure 1 and 0 are removed
+        probabilities_dict[0] = num_strata
+        if 0.0 in probabilities_dict[0]:
+            probabilities_dict[0].remove(0.0)
+        if 1.0 in probabilities_dict[0]:
+            probabilities_dict[0].remove(1.0)
+
+    elif type(num_strata) is list:
+        #error checking number of raster bands
+        if (len(num_strata)) != rast.band_count:
+            raise ValueError("number of lists in num_strata must be equal to the number of raster bands.")
+
+        #for each given num_strata, add it to probabilities_dict depending on type
+        for i in range(len(num_strata)):
+            if type(num_strata[i]) is int:
+                inc = 1 / num_strata[i]
+                probabilities_dict[i] = np.array(range(1, num_strata[i])) / num_strata[i]
+            else: #list of float
+                #for lists, error check max and min values
+                if min(num_strata[i]) < 0:
+                    raise ValueError("list[float] must not contain value less than 0")
+                elif max(num_strata[i]) > 1:
+                    raise ValueError("list[float] must not contain value greater than 1")
+                probabilities_dict[i] = num_strata[i]
+                if 0.0 in probabilities_dict[i]:
+                    probabilities_dict[i].remove(0.0)
+                if 1.0 in probabilities_dict[i]:
+                    probabilities_dict[i].remove(1.0)
+
+    else: #type dict
+        for key, val in num_strata.items():
+            if key not in rast.bands:
+                raise ValueError("probabilities dict key must be valid band name (see SpatialRaster.bands for list of names)")
+            else:
+                band_num = rast.band_name_dict[key]
+                if type(val) is int:
+                    inc = 1 / val
+                    probabilities_dict[band_num] = np.array(range(1, val)) / val
+                else: #list of float
+                    #for lists, error check max and min values
+                    if min(val) < 0:
+                        raise ValueError("list[float] must not contain value less than 0")
+                    elif max(val) > 1:
+                        raise ValueError("list[float] must not contain value greater than 1")
+                    probabilities_dict[band_num] = val
+                    if 0.0 in probabilities_dict[band_num]:
+                        probabilities_dict[band_num].remove(0.0)
+                    if 1.0 in probabilities_dict[band_num]:
+                        probabilities_dict[band_num].remove(1.0)
+
+    #error check max value for potential overflow error
+    max_mapped_strata = int(map)
+    for _, val in probabilities_dict.items():
+        strata_count = len(val) + 1
+        if strata_count > MAX_STRATA_VAL:
+            raise ValueError("one of the quantiles 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.")
+
+    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)
+
+    large_raster = False
+    raster_size_bytes = 0
+    height = rast.height
+    width = rast.width
+    for key, _ in probabilities_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 quantiles function
+    srast = SpatialRaster(quantiles_cpp(
+        rast.cpp_raster, 
+        probabilities_dict, 
+        map, 
+        filename,
+        temp_dir,
+        large_raster,
+        thread_count,
+        driver_options_str,
+        eps
+    ))
+
+    #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/utils/__init__.py

@@ -0,0 +1,18 @@
+##
+# @defgroup user_utils utils
+# @ingroup user
+#
+# Explanations of both the SpatialRaster and SpatialVector classes.
+
+from . import (
+    raster,
+    vector,
+)
+
+from .raster import SpatialRaster
+from .vector import SpatialVector
+
+__all__ = [
+    "SpatialRaster",
+    "spatialVector",
+]

sgspy/utils/plot.py

@@ -0,0 +1,143 @@
+# ******************************************************************************
+#
+#  Project: sgs
+#  Purpose: Plotting rasters and vectors with matplotlib.pyplot
+#  Author: Joseph Meyer
+#  Date: June, 2025
+#
+# ******************************************************************************
+
+from typing import Optional
+
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib #for typing matplotlib.axes.Axes
+
+def plot_raster(raster, 
+                ax: matplotlib.axes.Axes, 
+                target_width: int = 1000, 
+                target_height: int = 1000, 
+                band: Optional[int | str] = None, 
+                **kwargs):
+    """
+    Plots the specified bands using matplotlib.pyplot.imshow function.
+
+    Parameters
+    --------------------
+    raster : SpatialRaster
+        raster to plot
+    ax : matplotlib axis
+        the axis to plot the image on
+    target_width : int
+        maximum width in pixels for the image (after downsampling)
+    target_height : int
+        maximum height in pxeils for the image (after downsampling)
+    band (optional) : int or str
+        specification of which band to plot
+    **kwargs (optional)
+        any parameters which may be passed to matplotlib.pyplot.imshow
+    """
+    #get bands argument as list of int
+    if band is None:
+        if raster.band_count > 1:
+            raise ValueError("'band' argument must be given if raster contains more than one band.")
+        band = 0
+    else:
+        band = raster.get_band_index(band)
+    title = raster.bands[band]
+    
+    #calculate downsampled resolution and get downsampled raster
+    #for info on downsample resolution calculation:
+    #https://gdal.org/en/stable/api/gdaldataset_cpp.html#classGDALDataset_1ae66e21b09000133a0f4d99baabf7a0ec
+    target_downscaling_factor = min(raster.width / target_width, raster.height / target_height)
+    if (target_downscaling_factor <= 2 / 1.2):
+        downsampled_width = raster.width
+        downsampled_height = raster.height
+    elif (target_downscaling_factor <= 4 / 1.2):
+        downsampled_width = int(raster.width / 2)
+        downsampled_height = int(raster.height / 2)
+    elif (target_downscaling_factor <= 8 / 1.2):
+        downsampled_width = int(raster.width / 4)
+        downsampled_height = int(raster.height / 4)
+    else:
+        downsampled_width = int(raster.width / 8)
+        downsampled_height = int(raster.height / 8)
+
+    #get the raster data from the cpp object as a numpy array, and ensure no data is nan
+    no_data_val = raster.cpp_raster.get_band_nodata_value(band)
+    arr = np.asarray(
+        raster.cpp_raster.get_raster_as_memoryview(downsampled_width, downsampled_height, band),
+        copy=False
+    ).astype(np.float64, copy=True)
+    arr[arr == no_data_val] = np.nan
+
+    #get raster origin and raster extent
+    extent = (raster.xmin, raster.xmax, raster.ymin, raster.ymax) #(left, right, top, bottom)
+
+    #add image to matplotlib
+    plt.title(label=title)
+    ax.imshow(arr, origin='upper', extent=extent, **kwargs)
+
+def plot_vector(vector, 
+                ax: matplotlib.axes.Axes, 
+                geomtype: str, 
+                layer: Optional[int | str] = None, 
+                **kwargs):
+    """
+    Plots the specified layer using matplotlib.pyplot.plot.
+    The parameter give by geomtype must be one of:
+    'Point', 'MultiPoint', 'LineString', 'MultiLineString'.
+
+    The layer must contain only geometries of type Point and
+    MultiPoint in the case where 'Point' or 'MultiPoint is given,
+    or geometries of type LineString and MultiLineString 
+    in the case where 'LineString' or 'MultiLineString' is given.
+
+    Parameters
+    --------------------
+    vector : SpatialVector
+        vector to plot
+    ax : matplotlib axis
+        the axis to plot the image on
+    geomtype : str
+        geometry type of the layer
+    layer : None | int | str
+        layer to plot
+    **kwargs (optional)
+        any parameter which may be passed to matplotlib.pyplot.plot
+
+    Raises
+    --------------------
+    ValueError:
+        if no layer was specified, and the image contains more than one layer
+    ValueError:
+        if geomtype is not one of 'Point', 'MultiPoint', 'LineString', 'MultiLineString'
+    RuntimeError (from C++):
+        if the layer contains a geometry NOT of an acceptable type
+    """
+
+    if type(layer) == str:
+        layer_name = layer
+    elif type(layer) == int:
+        layer_name = vector.layers[layer]
+    elif len(vector.layers) == 1: #layer is None
+        layer_name = vector.layers[0]
+    else:
+        ValueError("no layer was specified, and there is more than one layer in the vector. Specify a layer to plot.");
+    
+    if geomtype == "Point" or geomtype == "MultiPoint":
+        points = vector.cpp_vector.get_points(layer_name)
+        if 'fmt' in kwargs:
+             ax.plot(points[0], points[1], **kwargs)
+        else:
+            ax.plot(points[0], points[1], '.r', **kwargs) #specify format as red points if format was not given
+    elif geomtype == "LineString" or geomtype == "MultiLineString":
+        lines = vector.cpp_vector.get_linestrings(layer_name)
+        if 'fmt' in kwargs:
+            for line in lines:
+                ax.plot(line[0], line[1], **kwargs)
+        else:
+            for line in lines:
+                ax.plot(line[0], line[1], '-k', **kwargs) #specify format as black lines if format was not give
+    else:
+        raise ValueError("geomtype must be of type 'Point', 'MultiPoint', 'LineString', or 'MultiLineString'");