sgspy 1.0.2__cp310-cp310-manylinux_2_28_x86_64.whl

sgspy/__init__.py

@@ -0,0 +1,82 @@
+##
+# @defgroup user User Documentation
+# This is the documentation describing how to use the Python functions within the sgsPy
+# package. For information on the underlying C++ implementations, see the developer
+# docs.
+#
+# The first step in any processing using the sgsPy package will be to initialize in insance
+# of either sgspy.SpatialRaster or sgspy.SpatialVector. These are the primary data inputs to
+# all sgs functions, and information on their use can be found in the 'utils' section.
+#
+# The processing functions are split into three different categories: calculate, stratify,
+# and sample. @n
+# The calculate section contains various helpful functions to assist in sampling
+# but are not necessarily a specific stratification or sampling function. Right now, 
+# it only has 'pca' or principal component analysis. @n
+# The stratify section has various stratification functions including stratification according 
+# to user defined breaks 'breaks', stratification according to polygons 'poly', stratification
+# along quantiles 'quantiles', and a method for mapping multiple existing stratificaiton outputs 'map'. @n
+# The sample sections has various sampling functions including simple random sampling 'srs', stratified
+# random sampling 'strat', systematic sampling 'systematic', and conditional latin hypercube sampling 'clhs'. @n
+
+import os
+import sys
+import platform
+import ctypes
+
+if (platform.system() == 'Windows'):
+    vendored_lib_path = os.path.join(sys.prefix, "sgspy")
+    lib_path = os.path.join(sys.prefix, "Library", "bin")
+    os.add_dll_directory(vendored_lib_path)
+    os.add_dll_directory(lib_path)
+
+    if vendored_lib_path not in os.environ['PATH']:
+        os.environ['PATH'] = vendored_lib_path + os.pathsep + os.environ['PATH']
+
+    if lib_path not in os.environ['PATH']:
+        os.environ['PATH'] = lib_path + os.pathsep + os.environ['PATH']
+
+else: #linux 
+    #this library goes missing at runtime if we don't do this
+    ctypes.CDLL(os.path.join(sys.prefix, 'lib', 'libtbb.so.12'), os.RTLD_GLOBAL | os.RTLD_NOW)
+   
+GIGABYTE = 1073741824
+
+from . import utils
+from . import calculate
+from . import sample
+from . import stratify
+
+from .utils import (
+    SpatialRaster,
+    SpatialVector,
+)
+
+from .calculate import (
+    pca,
+    representation,
+)
+
+from .sample import (
+    ahels,
+    clhs,
+    nc,
+    srs,
+    strat,
+    systematic,
+)
+
+from .stratify import (
+    breaks,
+    kmeans,
+    poly,
+    quantiles,
+    map,
+)
+
+__all__ = list(
+    set(utils.__all__) |
+    set(calculate.__all__) |
+    set(sample.__all__) |
+    set(stratify.__all__)
+)

sgspy/calculate/__init__.py

@@ -0,0 +1,18 @@
+##
+# @defgroup user_calculate calculate
+# @ingroup user
+#
+# documentation of additional calculation functions for sgsPy. At the moment just principal component analysis.
+
+from . import (
+    pca,
+    representation,
+)
+
+from .pca import pca
+from .representation import representation
+
+__all__ = [
+    "pca",
+    "representation",
+]

sgspy/calculate/pca/__init__.py

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

sgspy/calculate/pca/pca.py

