flkit 0.1.0__py3-none-any.whl

flkit/alg/inter/nearest_neighbor.py

@@ -0,0 +1,445 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+最近邻插值算法实现
+Nearest Neighbor Interpolation
+
+最近邻插值是最简单的插值方法，将查询点的值设为最近已知点的值。
+适用于分类数据或需要保持原始值的场景。
+"""
+
+import numpy as np
+from scipy.spatial import cKDTree
+from sklearn.neighbors import NearestNeighbors
+
+
+class NearestNeighbor2D:
+    """
+    二维最近邻插值
+
+    使用最近的已知点的值作为插值结果
+    """
+
+    def __init__(self, metric="euclidean"):
+        """
+        初始化NearestNeighbor2D插值器
+
+        Parameters:
+        -----------
+        metric : str, default='euclidean'
+            距离度量方式，可选：
+            - 'euclidean': 欧几里得距离
+            - 'manhattan': 曼哈顿距离
+            - 'chebyshev': 切比雪夫距离
+            - 'minkowski': 闵可夫斯基距离
+        """
+        self.metric = metric
+        self.tree = None
+        self.values = None
+
+    def fit(self, xyzv: np.ndarray):
+        """
+        训练最近邻模型
+
+        Parameters:
+        -----------
+        xyzv : np.ndarray, shape (N, 3)
+            已知点数据，每行为 [x, y, z] (对于2D插值，z为插值目标值)
+
+        Returns:
+        --------
+        self : NearestNeighbor2D
+            返回自身以支持链式调用
+        """
+        xyzv = np.atleast_2d(xyzv)
+        if xyzv.shape[1] != 3:
+            raise ValueError("输入数据必须是3列：[x, y, z]")
+
+        # 构建KD树用于快速最近邻搜索
+        self.tree = cKDTree(xyzv[:, :2])  # 只使用x, y坐标
+        self.values = xyzv[:, 2]  # z值
+
+        return self
+
+    def predict(self, xy: np.ndarray):
+        """
+        在指定位置进行插值预测
+
+        Parameters:
+        -----------
+        xy : np.ndarray, shape (M, 2) or (2,)
+            待插值点的坐标 [x, y]
+
+        Returns:
+        --------
+        float or np.ndarray
+            - 单点输入 (2,): 返回标量值
+            - 多点输入 (M, 2): 返回数组 shape (M,)
+        """
+        if self.tree is None:
+            raise ValueError("模型尚未训练，请先调用 fit() 方法")
+
+        # 检查输入是单点还是多点
+        is_single_point = xy.ndim == 1 or (xy.ndim == 2 and xy.shape[0] == 1)
+
+        xy = np.atleast_2d(xy)
+        if xy.shape[1] != 2:
+            raise ValueError("预测点坐标必须是2列：[x, y]")
+
+        # 查找最近邻
+        distances, indices = self.tree.query(xy)
+
+        # 返回最近邻的值
+        z = self.values[indices]
+
+        # 根据输入类型返回相应格式
+        if is_single_point:
+            return float(z[0])  # 单点返回标量
+        else:
+            return z  # 多点返回数组
+
+
+class NearestNeighbor3D:
+    """
+    三维最近邻插值
+
+    在三维空间中进行最近邻插值
+    """
+
+    def __init__(self, metric="euclidean"):
+        """
+        初始化NearestNeighbor3D插值器
+
+        Parameters:
+        -----------
+        metric : str, default='euclidean'
+            距离度量方式
+        """
+        self.metric = metric
+        self.tree = None
+        self.values = None
+
+    def fit(self, xyzv: np.ndarray):
+        """
+        训练最近邻3D模型
+
+        Parameters:
+        -----------
+        xyzv : np.ndarray, shape (N, 4)
+            已知点数据，每行为 [x, y, z, value]
+
+        Returns:
+        --------
+        self : NearestNeighbor3D
+            返回自身以支持链式调用
+        """
+        xyzv = np.atleast_2d(xyzv)
+        if xyzv.shape[1] != 4:
+            raise ValueError("输入数据必须是4列：[x, y, z, value]")
+
+        # 构建KD树用于快速最近邻搜索
+        self.tree = cKDTree(xyzv[:, :3])  # 使用x, y, z坐标
+        self.values = xyzv[:, 3]  # 属性值
+
+        return self
+
+    def predict(self, xyz: np.ndarray):
+        """
+        在指定位置进行插值预测
+
+        Parameters:
+        -----------
+        xyz : np.ndarray, shape (M, 3) or (3,)
+            待插值点的坐标 [x, y, z]
+
+        Returns:
+        --------
+        float or np.ndarray
+            - 单点输入 (3,): 返回标量值
+            - 多点输入 (M, 3): 返回数组 shape (M,)
+        """
+        if self.tree is None:
+            raise ValueError("模型尚未训练，请先调用 fit() 方法")
+
+        # 检查输入是单点还是多点
+        is_single_point = xyz.ndim == 1 or (xyz.ndim == 2 and xyz.shape[0] == 1)
+
+        xyz = np.atleast_2d(xyz)
+        if xyz.shape[1] != 3:
+            raise ValueError("预测点坐标必须是3列：[x, y, z]")
+
+        # 查找最近邻
+        distances, indices = self.tree.query(xyz)
+
+        # 返回最近邻的值
+        v = self.values[indices]
+
+        # 根据输入类型返回相应格式
+        if is_single_point:
+            return float(v[0])  # 单点返回标量
+        else:
+            return v  # 多点返回数组
+
+    def predict_grid(self, x_range, y_range, z_range, resolution=None):
+        """
+        在规则网格上进行预测
+
+        Parameters:
+        -----------
+        x_range : tuple
+            x方向的范围 (x_min, x_max)
+        y_range : tuple
+            y方向的范围 (y_min, y_max)
+        z_range : tuple
+            z方向的范围 (z_min, z_max)
+        resolution : tuple, optional
+            网格分辨率 (nx, ny, nz)，默认为 (50, 50, 50)
+
+        Returns:
+        --------
+        tuple
+            (grid_x, grid_y, grid_z, predictions)
+            - grid_x, grid_y, grid_z: 网格坐标
+            - predictions: 预测值网格
+        """
+        if self.tree is None:
+            raise ValueError("模型尚未训练，请先调用 fit() 方法")
+
+        if resolution is None:
+            resolution = (50, 50, 50)
+
+        # 创建网格
+        x = np.linspace(x_range[0], x_range[1], resolution[0])
+        y = np.linspace(y_range[0], y_range[1], resolution[1])
+        z = np.linspace(z_range[0], z_range[1], resolution[2])
+
+        grid_x, grid_y, grid_z = np.meshgrid(x, y, z, indexing="ij")
+
+        # 将网格点展平进行预测
+        grid_points = np.column_stack([grid_x.ravel(), grid_y.ravel(), grid_z.ravel()])
+
+        predictions_flat = self.predict(grid_points)
+        predictions = predictions_flat.reshape(grid_x.shape)
+
+        return grid_x, grid_y, grid_z, predictions
+
+
+class KNearestNeighbor:
+    """
+    K最近邻插值
+
+    使用K个最近邻点的加权平均值进行插值
+    """
+
+    def __init__(self, k=3, weights="uniform", metric="euclidean"):
+        """
+        初始化K最近邻插值器
+
+        Parameters:
+        -----------
+        k : int, default=3
+            最近邻的数量
+        weights : str, default='uniform'
+            权重计算方式：
+            - 'uniform': 均匀权重
+            - 'distance': 距离反比权重
+        metric : str, default='euclidean'
+            距离度量方式
+        """
+        self.k = k
+        self.weights = weights
+        self.metric = metric
+        self.nn_model = None
+        self.points = None
+        self.values = None
+
+    def fit(self, xyzv: np.ndarray):
+        """
+        训练K最近邻模型
+
+        Parameters:
+        -----------
+        xyzv : np.ndarray, shape (N, D+1)
+            已知点数据，前D列为坐标，最后一列为值
+
+        Returns:
+        --------
+        self : KNearestNeighbor
+            返回自身以支持链式调用
+        """
+        xyzv = np.atleast_2d(xyzv)
+        if xyzv.shape[1] < 2:
+            raise ValueError("输入数据至少需要2列：[坐标..., value]")
+
+        self.points = xyzv[:, :-1]  # 前面的列为坐标
+        self.values = xyzv[:, -1]  # 最后一列为值
+
+        if self.k > len(self.points):
+            raise ValueError(f"k={self.k} 不能大于数据点数量 {len(self.points)}")
+
+        # 使用sklearn的NearestNeighbors
+        self.nn_model = NearestNeighbors(n_neighbors=self.k, metric=self.metric)
+        self.nn_model.fit(self.points)
+
+        return self
+
+    def predict(self, query_points: np.ndarray) -> np.ndarray:
+        """
+        在指定位置进行插值预测
+
+        Parameters:
+        -----------
+        query_points : np.ndarray, shape (M, D)
+            查询点坐标
+
+        Returns:
+        --------
+        np.ndarray, shape (M,)
+            插值结果
+        """
+        if self.nn_model is None:
+            raise ValueError("模型尚未训练，请先调用 fit() 方法")
+
+        query_points = np.atleast_2d(query_points)
+
+        # 查找K个最近邻
+        distances, indices = self.nn_model.kneighbors(query_points)
+
+        # 获取最近邻的值
+        neighbor_values = self.values[indices]  # shape: (M, k)
+
+        if self.weights == "uniform":
+            # 均匀权重：简单平均
+            predictions = np.mean(neighbor_values, axis=1)
+        elif self.weights == "distance":
+            # 距离权重：距离越近权重越大
+            # 避免除零错误
+            distances = np.maximum(distances, 1e-10)
+            weights = 1.0 / distances
+
+            # 归一化权重
+            weights = weights / np.sum(weights, axis=1, keepdims=True)
+
+            # 加权平均
+            predictions = np.sum(neighbor_values * weights, axis=1)
+        else:
+            raise ValueError(f"不支持的权重类型: {self.weights}")
+
+        return predictions.squeeze() if predictions.shape[0] == 1 else predictions
+
+
+class AdaptiveNearestNeighbor:
+    """
+    自适应最近邻插值
+
+    根据局部数据密度自动调整邻居数量
+    """
+
+    def __init__(self, min_k=1, max_k=10, radius_factor=1.0, metric="euclidean"):
+        """
+        初始化自适应最近邻插值器
+
+        Parameters:
+        -----------
+        min_k : int, default=1
+            最小邻居数量
+        max_k : int, default=10
+            最大邻居数量
+        radius_factor : float, default=1.0
+            搜索半径因子
+        metric : str, default='euclidean'
+            距离度量方式
+        """
+        self.min_k = min_k
+        self.max_k = max_k
+        self.radius_factor = radius_factor
+        self.metric = metric
+        self.tree = None
+        self.points = None
+        self.values = None
+
+    def fit(self, xyzv: np.ndarray):
+        """
+        训练自适应最近邻模型
+
+        Parameters:
+        -----------
+        xyzv : np.ndarray, shape (N, D+1)
+            已知点数据，前D列为坐标，最后一列为值
+
+        Returns:
+        --------
+        self : AdaptiveNearestNeighbor
+            返回自身以支持链式调用
+        """
+        xyzv = np.atleast_2d(xyzv)
+        if xyzv.shape[1] < 2:
+            raise ValueError("输入数据至少需要2列：[坐标..., value]")
+
+        self.points = xyzv[:, :-1]  # 前面的列为坐标
+        self.values = xyzv[:, -1]  # 最后一列为值
+
+        # 构建KD树
+        self.tree = cKDTree(self.points)
+
+        return self
+
+    def predict(self, query_points: np.ndarray) -> np.ndarray:
+        """
+        在指定位置进行插值预测
+
+        Parameters:
+        -----------
+        query_points : np.ndarray, shape (M, D)
+            查询点坐标
+
+        Returns:
+        --------
+        np.ndarray, shape (M,)
+            插值结果
+        """
+        if self.tree is None:
+            raise ValueError("模型尚未训练，请先调用 fit() 方法")
+
+        query_points = np.atleast_2d(query_points)
+        predictions = []
+
+        for query_point in query_points:
+            # 估计局部密度
+            distances, indices = self.tree.query(
+                query_point, k=min(self.max_k, len(self.points))
+            )
+
+            # 根据距离分布确定邻居数量
+            if len(distances) > 1:
+                # 计算距离的变化率
+                distance_ratios = distances[1:] / distances[:-1]
+                # 找到距离突然增大的位置
+                jump_idx = np.where(distance_ratios > 2.0)[0]
+
+                if len(jump_idx) > 0:
+                    k = max(self.min_k, jump_idx[0] + 1)
+                else:
+                    k = self.max_k
+            else:
+                k = 1
+
+            k = min(k, len(self.points))
+
+            # 使用确定的k进行插值
+            distances_k = distances[:k]
+            indices_k = indices[:k]
+            values_k = self.values[indices_k]
+
+            if k == 1:
+                prediction = values_k[0]
+            else:
+                # 距离权重
+                weights = 1.0 / np.maximum(distances_k, 1e-10)
+                weights = weights / np.sum(weights)
+                prediction = np.sum(values_k * weights)
+
+            predictions.append(prediction)
+
+        predictions = np.array(predictions)
+        return predictions.squeeze() if predictions.shape[0] == 1 else predictions