nrl-tracker 1.11.0__py3-none-any.whl → 1.12.0__py3-none-any.whl

pytcl/mathematical_functions/basic_matrix/special_matrices.py

@@ -539,6 +539,22 @@ def duplication_matrix(n: int) -> NDArray[np.floating]:
     -------
     D : ndarray
         Duplication matrix of shape (n*n, n*(n+1)/2).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions import duplication_matrix, vech, vec
+    >>> # Create duplication matrix for 2x2 symmetric matrices
+    >>> D = duplication_matrix(2)
+    >>> D.shape
+    (4, 3)
+    >>> # For symmetric matrix A = [[1, 2], [2, 3]], half-vec has 3 elements
+    >>> A = np.array([[1.0, 2.0], [2.0, 3.0]])
+    >>> vech_A = vech(A)
+    >>> # Duplication matrix should reconstruct full vectorization
+    >>> vec_A = D @ vech_A
+    >>> np.allclose(vec_A, vec(A))
+    True
     """
     m = n * (n + 1) // 2
     D = np.zeros((n * n, m), dtype=np.float64)
@@ -574,6 +590,21 @@ def elimination_matrix(n: int) -> NDArray[np.floating]:
     -------
     L : ndarray
         Elimination matrix of shape (n*(n+1)/2, n*n).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions import elimination_matrix, vec
+    >>> # Create elimination matrix for 2x2 matrices
+    >>> L = elimination_matrix(2)
+    >>> L.shape
+    (3, 4)
+    >>> # For matrix A, extracts unique elements: [A[0,0], A[1,0], A[1,1]]
+    >>> A = np.array([[1.0, 2.0], [3.0, 4.0]])
+    >>> # Elimination extracts lower-triangular elements
+    >>> vech_A = L @ vec(A)
+    >>> np.allclose(vech_A, [1.0, 3.0, 4.0])
+    True
     """
     m = n * (n + 1) // 2
     L = np.zeros((m, n * n), dtype=np.float64)

pytcl/mathematical_functions/geometry/geometry.py

@@ -132,6 +132,13 @@ def convex_hull_area(points: ArrayLike) -> float:
     -------
     area : float
         Area (2D) or volume (3D) of the convex hull.
+
+    Examples
+    --------
+    >>> points = np.array([[0, 0], [1, 0], [1, 1], [0, 1]])
+    >>> area = convex_hull_area(points)
+    >>> area
+    1.0
     """
     points = np.asarray(points, dtype=np.float64)
     hull = ConvexHull(points)
@@ -180,6 +187,13 @@ def polygon_centroid(vertices: ArrayLike) -> NDArray[np.floating]:
     -------
     centroid : ndarray
         Centroid coordinates (x, y).
+
+    Examples
+    --------
+    >>> polygon = np.array([[0, 0], [1, 0], [1, 1], [0, 1]])
+    >>> centroid = polygon_centroid(polygon)
+    >>> np.allclose(centroid, [0.5, 0.5])
+    True
     """
     vertices = np.asarray(vertices, dtype=np.float64)
 