@@ -0,0 +1,158 @@
+# ******************************************************************************
+#
+#  Project: sgs
+#  Purpose: principal component analysis (pca)
+#  Author: Joseph Meyer
+#  Date: October, 2025
+#
+# ******************************************************************************
+
+##
+# @defgroup user_pca pca
+# @ingroup user_calculate
+
+import os
+import sys
+import site
+import tempfile
+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 pca_cpp
+
+GIGABYTE = 1073741824
+
+## 
+# @ingroup user_pca
+# This functions conducts principal component analysis on the given
+# raster.
+# 
+# A number of output components must be provided as an integer. This integer
+# must be less than or equal to the total number of bands in the input raster,
+# and will be the number of bands in the output raster.
+# A filename may be given to specify an output file location, otherwise
+# a virtual file type will be used. 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
+# 
+# Principal components are calculated across all raster bands, 
+# along with mean and standard deviation of each raster band. The
+# raster is both centered and scaled, then output values are calculated
+# for each principal component.
+# 
+# Examples
+# --------------------
+# rast = sgspy.SpatialRaster("raster.tif") @n
+# pcomp = sgspy.calculate.pca(rast, 3) 
+# 
+# rast = sgspy.SpatialRaster("raster.tif") @n
+# pcomp = sgspy.calculate.pca(rast, 2, filename="pca.tif", display_info=True)
+# 
+# rast = sgspy.SpatialRaster("raster.tif") @n
+# pcomp = sgspy.calculate.pca(rast, 1, filename="pca.tif", driver_options={"COMPRESS": "LZW"}) 
+# 
+# Parameters
+# --------------------
+# rast : SpatialRaster @n
+#     raster data structure containing input raster bands @n @n
+# num_comp : int @n
+#     the number of components @n @n
+# filename : str @n
+#     output filename or '' if there should not be an output file @n @n
+# display_info : bool @n
+#     whether to display principal component eigenvalues/eigenvectors @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 principal component bands
+def pca(
+    rast: SpatialRaster,
+    num_comp: int,
+    filename: str = '',
+    display_info: bool = False,
+    driver_options: dict = None
+    ):
+        
+    if type(rast) is not SpatialRaster:
+        print(type(rast))
+        raise TypeError("'rast' parameter must be of type sgspy.SpatialRaster.")
+
+    if type(num_comp) is not int:
+        raise TypeError("'num_comp' parameter must be of type int.")
+
+    if type(filename) is not str:
+        raise TypeError("'filename' parameter must be of type str.")
+
+    if type(display_info) is not bool:
+        raise TypeError("'display_info' parameter must be of type bool.")
+
+    if driver_options is not None and type(driver_options) is not dict: 
+        raise TypeError("'driver_options' parameter, if given, 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 = ""
+
+    #ensure number of components is acceptabe
+    if num_comp <= 0 or num_comp > len(rast.bands):
+        msg = f"the number of components must be greater than zero and less than or equal to the total number of raster bands ({len(rast.bands)})."
+        raise ValueError(msg)
+
+    #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 TypeError("the key for all key/value pairs in the driver_options dict must be a string.")
+            driver_options_str[key] = str(val)
+
+   #determine whether the raster should be categorized as 'large' and thus be processed in blocks
+    raster_size_bytes = 0
+    height = rast.height
+    width = rast.width
+    for i in range(len(rast.bands)):
+        pixel_size = rast.cpp_raster.get_raster_band_type_size(i)
+        band_size = height * width * pixel_size
+        raster_size_bytes += band_size
+        if band_size >= GIGABYTE:
+            large_raster = True
+            break
+
+    large_raster = large_raster or (raster_size_bytes > GIGABYTE * 4)
+
+    temp_dir = tempfile.mkdtemp()
+    rast.have_temp_dir = True
+    rast.temp_dir = temp_dir
+
+    [pcomp, eigenvectors, eigenvalues] = pca_cpp(
+        rast.cpp_raster,
+        num_comp,
+        large_raster,
+        temp_dir,
+        filename,
+        driver_options_str
+    )
+
+    if display_info:
+        print('eigenvectors:')
+        print(eigenvectors)
+        print()
+        print('eigenvalues:')
+        print(eigenvalues)
+        print()
+
+    pcomp_rast = SpatialRaster(pcomp)
+    pcomp_rast.cpp_raster.set_temp_dir(temp_dir)
+    rast.have_temp_dir = False
+    pcomp_rast.temp_dataset = filename == "" and large_raster
+    pcomp_rast.filename = filename
+
+    return pcomp_rast

sgspy/calculate/representation/__init__.py

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

sgspy/calculate/representation/representation.py

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

sgspy/sample/__init__.py

@@ -0,0 +1,30 @@
+## 
+# @defgroup user_sample sample
+# @ingroup user
+#
+# Documentation for the sampling functions.
+
+from . import (
+    ahels,
+    clhs,
+    nc,
+    srs,
+    strat,
+    systematic,
+)
+
+from .ahels import ahels
+from .clhs import clhs
+from .nc import nc
+from .srs import srs
+from .strat import strat
+from .systematic import systematic
+
+__all__ = [
+    "ahels",
+    "clhs",
+    "nc",
+    "srs",
+    "strat",
+    "systematic",
+]

sgspy/sample/ahels/__init__.py

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

sgspy/sample/ahels/ahels.py

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

sgspy/sample/clhs/__init__.py

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

sgspy/sample/clhs/clhs.py

@@ -0,0 +1,202 @@
+# ******************************************************************************
+#
+#  Project: sgs
+#  Purpose: simple random sampling (srs)
+#  Author: Joseph Meyer
+#  Date: June, 2025
+#
+# ******************************************************************************
+
+##
+# @defgroup user_clhs clhs
+# @ingroup user_sample
+
+import os
+import sys
+import site
+import tempfile
+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 clhs_cpp
+
+## 
+# @ingroup user_clhs
+# This function conducts Conditioned Latin Hypercube Sampling, see the following article for an
+# in depth description of the method itself:
+# 
+# Minasny, B. and McBratney, A.B. 2006. A conditioned Latin hypercube method
+# for sampling in the presence of ancillary information. Computers and Geosciences, 32:1378-1388.
+#
+# The number of output samples is decided by the 'num_samples' parameter. The 'iterations' parameter
+# indicates the number of iterations the simulated annealing portion of the clhs algorithm will undertake
+# in the case where a perfect latin hypercube is not found. A higher number of iterations may result in
+# a more representative sample, although the standard value recommended by Misany and McBratney is 10000.
+#
+# The access parameter may be given to restrict the areas where sampling may occur. The algorithm will still
+# attempt to find a latin hypercube representative across the entire feature space, not just the accessible
+# pixels. The access vector may contain geometries of type LineString or MultiLineString. buff_outer specifies
+# the buffer distance around the geometry which is allowed to be included in the sampling. buff_inner specifies
+# the buffer distance around the geometry which is not allwoed to be included in the sampling. buff_outer must
+# be larger than buff_inner. For a multi layer vector, layer_name must be specified.
+#
+# The output is an object of type sgspy.SpatialVector which contains the chosen sample points.
+#
+# Examples
+# --------------------
+# rast = sgspy.SpatialRaster("raster.tif") @n
+# samples = sgspy.sample.clhs(rast, num_samples=250)
+#
+# rast = sgspy.SpatialRaster("raster.tif") @n
+# samples = sgspy.sample.clhs(rast, num_samples=250, plot=True, filename="clhs_samples.shp")
+#
+# rast = sgspy.SpatialRaster("raster.tif") @n
+# access = sgspy.SpatialVector("access_network.shp") @n
+# samples = sgspy.sample.clhs(rast, num_samples=200, access=access, buff_outer=300)
+#
+# rast = sgspy.SpatialRaster("raster.tif") @n
+# access = sgspy.SpatialVector("access_network.shp") @n
+# samples = sgspy.sample.clhs(rast, num_samples=200, access=access, buff_inner=50, buff_outer=300)
+#
+# Parameters
+# --------------------
+# rast : SpatialRaster @n
+#     raster data structure containing input raster bands @n @n
+# num_samples : int @n
+#     the target number of samples @n @n
+# iterations : int @n
+#     the number of iterations in the clhs algorithms @n @n
+# access : SpatialVector @n
+#     a vector specifying an access network @n @n
+# layer_name : str @n
+#     the layer within the access network which will be used for sampling @n @n
+# buff_inner : int | float @n
+#     buffer boundary specifying distance from access geometries which CANNOT be sampled @n @n
+# buff_outer : int | float @n
+#     buffer boundary specifying distance from access geometries which CAN be sampled @n @n
+# plot : bool @n
+#     whether to plot the output samples or not @n @n
+# filename : str @n
+#     the filename to write to, or '' if file should not be written @n @n
+#
+# Returns
+# --------------------
+# a SpatialVector object containing point geometries of sample locations
+def clhs(
+    rast: SpatialRaster,
+    num_samples: int,
+    iterations: int = 10000,
+    access: Optional[SpatialVector] = None,
+    layer_name: Optional[str] = None,
+    buff_inner: Optional[int | float] = None,
+    buff_outer: Optional[int | float] = None,
+    plot: bool = False,
+    filename: str = ''):
+        
+    if type(rast) is not SpatialRaster:
+        raise TypeError("'rast' parameter must be of type sgspy.SpatialRaster.")
+
+    if type(num_samples) is not int:
+        raise TypeError("'num_samples' parameter must be of type int.")
+
+    if type(iterations) is not int:
+        raise TypeError("'iterations' parameter must be of type int.")
+
+    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(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 num_samples < 1:
+        raise ValueError("num_samples must be greater than 0")
+
+    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
+
+    temp_dir = rast.cpp_raster.get_temp_dir()
+    if temp_dir == "":
+        temp_dir = tempfile.mkdtemp()
+        rast.cpp_raster.set_temp_dir(temp_dir)
+
+    [sample_coordinates, cpp_vector] = clhs_cpp(
+        rast.cpp_raster,
+        num_samples,
+        iterations,
+        access_vector,
+        layer_name,
+        buff_inner,
+        buff_outer,
+        plot,
+        temp_dir,
+        filename
+    )
+
+    #plot new vector if requested
+    if plot:
+        try:
+            fig, ax = plt.subplots()
+            rast.plot(ax, band=rast.bands[0])
+            title = "samples on " + rast.bands[0]
+            
+            if access:
+                access.plot('LineString', ax)
+                title += " with access"
+
+            ax.plot(sample_coordinates[0], sample_coordinates[1], '.r')
+            ax.set_title(label=title)
+            plt.show()
+
+        except Exception as e:
+            print("unable to plot output: " + str(e))
+
+    return SpatialVector(cpp_vector)

sgspy/sample/nc/__init__.py

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

sgspy/sample/nc/nc.py

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

sgspy/sample/srs/__init__.py

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