Trace Analysis
Empirical trace handling and fitting.
The trace module provides utilities to load, characterise, and fit measured
traces (interarrival or service time samples) into the stochastic processes used
by LINE models.
Trace Utilities (line_solver.api.trace)
Trace Analysis Functions.
Native Python implementations for statistical analysis of empirical trace data including means, variances, correlations, and index of dispersion.
- Key functions:
trace_mean: Mean of trace data trace_var: Variance of trace data trace_scv: Squared coefficient of variation trace_acf: Autocorrelation function trace_summary: Comprehensive summary statistics
- trace_mean(trace)[source]
Compute the arithmetic mean of trace data.
- Parameters:
- Returns:
Mean value of the trace.
- Return type:
Example
>>> trace_mean([1.0, 2.0, 3.0, 4.0, 5.0]) 3.0
- trace_var(trace)[source]
Compute the variance of trace data.
Uses population variance (ddof=0) for consistency with the JAR.
- Parameters:
- Returns:
Variance of the trace.
- Return type:
Example
>>> trace_var([1.0, 2.0, 3.0, 4.0, 5.0]) 2.0
- trace_scv(trace)[source]
Compute the squared coefficient of variation (SCV).
SCV = Var(X) / E[X]^2
- Parameters:
- Returns:
Squared coefficient of variation.
- Return type:
Example
>>> trace_scv([1.0, 2.0, 3.0]) # Var=0.667, Mean=2, SCV=0.167
- trace_acf(trace, lags=None)[source]
Compute the autocorrelation function at specified lags.
- Parameters:
- Returns:
Array of autocorrelation values at each lag.
- Return type:
Example
>>> trace = np.random.randn(100) >>> acf = trace_acf(trace, [1, 2, 3])
- trace_gamma(trace, limit=1000)[source]
Estimate the autocorrelation decay rate of a trace.
- Parameters:
- Returns:
Array containing [GAMMA, RHO0, RESIDUALS].
- Return type:
Example
>>> gamma, rho0, residuals = trace_gamma(trace_data)
Mirrors trace_gamma.m: rho_k = RHO0 * gamma^k is fitted by ROBUST nonlinear least squares over the whole range of gamma, started at 0.99. MATLAB uses nlinfit with RobustWgtFun ‘fair’, whose weight 1/(1 + |r|/c) at the default tuning c = 1.4 is exactly the derivative of the fair loss passed to least_squares below, so the two minimize the same criterion. An unweighted fit is the fallback, as MATLAB falls back to lsqcurvefit.
- trace_iat2counts(trace, scale)[source]
Compute the counting process from inter-arrival times.
- Parameters:
- Returns:
Array of counts after scale units of time from each arrival.
- Return type:
Example
>>> iat = [0.5, 0.3, 0.8, 0.2, 0.4] >>> counts = trace_iat2counts(iat, 1.0)
- trace_idi(trace, kset, option=None, n=1)[source]
Compute the Index of Dispersion for Intervals.
- Parameters:
- Returns:
Tuple of (IDI values, support values).
- Return type:
Example
>>> idi, support = trace_idi(trace_data, [10, 20, 50])
- trace_idc(trace)[source]
Compute the Index of Dispersion for Counts.
Asymptotically equal to IDI.
Example
>>> idc = trace_idc(inter_arrival_times)
- trace_pmf(X)[source]
Compute the probability mass function of discrete data.
- Parameters:
- Returns:
Tuple of (PMF values, unique values).
- Return type:
Example
>>> pmf, values = trace_pmf([1, 2, 2, 3, 3, 3])
- trace_shuffle(trace)[source]
Shuffle trace data randomly.
- Parameters:
- Returns:
Shuffled trace array.
- Return type:
Example
>>> shuffled = trace_shuffle([1, 2, 3, 4, 5])
- trace_joint(trace, lag, order)[source]
Compute joint moments E[X^{k_1}_{i} * X^{k_2}_{i+j} * …].
- Parameters:
- Returns:
Joint moment value.
- Return type:
Example
>>> jm = trace_joint(trace, [0, 1], [1, 1]) # E[X_i * X_{i+1}]
- trace_iat2bins(trace, scale)[source]
Compute counts in bins with specified timescale.
- Parameters:
- Returns:
Tuple of (counts per bin, bin membership for each element).
- Return type:
Example
>>> counts, bins = trace_iat2bins(iat_data, 1.0)
- trace_summary(trace)[source]
Compute comprehensive summary statistics for a trace.
- Parameters:
- Returns:
Array containing [MEAN, SCV, MAD, SKEW, KURT, Q25, Q50, Q75, P95, MIN, MAX, IQR, ACF1, ACF2, ACF3, ACF4, IDC_SCV_RATIO].
- Return type:
Example
>>> summary = trace_summary(trace_data) >>> print(f"Mean: {summary[0]}, SCV: {summary[1]}")
- trace_bicov(trace, grid)[source]
Compute bicovariance of a trace.
Bicovariance measures third-order correlation structure at multiple lag combinations.
- Parameters:
- Returns:
bicov: Array of bicovariance values
bicov_lags: 2D array of lag combinations (each row is [1, i, j])
- Return type:
Tuple of (bicov, bicov_lags) where
Example
>>> trace = np.random.randn(1000) >>> bicov, lags = trace_bicov(trace, [1, 2, 3, 4, 5])
- mtrace_mean(trace, ntypes, types)[source]
Compute the mean of a trace, divided by types.
- Parameters:
- Returns:
Array containing the mean values for each type.
- Return type:
Example
>>> trace = [1.0, 2.0, 3.0, 4.0] >>> types = [0, 1, 0, 1] >>> means = mtrace_mean(trace, 2, types)
- mtrace_var(trace, ntypes, types)[source]
Compute the variance of a trace, divided by types.
- Parameters:
- Returns:
Array containing the variance values for each type.
- Return type:
Example
>>> var_by_type = mtrace_var(trace, 2, types)
- mtrace_count(trace, ntypes, types)[source]
Count elements per type in a trace.
- Parameters:
- Returns:
Array containing counts for each type.
- Return type:
Example
>>> counts = mtrace_count(trace, 2, types)
- mtrace_sigma(T, L)[source]
Compute one-step class transition probabilities from a marked trace.
Computes P(C_k = j | C_{k-1} = i) empirically from the trace.
- mtrace_sigma2(T, L)[source]
Compute two-step class transition probabilities from a marked trace.
Computes P(C_k = h | C_{k-1} = j, C_{k-2} = i) empirically.
- mtrace_cross_moment(T, L, k)[source]
Compute the k-th order moment of inter-arrival times between class pairs.
- mtrace_forward_moment(T, A, orders, norm=True)[source]
Compute forward moments of a marked trace.
Forward moment for class c is E[T_{k+1}^order | C_k = c].
- Parameters:
- Returns:
Matrix of shape (C, len(orders)) containing forward moments.
- Return type:
- mtrace_backward_moment(T, A, orders, norm=True)[source]
Compute backward moments of a marked trace.
Backward moment for class c is E[T_k^order | C_k = c].
- Parameters:
- Returns:
Matrix of shape (C, len(orders)) containing backward moments.
- Return type:
- mtrace_summary(T, L)[source]
Compute comprehensive summary statistics for a marked trace.
- Parameters:
- Returns:
M: First 5 aggregate moments
ACF: Autocorrelation for lags 1-100
F1, F2: Forward moments of order 1 and 2
B1, B2: Backward moments of order 1 and 2
C1, C2: Cross moments of order 1 and 2
Pc: Class probabilities
Pab: One-step transition probabilities
- Return type:
Dictionary containing
- mtrace_split(T, L)[source]
Split a multi-class trace into per-class traces.
For each class, computes inter-arrival times between consecutive events of that class.
- mtrace_joint(T, A, i)[source]
Compute class-dependent joint moments.
Computes E[(X^(a)_j)^i[0] * (X^(a)_{j+1})^i[1]] for all classes a.
- mtrace_moment(T, A, orders, after=False, norm=False)[source]
Compute class-dependent moments of a multi-class trace.
- mtrace_bootstrap(T, A, n_samples=100, seed=None)[source]
Generate bootstrap samples from a marked trace.
- mtrace_iat2counts(T, L, scale)[source]
Per-class counting processes of a marked trace: for each arrival, how many events of each class fall in the window of length
scalethat starts at that arrival.Port of the pure-MATLAB branch of
m3a/mtrace/mtrace_iat2counts.m. The windows are anchored at EVERY arrival, not at each class’s own arrivals, so the rows are aligned across classes and cross-class count covariances are well defined. The series is truncated at the first window that reaches the end of the trace, because from there on the counts are censored.