@@ -274,6 +288,25 @@ def line_plane_intersection(
     -------
     intersection : ndarray or None
         Intersection point, or None if line is parallel to plane.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions.geometry import line_plane_intersection
+    >>> # Line: passes through origin with direction (0, 0, 1) [vertical]
+    >>> line_point = np.array([0.0, 0.0, 0.0])
+    >>> line_dir = np.array([0.0, 0.0, 1.0])
+    >>> # Plane: z = 5, normal is (0, 0, 1)
+    >>> plane_point = np.array([0.0, 0.0, 5.0])
+    >>> plane_normal = np.array([0.0, 0.0, 1.0])
+    >>> intersection = line_plane_intersection(line_point, line_dir, plane_point, plane_normal)
+    >>> np.allclose(intersection, [0, 0, 5])
+    True
+    >>> # Parallel case: line and plane parallel, no intersection
+    >>> line_dir_parallel = np.array([1.0, 0.0, 0.0])
+    >>> intersection = line_plane_intersection(line_point, line_dir_parallel, plane_point, plane_normal)
+    >>> intersection is None
+    True
     """
     line_point = np.asarray(line_point, dtype=np.float64)
     line_dir = np.asarray(line_dir, dtype=np.float64)

pytcl/mathematical_functions/interpolation/interpolation.py

@@ -185,6 +185,21 @@ def pchip(
     p : PchipInterpolator
         PCHIP interpolator object.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions.interpolation import pchip
+    >>> # Monotonic data: stock prices (should not overshoot)
+    >>> x = np.array([0, 1, 2, 3, 4])
+    >>> y = np.array([10, 12, 11, 15, 18])  # Non-monotonic but generally increasing
+    >>> p = pchip(x, y)
+    >>> # Evaluate at intermediate points
+    >>> x_new = np.array([0.5, 1.5, 2.5])
+    >>> y_new = p(x_new)
+    >>> # PCHIP preserves bounds: should stay within observed values
+    >>> np.all((y_new >= y.min()) & (y_new <= y.max()))
+    True
+
     Notes
     -----
     Unlike cubic splines, PCHIP will not overshoot if the data is
@@ -222,6 +237,21 @@ def akima(
     a : Akima1DInterpolator
         Akima interpolator object.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions.interpolation import akima
+    >>> # Noisy data where smoothness without oscillation is desired
+    >>> x = np.array([0, 1, 2, 3, 4, 5])
+    >>> y = np.array([0, 1, 1.5, 1.2, 2.0, 2.5])  # Noisy measurements
+    >>> a = akima(x, y)
+    >>> # Evaluate at intermediate points
+    >>> x_new = np.array([0.5, 1.5, 3.5])
+    >>> y_new = a(x_new)
+    >>> # Akima should produce smooth, non-oscillating results
+    >>> y_new.shape
+    (3,)
+
     See Also
     --------
     scipy.interpolate.Akima1DInterpolator : Underlying implementation.
@@ -307,6 +337,23 @@ def interp3d(
     f : RegularGridInterpolator
         Interpolation function.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions.interpolation import interp3d
+    >>> # Create a 3D grid: temperature field
+    >>> x = np.array([0, 1, 2])
+    >>> y = np.array([0, 1, 2])
+    >>> z = np.array([0, 1])
+    >>> # Temperature values at grid points (3x3x2)
+    >>> values = np.arange(18).reshape((3, 3, 2), order='C').astype(float)
+    >>> f = interp3d(x, y, z, values, kind='linear')
+    >>> # Interpolate at intermediate points
+    >>> pts = np.array([[0.5, 0.5, 0.5], [1.5, 1.5, 0.5]])
+    >>> result = f(pts)
+    >>> result.shape
+    (2,)
+
     See Also
     --------
     scipy.interpolate.RegularGridInterpolator : Underlying implementation.
@@ -397,6 +444,23 @@ def barycentric(
     p : BarycentricInterpolator
         Barycentric interpolator object.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions.interpolation import barycentric
+    >>> # Interpolate a polynomial at Chebyshev nodes (most stable)
+    >>> n = 5
+    >>> x = np.cos(np.linspace(0, np.pi, n))  # Chebyshev nodes
+    >>> y = x**2 + 2*x + 1  # Quadratic function
+    >>> poly = barycentric(x, y)
+    >>> # Evaluate interpolant at new points
+    >>> x_new = np.linspace(-0.8, 0.8, 3)
+    >>> y_interp = poly(x_new)
+    >>> # Should match the original function well
+    >>> y_exact = x_new**2 + 2*x_new + 1
+    >>> np.allclose(y_interp, y_exact, atol=0.01)
+    True
+
     See Also
     --------
     scipy.interpolate.BarycentricInterpolator : Underlying implementation.
@@ -427,6 +491,25 @@ def krogh(
     k : KroghInterpolator
         Krogh interpolator object.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions.interpolation import krogh
+    >>> # Hermite interpolation with function values and derivatives
+    >>> x = np.array([0, 1, 2])
+    >>> # For Hermite interpolation, y rows are: function values, then derivatives
+    >>> y = np.array([
+    ...     [1, 2, 3],      # Function values at x=0, 1, 2
+    ...     [0, 1, 2],      # Derivatives at x=0, 1, 2
+    ... ])
+    >>> k = krogh(x, y)
+    >>> # Evaluate interpolant at new points
+    >>> x_new = np.array([0.5, 1.5])
+    >>> y_interp = k(x_new)
+    >>> # Interpolant passes through original points and matches derivatives
+    >>> np.allclose(k(x), y[0])
+    True
+
     See Also
     --------
     scipy.interpolate.KroghInterpolator : Underlying implementation.

pytcl/mathematical_functions/signal_processing/detection.py

@@ -711,6 +711,21 @@ def cfar_so(
     result : CFARResult
         Named tuple with detection results.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions.signal_processing import cfar_so
+    >>> # Create test signal with closely spaced targets in clutter
+    >>> np.random.seed(42)
+    >>> signal = np.random.exponential(1.0, 500)
+    >>> signal[200:205] = [30, 40, 35, 45, 38]  # Target cluster
+    >>> signal[350] = 50  # Isolated target
+    >>> # Detect using SO-CFAR
+    >>> result = cfar_so(signal, guard_cells=2, ref_cells=16, pfa=1e-4)
+    >>> # SO-CFAR good for clutter edge detection
+    >>> len(result.detection_indices) >= 2  # Should find multiple targets
+    True
+
     Notes
     -----
     SO-CFAR is complementary to GO-CFAR. It is more sensitive near
@@ -966,6 +981,22 @@ def cluster_detections(
     -------
     peak_indices : ndarray
         Indices of detection peaks after clustering.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions.signal_processing import cluster_detections
+    >>> # CFAR detection result with closely spaced detections
+    >>> detections = np.zeros(100, dtype=bool)
+    >>> detections[20:24] = True  # Cluster 1 (4 adjacent detections)
+    >>> detections[60] = True      # Cluster 2 (single detection)
+    >>> detections[62] = True      # Close to cluster 2
+    >>> # Cluster with min_separation=1 (adjacent counts as same cluster)
+    >>> peaks = cluster_detections(detections, min_separation=1)
+    >>> len(peaks)  # Should find 2 clusters
+    2
+    >>> peaks[0]  # Center of first cluster (indices 20-23)
+    21
     """
     detections = np.asarray(detections)
 

pytcl/mathematical_functions/signal_processing/filters.py

@@ -810,6 +810,22 @@ def sos_to_zpk(sos: ArrayLike) -> tuple[NDArray[Any], NDArray[Any], Any]:
         Poles.
     k : float
         Gain.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions.signal_processing import (
+    ...     sos_to_zpk, butter_sos
+    ... )
+    >>> # Design a Butterworth filter and convert to ZPK form
+    >>> sos = butter_sos(4, 0.3)  # 4th order Butterworth lowpass
+    >>> z, p, k = sos_to_zpk(sos)
+    >>> # Check filter stability: poles must be inside unit circle
+    >>> np.all(np.abs(p) < 1.0)
+    True
+    >>> # Verify number of poles matches filter order
+    >>> len(p) == 4
+    True
     """
     return scipy_signal.sos2zpk(np.asarray(sos))
 
@@ -835,5 +851,45 @@ def zpk_to_sos(
     -------
     sos : ndarray
         Second-order sections array.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions.signal_processing import (
+    ...     zpk_to_sos
+    ... )
+    >>> # Create a simple 2nd order Butterworth-like filter
+    >>> z = np.array([-1.0, -1.0])  # Zeros at -1
+    >>> p = np.array([0.7071 * np.exp(1j * np.pi / 4),
+    ...               0.7071 * np.exp(-1j * np.pi / 4)])  # Complex poles
+    >>> k = 1.0
+    >>> sos = zpk_to_sos(z, p, k)
+    >>> sos.shape
+    (1, 6)
+    >>> # Verify roundtrip conversion
+    >>> from pytcl.mathematical_functions.signal_processing import sos_to_zpk
+    >>> z2, p2, k2 = sos_to_zpk(sos)
+    >>> np.allclose(z, z2) and np.allclose(p, p2)
+    True
     """
     return scipy_signal.zpk2sos(np.asarray(z), np.asarray(p), k, pairing=pairing)
+
+
+__all__ = [
+    "FilterCoefficients",
+    "FrequencyResponse",
+    "butter_design",
+    "cheby1_design",
+    "cheby2_design",
+    "ellip_design",
+    "bessel_design",
+    "fir_design",
+    "fir_design_remez",
+    "apply_filter",
+    "filtfilt",
+    "frequency_response",
+    "group_delay",
+    "filter_order",
+    "sos_to_zpk",
+    "zpk_to_sos",
+]

pytcl/mathematical_functions/signal_processing/matched_filter.py

@@ -273,12 +273,23 @@ def optimal_filter(
     Examples
     --------
     >>> import numpy as np
+    >>> # White noise case (simple matched filter)
     >>> signal = np.random.randn(256)
     >>> template = np.ones(16)
-    >>> noise_psd = np.ones(256)  # White noise
+    >>> noise_psd = np.ones(256)  # White noise (flat PSD)
     >>> output = optimal_filter(signal, template, noise_psd)
     >>> len(output) == len(signal)
     True
+    >>> # Colored noise case (Wiener filtering optimal)
+    >>> # Create signal with target embedded in colored noise
+    >>> target = np.array([1, 2, 3, 2, 1])
+    >>> noise_freq = np.linspace(0, 1, 256)
+    >>> colored_noise_psd = 1.0 + 2.0 * np.exp(-5 * noise_freq)  # Red noise
+    >>> colored_noise = np.random.randn(256) * np.sqrt(colored_noise_psd)
+    >>> signal = np.concatenate([colored_noise, target, colored_noise])
+    >>> output = optimal_filter(signal, target, colored_noise_psd)
+    >>> len(output) == len(signal)
+    True
 
     Notes
     -----
@@ -751,6 +762,26 @@ def cross_ambiguity(
         Doppler frequency values in Hz.
     caf : ndarray
         Cross-ambiguity function (2D, complex).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions.signal_processing import (
+    ...     cross_ambiguity, generate_lfm_chirp
+    ... )
+    >>> # Generate two LFM chirps for correlation analysis
+    >>> fs = 10000  # 10 kHz sampling
+    >>> signal1 = generate_lfm_chirp(0.001, 1000, 2000, fs)  # 1 ms chirp
+    >>> signal2 = generate_lfm_chirp(0.001, 1000, 2000, fs)  # Identical chirp
+    >>> # Compute cross-ambiguity function
+    >>> delays, dopplers, caf = cross_ambiguity(
+    ...     signal1, signal2, fs, n_delay=64, n_doppler=64
+    ... )
+    >>> # Auto-correlation should have peak near zero delay/Doppler
+    >>> caf.shape
+    (64, 64)
+    >>> np.max(np.abs(caf)) > 0.9  # High correlation for identical signals
+    True
     """
     signal1 = np.asarray(signal1, dtype=np.complex128)
     signal2 = np.asarray(signal2, dtype=np.complex128)

pytcl/mathematical_functions/special_functions/hypergeometric.py

@@ -311,6 +311,23 @@ def hyp1f1_regularized(
     F : ndarray
         Values of 1F1(a; b; z) / Gamma(b).
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions.special_functions import hyp1f1_regularized
+    >>> # Regularized form avoids overflow for problematic b values
+    >>> a, b, z = 0.5, 1.5, 1.0
+    >>> f_reg = hyp1f1_regularized(a, b, z)
+    >>> # Should give finite, non-overflowing result
+    >>> np.isfinite(f_reg)
+    True
+    >>> # Compare to regular hypergeometric computation
+    >>> from pytcl.mathematical_functions.special_functions import hyp1f1
+    >>> import scipy.special as sp
+    >>> f_normal = hyp1f1(a, b, z) / sp.gamma(b)
+    >>> np.allclose(f_reg, f_normal)
+    True
+
     Notes
     -----
     This function remains finite even when b is a non-positive integer,

pytcl/mathematical_functions/statistics/estimators.py

@@ -68,6 +68,13 @@ def weighted_var(
     -------
     var : ndarray
         Weighted variance.
+
+    Examples
+    --------
+    >>> x = [1, 2, 3]
+    >>> weights = [1, 1, 2]
+    >>> weighted_var(x, weights)
+    0.5625
     """
     x = np.asarray(x, dtype=np.float64)
     weights = np.asarray(weights, dtype=np.float64)
@@ -106,6 +113,14 @@ def weighted_cov(
     -------
     cov : ndarray
         Weighted covariance matrix of shape (n_features, n_features).
+
+    Examples
+    --------
+    >>> x = [[1, 2], [2, 3], [3, 4]]
+    >>> weights = [1, 1, 1]
+    >>> cov = weighted_cov(x, weights)
+    >>> cov.shape
+    (2, 2)
     """
     x = np.asarray(x, dtype=np.float64)
     weights = np.asarray(weights, dtype=np.float64)
@@ -173,6 +188,12 @@ def sample_var(
     -------
     var : ndarray
         Sample variance.
+
+    Examples
+    --------
+    >>> x = [1, 2, 3, 4, 5]
+    >>> sample_var(x)
+    2.5
     """
     return np.var(x, ddof=ddof, axis=axis, dtype=np.float64)
 
@@ -198,6 +219,13 @@ def sample_cov(
     -------
     cov : ndarray
         Covariance matrix.
+
+    Examples
+    --------
+    >>> x = [[1, 2], [2, 3], [3, 4]]
+    >>> cov = sample_cov(x)
+    >>> cov.shape
+    (2, 2)
     """
     x = np.asarray(x, dtype=np.float64)
 
@@ -224,6 +252,15 @@ def sample_corr(x: ArrayLike) -> NDArray[np.floating]:
     -------
     corr : ndarray
         Correlation matrix of shape (n_features, n_features).
+
+    Examples
+    --------
+    >>> x = [[1, 2], [2, 3], [3, 4]]
+    >>> corr = sample_corr(x)
+    >>> corr.shape
+    (2, 2)
+    >>> corr[0, 0]  # Correlation of feature 1 with itself
+    1.0
     """
     return np.corrcoef(np.asarray(x, dtype=np.float64).T)
 
@@ -246,6 +283,13 @@ def median(
     -------
     med : ndarray
         Median value(s).
+
+    Examples
+    --------
+    >>> median([1, 2, 3, 4, 5])
+    3.0
+    >>> median([1, 2, 3, 4])
+    2.5
     """
     return np.median(x, axis=axis)
 
@@ -275,6 +319,11 @@ def mad(
     mad : ndarray
         MAD value(s).
 
+    Examples
+    --------
+    >>> mad([1, 2, 3, 4, 5])
+    1.4826
+
     Notes
     -----
     For normally distributed data, scale * MAD approximates the
@@ -303,6 +352,11 @@ def iqr(
     -------
     iqr : ndarray
         Interquartile range (Q3 - Q1).
+
+    Examples
+    --------
+    >>> iqr([1, 2, 3, 4, 5, 6, 7, 8, 9])
+    4.5
     """
     x = np.asarray(x, dtype=np.float64)
     q75, q25 = np.percentile(x, [75, 25], axis=axis)
@@ -330,6 +384,11 @@ def skewness(
     -------
     skew : ndarray
         Skewness value(s).
+
+    Examples
+    --------
+    >>> skewness([1, 2, 3, 4, 5])
+    0.0
     """
     from scipy.stats import skew as scipy_skew
 
@@ -361,6 +420,11 @@ def kurtosis(
     -------
     kurt : ndarray
         Kurtosis value(s).
+
+    Examples
+    --------
+    >>> kurtosis([1, 2, 3, 4, 5])
+    -1.2
     """
     from scipy.stats import kurtosis as scipy_kurtosis
 
@@ -393,6 +457,13 @@ def moment(
     -------
     m : ndarray
         Moment value(s).
+
+    Examples
+    --------
+    >>> moment([1, 2, 3, 4, 5], order=2)
+    2.0
+    >>> moment([1, 2, 3, 4, 5], order=2, central=False)
+    11.0
     """
     from scipy.stats import moment as scipy_moment
 

pytcl/mathematical_functions/transforms/wavelets.py

@@ -816,6 +816,31 @@ def threshold_coefficients(
     -------
     result : DWTResult
         Thresholded coefficients.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.mathematical_functions.transforms import dwt, threshold_coefficients, idwt
+    >>> # Create noisy signal
+    >>> t = np.linspace(0, 1, 256)
+    >>> signal = np.sin(2 * np.pi * 5 * t)
+    >>> noise = 0.5 * np.random.randn(256)
+    >>> noisy_signal = signal + noise
+    >>> # Denoise using wavelet thresholding
+    >>> coeffs = dwt(noisy_signal, wavelet='db4', level=3)
+    >>> # Apply soft threshold (default automatic threshold value)
+    >>> coeffs_denoised = threshold_coefficients(coeffs, threshold='soft')
+    >>> # Reconstruct signal from thresholded coefficients
+    >>> signal_denoised = idwt(coeffs_denoised)
+    >>> len(signal_denoised) == len(noisy_signal)
+    True
+
+    Notes
+    -----
+    When value is None, the universal threshold is computed as:
+        sigma * sqrt(2 * log(n))
+    where sigma is estimated from the finest detail coefficients
+    and n is the total number of coefficients.
     """
     if not PYWT_AVAILABLE:
         raise ImportError(

pytcl/navigation/great_circle.py

@@ -901,6 +901,19 @@ def clear_great_circle_cache() -> None:
 
     This can be useful to free memory after processing large datasets
     or when cache statistics are being monitored.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.navigation import great_circle_distance, clear_great_circle_cache
+    >>> # Compute a few distances (cached)
+    >>> d1 = great_circle_distance(0, 0, np.radians(1), 0)
+    >>> d2 = great_circle_distance(0, 0, np.radians(2), 0)
+    >>> # Check cache state before clear
+    >>> cache_before = great_circle_distance.__wrapped__.__self__.cache_info()
+    >>> # Clear all cached values
+    >>> clear_great_circle_cache()
+    >>> # Cache is now empty
     """
     _gc_distance_cached.cache_clear()
     _gc_azimuth_cached.cache_clear()
@@ -914,6 +927,26 @@ def get_cache_info() -> dict[str, Any]:
     -------
     dict[str, Any]
         Dictionary with cache statistics for distance and azimuth caches.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.navigation import great_circle_distance, get_cache_info, clear_great_circle_cache
+    >>> # Clear cache first
+    >>> clear_great_circle_cache()
+    >>> # Compute some distances (multiple calls to test cache hits)
+    >>> d1 = great_circle_distance(0, 0, np.radians(1), 0)
+    >>> d1_again = great_circle_distance(0, 0, np.radians(1), 0)  # Cache hit
+    >>> # Get cache statistics
+    >>> info = get_cache_info()
+    >>> info['distance']['hits'] > 0  # Should have at least one hit
+    True
+    >>> info['distance']['currsize'] > 0  # Cache is not empty
+    True
+
+    See Also
+    --------
+    clear_great_circle_cache : Clear all cached values.
     """
     return {
         "distance": _gc_distance_cached.cache_info()._asdict(),