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

pytcl/navigation/rhumb.py

@@ -263,6 +263,15 @@ def indirect_rhumb_spherical(
     -------
     RhumbResult
         Distance and constant bearing.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> lat1, lon1 = np.radians(40), np.radians(-74)  # New York
+    >>> lat2, lon2 = np.radians(51), np.radians(0)   # London
+    >>> result = indirect_rhumb_spherical(lat1, lon1, lat2, lon2)
+    >>> result.distance > 5000000  # Over 5000 km
+    True
     """
     distance = rhumb_distance_spherical(lat1, lon1, lat2, lon2, radius)
     bearing = rhumb_bearing(lat1, lon1, lat2, lon2)
@@ -354,6 +363,15 @@ def rhumb_distance_ellipsoidal(
     -------
     float
         Rhumb line distance in meters.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> lat1, lon1 = np.radians(40), np.radians(-74)
+    >>> lat2, lon2 = np.radians(51), np.radians(0)
+    >>> dist = rhumb_distance_ellipsoidal(lat1, lon1, lat2, lon2)
+    >>> dist > 5000000  # Over 5000 km
+    True
     """
     a = ellipsoid.a
     e2 = ellipsoid.e2
@@ -419,6 +437,15 @@ def indirect_rhumb(
     -------
     RhumbResult
         Distance and constant bearing.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> lat1, lon1 = np.radians(40), np.radians(-74)  # New York
+    >>> lat2, lon2 = np.radians(51), np.radians(0)   # London
+    >>> result = indirect_rhumb(lat1, lon1, lat2, lon2)
+    >>> 0 < result.bearing < np.pi  # Eastward bearing
+    True
     """
     distance = rhumb_distance_ellipsoidal(lat1, lon1, lat2, lon2, ellipsoid)
 
@@ -460,6 +487,15 @@ def direct_rhumb(
     -------
     RhumbDirectResult
         Destination latitude and longitude.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> lat, lon = np.radians(40), np.radians(-74)
+    >>> bearing = np.radians(90)  # Due east
+    >>> dest = direct_rhumb(lat, lon, bearing, 100000)  # 100 km
+    >>> np.degrees(dest.lon) > -74  # Moved east
+    True
     """
     a = ellipsoid.a
     e2 = ellipsoid.e2
@@ -534,6 +570,17 @@ def rhumb_intersect(
     RhumbIntersectionResult
         Intersection point and validity flag.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> lat1, lon1 = np.radians(40), np.radians(-74)
+    >>> lat2, lon2 = np.radians(51), np.radians(0)
+    >>> bearing1 = np.radians(45)
+    >>> bearing2 = np.radians(270)
+    >>> result = rhumb_intersect(lat1, lon1, bearing1, lat2, lon2, bearing2)
+    >>> result.valid  # May or may not intersect
+    True
+
     Notes
     -----
     Unlike great circles, two rhumb lines may not intersect (if bearings
@@ -612,6 +659,15 @@ def rhumb_midpoint(
     -------
     RhumbDirectResult
         Midpoint latitude and longitude.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> lat1, lon1 = np.radians(0), np.radians(0)
+    >>> lat2, lon2 = np.radians(10), np.radians(10)
+    >>> mid = rhumb_midpoint(lat1, lon1, lat2, lon2)
+    >>> np.isclose(np.degrees(mid.lat), 5, atol=0.1)
+    True
     """
     result = indirect_rhumb_spherical(lat1, lon1, lat2, lon2)
     return direct_rhumb_spherical(lat1, lon1, result.bearing, result.distance / 2)
@@ -643,6 +699,15 @@ def rhumb_waypoints(
     -------
     lats, lons : ndarray
         Arrays of waypoint latitudes and longitudes in radians.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> lat1, lon1 = np.radians(40), np.radians(-74)
+    >>> lat2, lon2 = np.radians(51), np.radians(0)
+    >>> lats, lons = rhumb_waypoints(lat1, lon1, lat2, lon2, 5)
+    >>> len(lats)
+    5
     """
     result = indirect_rhumb_spherical(lat1, lon1, lat2, lon2, radius)
 
@@ -685,6 +750,15 @@ def compare_great_circle_rhumb(
         Rhumb line distance in meters.
     difference_percent : float
         Percentage difference (rhumb is longer).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> lat1, lon1 = np.radians(40), np.radians(-74)  # NYC
+    >>> lat2, lon2 = np.radians(51), np.radians(0)   # London
+    >>> gc, rhumb, diff = compare_great_circle_rhumb(lat1, lon1, lat2, lon2)
+    >>> rhumb > gc  # Rhumb is always longer
+    True
     """
     from pytcl.navigation.great_circle import great_circle_distance
 

pytcl/performance_evaluation/estimation_metrics.py

@@ -140,6 +140,14 @@ def velocity_rmse(
     -------
     float
         Velocity RMSE.
+
+    Examples
+    --------
+    >>> # State = [x, vx, y, vy], velocities are indices [1, 3]
+    >>> true = np.array([[0, 10, 0, 5], [1, 10, 0.5, 5]])
+    >>> est = np.array([[0, 9.5, 0, 5.2], [1, 10.2, 0.5, 4.9]])
+    >>> velocity_rmse(true, est, [1, 3])  # doctest: +SKIP
+    0.316...
     """
     true_vel = true_states[:, velocity_indices]
     est_vel = estimated_states[:, velocity_indices]
@@ -216,6 +224,15 @@ def nees_sequence(
     -------
     ndarray
         NEES values for each time step, shape (N,).
+
+    Examples
+    --------
+    >>> true = np.array([[1.0, 2.0], [1.5, 2.5]])
+    >>> est = np.array([[1.1, 1.9], [1.6, 2.4]])
+    >>> P = np.array([np.eye(2) * 0.1, np.eye(2) * 0.1])
+    >>> nees_vals = nees_sequence(true, est, P)
+    >>> len(nees_vals)
+    2
     """
     N = true_states.shape[0]
     nees_values = np.zeros(N)
@@ -247,6 +264,15 @@ def average_nees(
     -------
     float
         Average NEES (should be close to state_dim for consistent filter).
+
+    Examples
+    --------
+    >>> true = np.array([[1.0, 2.0], [1.5, 2.5], [2.0, 3.0]])
+    >>> est = np.array([[1.1, 1.9], [1.6, 2.4], [2.1, 2.9]])
+    >>> P = np.array([np.eye(2) * 0.1] * 3)
+    >>> avg = average_nees(true, est, P)
+    >>> avg  # Should be close to state_dim=2 for consistent filter
+    0.2
     """
     return float(np.mean(nees_sequence(true_states, estimated_states, covariances)))
 
@@ -279,6 +305,13 @@ def nis(
 
     where nu = z - H*x_pred is the innovation and S is the innovation
     covariance.
+
+    Examples
+    --------
+    >>> nu = np.array([0.5, -0.3])  # Innovation vector
+    >>> S = np.eye(2) * 0.25  # Innovation covariance
+    >>> nis(nu, S)
+    1.36
     """
     innovation = np.asarray(innovation)
     innovation_covariance = np.asarray(innovation_covariance)
@@ -305,6 +338,14 @@ def nis_sequence(
     -------
     ndarray
         NIS values for each time step.
+
+    Examples
+    --------
+    >>> innovations = np.array([[0.5, -0.3], [0.2, 0.1]])
+    >>> S = np.array([np.eye(2) * 0.25, np.eye(2) * 0.25])
+    >>> nis_vals = nis_sequence(innovations, S)
+    >>> len(nis_vals)
+    2
     """
     N = innovations.shape[0]
     nis_values = np.zeros(N)
@@ -395,6 +436,15 @@ def credibility_interval(
     -------
     float
         Fraction of errors within the interval.
+
+    Examples
+    --------
+    >>> rng = np.random.default_rng(42)
+    >>> errors = rng.normal(0, 0.1, (100, 2))  # Small errors
+    >>> P = np.array([np.eye(2) * 0.1] * 100)  # Matching covariance
+    >>> frac = credibility_interval(errors, P, interval=0.95)
+    >>> frac > 0.9  # Most errors within interval
+    True
     """
     N = len(errors)
     state_dim = errors.shape[1]
@@ -430,6 +480,16 @@ def monte_carlo_rmse(
     -------
     ndarray
         RMSE values.
+
+    Examples
+    --------
+    >>> # 3 Monte Carlo runs, 2 time steps, 2 state components
+    >>> errors = np.array([[[0.1, 0.2], [0.15, 0.1]],
+    ...                    [[0.05, 0.1], [0.2, 0.15]],
+    ...                    [[0.15, 0.05], [0.1, 0.2]]])
+    >>> rmse_per_time = monte_carlo_rmse(errors, axis=0)
+    >>> rmse_per_time.shape
+    (2, 2)
     """
     return np.sqrt(np.mean(errors**2, axis=axis))
 
@@ -453,6 +513,16 @@ def estimation_error_bounds(
     ndarray
         Error bounds (standard deviations) for each component,
         shape (N, state_dim).
+
+    Examples
+    --------
+    >>> P = np.array([[[1.0, 0], [0, 4.0]],
+    ...               [[0.25, 0], [0, 1.0]]])
+    >>> bounds = estimation_error_bounds(P, sigma=2.0)
+    >>> bounds[0]  # 2-sigma bounds: 2*sqrt(1), 2*sqrt(4)
+    array([2., 4.])
+    >>> bounds[1]  # 2-sigma bounds: 2*sqrt(0.25), 2*sqrt(1)
+    array([1., 2.])
     """
     # Extract diagonal elements (variances)
     variances = np.diagonal(covariances, axis1=1, axis2=2)

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)