nrl-tracker 1.9.1__py3-none-any.whl → 1.9.2__py3-none-any.whl

pytcl/performance_evaluation/track_metrics.py

@@ -192,6 +192,17 @@ def ospa_over_time(
     ------
     ValueError
         If sequences have different lengths.
+
+    Examples
+    --------
+    >>> # Two time steps with ground truth and estimates
+    >>> X_seq = [[np.array([0, 0]), np.array([10, 10])],
+    ...          [np.array([1, 0]), np.array([11, 10])]]
+    >>> Y_seq = [[np.array([0.5, 0]), np.array([10, 10.5])],
+    ...          [np.array([1.5, 0]), np.array([11, 10.5])]]
+    >>> ospa_vals = ospa_over_time(X_seq, Y_seq, c=100, p=2)
+    >>> len(ospa_vals)
+    2
     """
     if len(X_sequence) != len(Y_sequence):
         raise ValueError("Sequences must have the same length")
@@ -340,6 +351,13 @@ def identity_switches(
     -------
     int
         Number of identity switches.
+
+    Examples
+    --------
+    >>> true_labels = np.array([0, 0, 1, 1])
+    >>> estimated_labels = np.array([0, 0, 0, 0])  # Track 0 switches targets
+    >>> identity_switches(true_labels, estimated_labels)
+    1
     """
     true_labels = np.asarray(true_labels)
     estimated_labels = np.asarray(estimated_labels)
@@ -391,6 +409,18 @@ def mot_metrics(
     MOTA (Multiple Object Tracking Accuracy) accounts for false positives,
     misses, and identity switches. MOTP (Precision) measures localization
     accuracy for correctly matched pairs.
+
+    Examples
+    --------
+    >>> gt = [[np.array([0, 0]), np.array([10, 10])],
+    ...       [np.array([1, 0]), np.array([11, 10])]]
+    >>> est = [[np.array([0.5, 0]), np.array([10.5, 10])],
+    ...        [np.array([1.5, 0]), np.array([11.5, 10])]]
+    >>> result = mot_metrics(gt, est, threshold=5.0)
+    >>> result.mota  # High accuracy with small errors
+    1.0
+    >>> result.motp < 1.0  # Some localization error
+    True
     """
     total_gt = 0
     total_fp = 0

pytcl/static_estimation/maximum_likelihood.py

@@ -222,6 +222,14 @@ def fisher_information_exponential_family(
     -----
     For exponential families, I(theta) = Var[T(X)] = d^2 A(theta) / d theta^2,
     where A(theta) is the log-partition function.
+
+    Examples
+    --------
+    >>> def suff_stats(x, theta):
+    ...     return np.array([x, x**2])  # Mean and second moment
+    >>> data = np.random.normal(0, 1, 100)
+    >>> theta = np.array([0.0, 1.0])
+    >>> F = fisher_information_exponential_family(suff_stats, theta, data)
     """
     theta = np.asarray(theta, dtype=np.float64)
     data = np.asarray(data, dtype=np.float64)
@@ -263,6 +271,14 @@ def observed_fisher_information(
     The observed Fisher information is often more accurate for
     finite samples and is asymptotically equivalent to the
     expected Fisher information.
+
+    Examples
+    --------
+    >>> data = np.array([1.2, 0.8, 1.1, 0.9, 1.0])
+    >>> def log_lik(theta):
+    ...     return -0.5 * np.sum((data - theta[0])**2 / theta[1]) - 2.5 * np.log(theta[1])
+    >>> theta = np.array([1.0, 0.1])
+    >>> F_obs = observed_fisher_information(log_lik, theta)
     """
     return fisher_information_numerical(log_likelihood, theta, h)
 
@@ -361,6 +377,14 @@ def cramer_rao_bound_biased(
     -----
     For a biased estimator with bias b(theta), the CRB becomes:
         Var(theta_hat) >= (I + db/dtheta) I^{-1} (I + db/dtheta)^T
+
+    Examples
+    --------
+    >>> F = np.array([[10.0, 0], [0, 5.0]])  # Fisher info
+    >>> db = np.array([[0.1, 0], [0, 0.2]])  # Bias gradient
+    >>> crb_biased = cramer_rao_bound_biased(F, db)
+    >>> crb_biased.shape
+    (2, 2)
     """
     F = np.asarray(fisher_info, dtype=np.float64)
     db = np.asarray(bias_gradient, dtype=np.float64)
@@ -571,6 +595,17 @@ def mle_scoring(
     -----
     Fisher scoring update: theta_{n+1} = theta_n + I(theta_n)^{-1} @ score
     This is equivalent to Newton-Raphson when I(theta) = -E[H].
+
+    Examples
+    --------
+    >>> data = np.array([1.0, 1.1, 0.9, 1.2, 0.8])
+    >>> def log_lik(theta):
+    ...     return -0.5 * len(data) * np.log(2*np.pi) - np.sum((data - theta[0])**2) / 2
+    >>> def score(theta):
+    ...     return np.array([np.sum(data - theta[0])])
+    >>> def fisher(theta):
+    ...     return np.array([[len(data)]])
+    >>> result = mle_scoring(log_lik, score, fisher, np.array([0.0]))
     """
     theta = np.asarray(theta_init, dtype=np.float64).copy()
 
@@ -729,6 +764,13 @@ def aic(log_likelihood: float, n_params: int) -> float:
     Notes
     -----
     AIC = -2 * log_likelihood + 2 * n_params
+
+    Examples
+    --------
+    >>> log_lik = -100.0
+    >>> n_params = 3
+    >>> aic(log_lik, n_params)
+    206.0
     """
     return -2 * log_likelihood + 2 * n_params
 
@@ -754,6 +796,12 @@ def bic(log_likelihood: float, n_params: int, n_samples: int) -> float:
     Notes
     -----
     BIC = -2 * log_likelihood + n_params * log(n_samples)
+
+    Examples
+    --------
+    >>> log_lik = -100.0
+    >>> bic(log_lik, n_params=3, n_samples=100)
+    213.81551055796427
     """
     return -2 * log_likelihood + n_params * np.log(n_samples)
 
@@ -780,6 +828,12 @@ def aicc(log_likelihood: float, n_params: int, n_samples: int) -> float:
     -----
     AICc adds a correction for small sample sizes:
     AICc = AIC + 2*k*(k+1)/(n-k-1)
+
+    Examples
+    --------
+    >>> log_lik = -50.0
+    >>> aicc(log_lik, n_params=3, n_samples=20)
+    109.5
     """
     k = n_params
     n = n_samples

pytcl/static_estimation/robust.py

@@ -99,6 +99,15 @@ def huber_weight(r: ArrayLike, c: float = 1.345) -> NDArray[np.floating]:
     The Huber weight function is:
         w(r) = 1           if |r| <= c
         w(r) = c / |r|     if |r| > c
+
+    Examples
+    --------
+    >>> r = np.array([0.5, 1.0, 2.0, 5.0])  # Standardized residuals
+    >>> w = huber_weight(r, c=1.345)
+    >>> w[0]  # Small residual gets weight 1
+    1.0
+    >>> w[3] < 0.5  # Large residual gets reduced weight
+    True
     """
     r = np.asarray(r, dtype=np.float64)
     abs_r = np.abs(r)
@@ -129,6 +138,13 @@ def huber_rho(r: ArrayLike, c: float = 1.345) -> NDArray[np.floating]:
     The Huber rho function is:
         rho(r) = r^2 / 2           if |r| <= c
         rho(r) = c * |r| - c^2/2   if |r| > c
+
+    Examples
+    --------
+    >>> r = np.array([0.5, 1.0, 2.0])
+    >>> rho = huber_rho(r, c=1.345)
+    >>> rho[0]  # Small residual: r^2/2
+    0.125
     """
     r = np.asarray(r, dtype=np.float64)
     abs_r = np.abs(r)
@@ -160,6 +176,15 @@ def tukey_weight(r: ArrayLike, c: float = 4.685) -> NDArray[np.floating]:
         w(r) = 0                 if |r| > c
 
     This provides complete rejection of large outliers.
+
+    Examples
+    --------
+    >>> r = np.array([0.5, 2.0, 5.0, 10.0])
+    >>> w = tukey_weight(r, c=4.685)
+    >>> w[0] > 0.9  # Small residual gets high weight
+    True
+    >>> w[3]  # Large residual completely rejected
+    0.0
     """
     r = np.asarray(r, dtype=np.float64)
     abs_r = np.abs(r)
@@ -190,6 +215,15 @@ def tukey_rho(r: ArrayLike, c: float = 4.685) -> NDArray[np.floating]:
     The Tukey rho function is:
         rho(r) = c^2/6 * (1 - (1 - (r/c)^2)^3)   if |r| <= c
         rho(r) = c^2/6                            if |r| > c
+
+    Examples
+    --------
+    >>> r = np.array([0.0, 2.0, 10.0])
+    >>> rho = tukey_rho(r, c=4.685)
+    >>> rho[0]  # Zero residual
+    0.0
+    >>> rho[2] == rho[2]  # Large residuals saturate at c^2/6
+    True
     """
     r = np.asarray(r, dtype=np.float64)
     abs_r = np.abs(r)
@@ -219,6 +253,15 @@ def cauchy_weight(r: ArrayLike, c: float = 2.385) -> NDArray[np.floating]:
     -----
     The Cauchy weight function is:
         w(r) = 1 / (1 + (r/c)^2)
+
+    Examples
+    --------
+    >>> r = np.array([0.0, 1.0, 5.0])
+    >>> w = cauchy_weight(r, c=2.385)
+    >>> w[0]  # Zero residual gets weight 1
+    1.0
+    >>> 0 < w[2] < 1  # Large residuals get reduced weight (but never zero)
+    True
     """
     r = np.asarray(r, dtype=np.float64)
     return 1 / (1 + (r / c) ** 2)
@@ -251,6 +294,13 @@ def mad(residuals: ArrayLike, c: float = 1.4826) -> float:
     MAD = c * median(|r - median(r)|)
 
     This is a robust scale estimator with 50% breakdown point.
+
+    Examples
+    --------
+    >>> residuals = np.array([1.0, 1.1, 0.9, 1.0, 100.0])  # One outlier
+    >>> scale = mad(residuals)
+    >>> scale < 1.0  # Robust to the outlier
+    True
     """
     r = np.asarray(residuals, dtype=np.float64)
     return c * float(np.median(np.abs(r - np.median(r))))
@@ -279,6 +329,13 @@ def tau_scale(
     Notes
     -----
     Tau scale combines high breakdown point with efficiency.
+
+    Examples
+    --------
+    >>> residuals = np.array([1.0, 1.1, 0.9, 1.0, 1.2, 100.0])  # One outlier
+    >>> scale = tau_scale(residuals)
+    >>> scale < 10.0  # Robust to the outlier
+    True
     """
     r = np.asarray(residuals, dtype=np.float64)
     n = len(r)

pytcl/terrain/dem.py

@@ -438,6 +438,19 @@ def get_elevation_profile(
         Array of distances from start in meters.
     elevations : ndarray
         Array of elevation values in meters.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> dem = create_flat_dem(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119),
+    ...     elevation=500)
+    >>> dists, elevs = get_elevation_profile(
+    ...     dem, np.radians(35.2), np.radians(-119.8),
+    ...     np.radians(35.8), np.radians(-119.2), n_points=10)
+    >>> len(dists) == 10
+    True
     """
     # Generate points along path
     lats = np.linspace(lat_start, lat_end, n_points)
@@ -492,6 +505,21 @@ def interpolate_dem(
     -------
     DEMGrid
         New interpolated DEM grid.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> dem = create_flat_dem(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119),
+    ...     elevation=100)
+    >>> new_dem = interpolate_dem(
+    ...     dem,
+    ...     np.radians(35.2), np.radians(35.8),
+    ...     np.radians(-119.8), np.radians(-119.2),
+    ...     new_n_lat=5, new_n_lon=5)
+    >>> new_dem.data.shape
+    (5, 5)
     """
     # Create new coordinate arrays
     new_lats = np.linspace(new_lat_min, new_lat_max, new_n_lat)
@@ -547,6 +575,22 @@ def merge_dems(
     -------
     DEMGrid
         Merged DEM grid.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> dem1 = create_flat_dem(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119), elevation=100)
+    >>> dem2 = create_flat_dem(
+    ...     np.radians(36), np.radians(37),
+    ...     np.radians(-120), np.radians(-119), elevation=200)
+    >>> merged = merge_dems(
+    ...     [dem1, dem2],
+    ...     np.radians(35), np.radians(37),
+    ...     np.radians(-120), np.radians(-119))
+    >>> merged.name
+    'Merged DEM'
     """
     # Compute output grid dimensions
     d_lat = np.radians(resolution_arcsec / 3600)
@@ -611,6 +655,19 @@ def create_flat_dem(
     -------
     DEMGrid
         Flat DEM grid.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> dem = create_flat_dem(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119),
+    ...     elevation=500)
+    >>> dem.name
+    'Flat DEM'
+    >>> result = dem.get_elevation(np.radians(35.5), np.radians(-119.5))
+    >>> abs(result.elevation - 500) < 1
+    True
     """
     d_lat = np.radians(resolution_arcsec / 3600)
     d_lon = np.radians(resolution_arcsec / 3600)
@@ -672,6 +729,18 @@ def create_synthetic_terrain(
     -------
     DEMGrid
         Synthetic terrain DEM.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> dem = create_synthetic_terrain(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119),
+    ...     base_elevation=500, amplitude=200, seed=42)
+    >>> dem.name
+    'Synthetic Terrain'
+    >>> dem.data.min() < dem.data.max()  # Has elevation variation
+    True
     """
     if seed is not None:
         np.random.seed(seed)

pytcl/terrain/visibility.py

@@ -160,6 +160,20 @@ def line_of_sight(
     The refraction coefficient models atmospheric bending of radio waves.
     A typical value for radio frequencies is 0.13 (4/3 Earth model).
     For optical line of sight, use 0.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.terrain.dem import create_flat_dem
+    >>> dem = create_flat_dem(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119), elevation=100)
+    >>> result = line_of_sight(
+    ...     dem,
+    ...     np.radians(35.3), np.radians(-119.7), 10,
+    ...     np.radians(35.7), np.radians(-119.3), 10)
+    >>> result.visible  # Clear LOS over flat terrain
+    True
     """
     # Effective Earth radius for refraction
     if refraction_coeff > 0:
@@ -296,6 +310,19 @@ def viewshed(
     -------
     ViewshedResult
         Viewshed computation result with visibility grid.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.terrain.dem import create_flat_dem
+    >>> dem = create_flat_dem(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119), elevation=100)
+    >>> result = viewshed(
+    ...     dem, np.radians(35.5), np.radians(-119.5), 20,
+    ...     max_range=10000, n_radials=36, samples_per_radial=10)
+    >>> result.visible.any()  # Some cells visible
+    True
     """
     # Convert max range to angular distance
     max_angular_range = max_range / earth_radius
@@ -428,6 +455,19 @@ def compute_horizon(
     -------
     list of HorizonPoint
         Horizon points for each azimuth direction.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.terrain.dem import create_flat_dem
+    >>> dem = create_flat_dem(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119), elevation=100)
+    >>> horizon = compute_horizon(
+    ...     dem, np.radians(35.5), np.radians(-119.5), 10,
+    ...     n_azimuths=8, max_range=10000, samples_per_radial=10)
+    >>> len(horizon)
+    8
     """
     max_angular_range = max_range / earth_radius
 
@@ -534,6 +574,18 @@ def terrain_masking_angle(
     -------
     float
         Masking angle in radians above horizontal.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.terrain.dem import create_flat_dem
+    >>> dem = create_flat_dem(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119), elevation=100)
+    >>> angle = terrain_masking_angle(
+    ...     dem, np.radians(35.5), np.radians(-119.5), 10, azimuth=0)
+    >>> -np.pi/2 <= angle <= np.pi/2  # Valid angle range
+    True
     """
     max_angular_range = max_range / earth_radius
 
@@ -628,6 +680,19 @@ def radar_coverage_map(
     -------
     ViewshedResult
         Radar coverage map.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.terrain.dem import create_flat_dem
+    >>> dem = create_flat_dem(
+    ...     np.radians(35), np.radians(36),
+    ...     np.radians(-120), np.radians(-119), elevation=100)
+    >>> coverage = radar_coverage_map(
+    ...     dem, np.radians(35.5), np.radians(-119.5), 30,
+    ...     max_range=20000, n_radials=36, samples_per_radial=20)
+    >>> coverage.visible.any()  # Some coverage exists
+    True
     """
     # Compute basic viewshed with refraction
     result = viewshed(

pytcl/trackers/hypothesis.py

@@ -208,6 +208,29 @@ def compute_association_likelihood(
     -------
     likelihood : float
         Joint likelihood of the association.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # 2 tracks, 2 measurements
+    >>> likelihood_matrix = np.array([[0.9, 0.1],
+    ...                                [0.1, 0.8]])
+    >>> # Association: track 0 -> meas 0, track 1 -> meas 1
+    >>> association = {0: 0, 1: 1}
+    >>> lik = compute_association_likelihood(
+    ...     association, likelihood_matrix,
+    ...     detection_prob=0.9, clutter_density=1e-6, n_meas=2
+    ... )
+    >>> lik > 0
+    True
+    >>> # Association with missed detection
+    >>> assoc_miss = {0: 0, 1: -1}  # track 1 misses
+    >>> lik_miss = compute_association_likelihood(
+    ...     assoc_miss, likelihood_matrix,
+    ...     detection_prob=0.9, clutter_density=1e-6, n_meas=2
+    ... )
+    >>> lik > lik_miss  # Full detection more likely
+    True
     """
     likelihood = 1.0
 
@@ -259,6 +282,31 @@ def n_scan_prune(
     committed_track_ids : set
         Track IDs that are now committed (survived N-scan).
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from pytcl.trackers.hypothesis import (
+    ...     Hypothesis, MHTTrack, MHTTrackStatus, n_scan_prune
+    ... )
+    >>> # Two hypotheses, tracks with different creation scans
+    >>> track1 = MHTTrack(id=0, state=np.zeros(2), covariance=np.eye(2),
+    ...                   score=1.0, status=MHTTrackStatus.CONFIRMED,
+    ...                   history=[0], parent_id=-1, scan_created=0,
+    ...                   n_hits=3, n_misses=0)
+    >>> track2 = MHTTrack(id=1, state=np.zeros(2), covariance=np.eye(2),
+    ...                   score=0.5, status=MHTTrackStatus.TENTATIVE,
+    ...                   history=[1], parent_id=-1, scan_created=2,
+    ...                   n_hits=1, n_misses=0)
+    >>> tracks = {0: track1, 1: track2}
+    >>> hyp1 = Hypothesis(id=0, probability=0.8, track_ids=[0],
+    ...                   scan_created=0, parent_id=-1)
+    >>> hyp2 = Hypothesis(id=1, probability=0.2, track_ids=[1],
+    ...                   scan_created=2, parent_id=-1)
+    >>> pruned, committed = n_scan_prune([hyp1, hyp2], tracks, n_scan=2,
+    ...                                   current_scan=3)
+    >>> len(pruned) >= 1
+    True
+
     Notes
     -----
     N-scan pruning works by:
@@ -338,6 +386,23 @@ def prune_hypotheses_by_probability(
     -------
     pruned : list of Hypothesis
         Pruned and renormalized hypotheses.
+
+    Examples
+    --------
+    >>> from pytcl.trackers.hypothesis import Hypothesis, prune_hypotheses_by_probability
+    >>> # 5 hypotheses with varying probabilities
+    >>> hyps = [
+    ...     Hypothesis(id=0, probability=0.5, track_ids=[0], scan_created=0, parent_id=-1),
+    ...     Hypothesis(id=1, probability=0.3, track_ids=[1], scan_created=0, parent_id=-1),
+    ...     Hypothesis(id=2, probability=0.1, track_ids=[2], scan_created=0, parent_id=-1),
+    ...     Hypothesis(id=3, probability=0.05, track_ids=[3], scan_created=0, parent_id=-1),
+    ...     Hypothesis(id=4, probability=1e-8, track_ids=[4], scan_created=0, parent_id=-1),
+    ... ]
+    >>> pruned = prune_hypotheses_by_probability(hyps, max_hypotheses=3)
+    >>> len(pruned)  # Only top 3 kept
+    3
+    >>> sum(h.probability for h in pruned)  # Renormalized to 1
+    1.0
     """
     if not hypotheses:
         return []