galpy.df.streamspraydf.streamTrack

streamspraydf.streamTrack(n=5000, particles=None, tail=None, track_time_range=None, ntp=None, smoothing=None, smoothing_factor=1.0, niter=0, order=2, velocity_weight='auto', custom_sky_transform=None)[source]

Construct a smooth phase-space track through the stream by sampling particles and projecting them onto a finely-integrated progenitor orbit.

The track is parameterized by the progenitor’s time coordinate tp: tp=0 is the progenitor today, tp<0 are past positions (matched by the trailing arm) and tp>0 are future positions (matched by the leading arm). Because stream particles have small velocity offsets from the progenitor, they lie spatially close to a short arc of the progenitor’s orbit — the relevant tp range is much smaller than tdisrupt.

Parameters:

  • n (int, optional) – Total number of particles to draw. When tail='both', n is split equally between leading and trailing (matching self.sample(n, ...)’s convention). Ignored if particles is provided. Default is 5000.

  • particles (array, shape (6, N), optional) – Pre-computed present-day (R, vR, vT, z, vz, phi) of stream particles. Use self.sample(returndt=False, return_orbit=False, integrate=True) to draw, or pass an externally-generated sample (e.g. from an N-body run). When tail='both', the array must follow the sample ordering (leading first, then trailing) and is split at N // 2. Default is None (sample freshly).

  • tail (str, optional) – One of 'leading', 'trailing', or 'both'. Defaults to the value set at initialization.

  • track_time_range (float or Quantity, optional) – Half-range (symmetric about tp=0) of the finely-integrated progenitor orbit used for closest-point matching. Default is data-driven: 8 * d_max / |v_prog| clamped to [1, tdisrupt], where d_max is the farthest particle’s distance from the progenitor.

  • ntp (int, optional) – Number of binning nodes. Default sqrt(N) with a floor of 21 and a ceiling that scales with the arc span (at least 201; larger for long streams).

  • smoothing (None, float, or array-like, optional) – Smoothing parameter(s). None (default) uses GCV auto-tuning. A float sets a single s for all coords. An array-like of length 6 (mean only) or 27 (mean + covariance) sets per-spline s values — pass a previous call’s track.smoothing_s to reproduce the same smoothness without re-running GCV.

  • smoothing_factor (float, optional) – Multiplier applied to every spline’s effective s after GCV (or explicit-s) selection. Values > 1 force a smoother fit, values < 1 a rougher one. Useful when GCV undersmooths in finite samples (a common failure mode of make_smoothing_spline on noisy binned means). Default 1.0. For an interactive smoothing sweep, save track.particles from the first call and pass it back as particles= — only the cheap re-fit step runs, the orbit-integration sample is reused.

  • niter (int, optional) – Iterations beyond the initial fit. Each iteration reassigns particles to the closest point on the current track.

  • order (int, optional) – 1 = mean only, 2 = mean + covariance (default).

  • velocity_weight (float or 'auto', optional) – Multiplicative weight applied to velocity components when computing 6D distances during the closest-point projection. Default 'auto' learns the weight from the inner-half particle dispersion (σ_pos / σ_vel, clipped to [0.1, 10]); typically lands at ~2–3 for both clean and perturbed streams. Values > 1 make velocity matches more important than position matches — useful when the progenitor orbit revisits regions of phase space (e.g., in strongly-perturbed potentials with a massive LMC). Pass 1.0 for the legacy unweighted natural-units metric.

Returns:

A single-arm track object, or a pair with .leading and .trailing tracks when tail='both'.

Return type:

galpy.df.StreamTrack or galpy.df.StreamTrackPair

Notes

  • 2026-04-14 - Written - Bovy (UofT)