Averager Module

averager: Averaging Functions for Time Series

This module provides tools for computing averaged quantities from time series data, with a focus on action-angle variables in galactic dynamics. It implements mean-preserving spline interpolation and extrema-based averaging methods.

Main Functions

value(t, x, **kwargs)

Average a time series between its extrema points. Supports different averaging types and can return minima, maxima, frequency, and phase angle.

action(t, xv, act=None, **kwargs)

Calculate averaged action-angle variables from orbital trajectories. Can compute secular variations, frequency derivatives, and bar-specific quantities.

Helper Functions

find_peaks_with_limitations(t, x, **kwargs)

Find peaks in a time series with optional filtering to remove spurious peaks based on frequency and amplitude criteria.

galport.averager.action(t, xv, act=None, dJdt=False, secular=False, secular_extrema=False, secular_act_freq=False, secular_bar_var=False, border_type='apocenters', JR_ilr=True, positive_omega=True, apply_apo_filter=True, freq_ratio_lim=1.4, value_ratio_lim=0.1, spline_expansion=100)[source]

Calculate averaged action-angle variables from orbital trajectories.

This function processes time series of positions and velocities to compute averaged actions, angles, and frequencies. It can also extract secular (long-term) variations and various derived quantities.

Parameters:

  • t ((N,) numpy array) – Array of time values.

  • xv ((N, 6) numpy array) – Array of phase-space coordinates [x, y, z, vx, vy, vz] at each time step.

  • act ((N, 3) numpy array, optional) – Array of instantaneous actions [JR, Jz, Lz] from Agama. If not provided, actions will be computed internally. Default: None

  • dJdt (bool, optional) – If True, calculate time derivatives of actions (dJR/dt, dJz/dt, dLz/dt). Default: False

  • secular (bool, optional) – If True, calculate secular (long-term) actions and frequencies. Default: False

  • secular_extrema (bool, optional) – If True, calculate secular maxima and minima of averaged actions and frequencies. Default: False

  • secular_act_freq (bool, optional) – If True, calculate oscillation frequencies of secular actions. Default: False

  • secular_bar_var (bool, optional) –

    If True, calculate bar-specific variables:

    • Jv = JR + Jz + Lz/2 (adiabatic invariant),

    • Ωpr = Ω - κ/2 (secular precession rate),

    • dLz/dΩpr (Lynden-Bell derivative).

    Default: False

  • border_type (str, optional) –

    Border processing parameter. Options:

    • apocenters : calculation between first and last apocenters

    • nbody : calculation between t=0 and last apocenter

    • secular : for secular variation calculations

    Default: ‘apocenters’

  • JR_ilr (bool, optional) – If True, adjust JR for ILR by adding -Lz when Lz < 0. Default: True

  • positive_omega (bool, optional) – If True, always calculate average angular velocity as a positive value (the angle between apocenters is measured in the positive direction). Default: True

  • apply_apo_filter (bool, optional) – If True, apply frequency and amplitude filters to remove spurious apocenters. Default: True

  • freq_ratio_lim (float, optional) – Lower limit on the ratio of frequencies for apocenter filtering. Used when apply_apo_filter=True. Default: 1.4

  • value_ratio_lim (float, optional) – Lower limit on the value ratio for apocenter filtering. Used when apply_apo_filter=True. Default: 0.1

  • spline_expansion (int, optional) – Factor by which to increase the resolution for finding extrema using cubic spline interpolation. Default: 100

Returns:

result – 2D array of shape (len(t), n_values) where n_var depends on the selected options (ranges from 9 to 36). The columns are organized as:

Index

Name

Description

Condition

0

JR

radial action

always

1

Jz

vertical action

always

2

Lz

angular momentum

always

3

dJR/dt

time derivative of radial action

dJdt=True

4

dJz/dt

time derivative of vertical action

dJdt=True

5

dLz/dt

time derivative of angular momentum

dJdt=True

6

θR

radial angle

always

7

θz

vertical angle

always

8

θφ

azimuthal angle

always

9

κ

radial frequency

always

10

ωz

vertical frequency

always

11

Ω

azimuthal frequency

always

12

JR_sec

secular radial action

secular=True

13

Jz_sec

secular vertical action

secular=True

14

Lz_sec

secular angular momentum

secular=True

15

κ_sec

secular radial frequency

secular=True

16

ωz_sec

secular vertical frequency

secular=True

17

Ω_sec

secular azimuthal frequency

secular=True

18-20

JR_max, Jz_max, Lz_max

secular maxima

secular_extrema=True

21-23

JR_min, Jz_min, Lz_min

secular minima

secular_extrema=True

24-26

κ_max, ωz_max, Ω_max

secular frequency maxima

secular_extrema=True

27-29

κ_min, ωz_min, Ω_min

secular frequency minima

secular_extrema=True

30

ΩJR

oscillation frequency of JR

secular_act_freq=True

31

ΩJz

oscillation frequency of Jz

secular_act_freq=True

32

ΩLz

oscillation frequency of Lz

secular_act_freq=True

33

Jv

adiabatic invariant (JR+Jz+Lz/2)

secular_bar_var=True

34

Ωpr

secular precession rate (Ω-κ/2)

secular_bar_var=True

35

dLz/dΩpr

Lynden-Bell derivative

secular_bar_var=True

Return type:

(N, n_var) numpy array

Notes

The function uses mean-preserving spline interpolation to compute averaged quantities between orbital turning points (apocenters or z-maxima). The number of output columns depends on which options are enabled.

galport.averager.find_peaks_with_limitations(t, x, apply_filter=False, freq_ratio_lim=1.4, value_ratio_lim=0.1, minmax=False)[source]

Find peaks in a time series with optional filtering to remove spurious peaks based on frequency and amplitude criteria.

Parameters:

  • t ((N,) numpy array) – Array of time values.

  • x ((N,) numpy array) – Array of values to find peaks in.

  • apply_filter (bool, optional) – Whether to apply filtering conditions to remove spurious peaks. If True, peaks are filtered based on frequency ratio and value ratio criteria. Default: True

  • freq_ratio_lim (float, optional) – Lower limit on the ratio of frequencies between consecutive peaks. A peak is considered spurious if its instantaneous frequency differs from neighbors by more than this factor. Specifically: freq_i > freq_ratio_lim * freq_{i+1} AND freq_i > freq_ratio_lim * freq_{i-1} Default: 1.4

  • value_ratio_lim (float, optional) – Lower limit on the value ratio for peak filtering. A peak is considered spurious if the amplitude variation between consecutive extrema is below this threshold. Calculated as: 2 * (|x_max| - |x_min|) / (|x_max| + |x_min|) < value_ratio_lim Default: 0.1

  • minmax (bool, optional) – If True, also return indices and values of minima. Default: False

Returns:

  • n_max ((M, ) numpy array) – 1D integer array of indices where maxima occur.

  • x_max ((M, ) numpy array) – 1D array of maximum values at the identified peak indices.

  • If minmax=True, additionally returns

  • n_min ((L, )numpy array (optional)) – 1D integer array of indices where minima occur.

  • x_min ((L, ) numpy array (optional)) – 1D array of minimum values at the identified minima indices.

galport.averager.value(t, x, average_type='extrema', border_type='apocenters', minmax=False, frequency=False, angle=False, spline_expansion=100, apply_filter=False, freq_ratio_lim=1.4, value_ratio_lim=0.1)[source]

Average a time series between its extrema points.

This function computes averaged values of a time series by identifying extrema (maxima and minima) and averaging between them. Various averaging methods are available, and additional quantities like frequency and angle can be computed.

Parameters:

  • t ((N,) numpy array) – Array of time values.

  • x ((N,) numpy array) – Array of values to be averaged.

  • average_type (str, optional) –

    Type of averaging to perform. Options: - extrema : average between successive maxima and minima - mean : compute mean values separately for maxima and minima intervals,

    then average them

    • onlymax : average only between maxima intervals

    Default: ‘extrema’

  • border_type (str, optional) –

    Border processing parameter. Options:

    • apocenters : calculation between first and last extrema

    • nbody : calculation between t=0 and last extrema

    • secular : for secular variation calculations

    Default: ‘apocenters’

  • minmax (bool, optional) – If True, also return the minima and maxima values as functions of time. Default: False

  • frequency (bool, optional) – If True, compute the frequency of oscillation between extrema. Default: False

  • angle (bool, optional) – If True, compute the phase angle of oscillation. Default: False

  • spline_expansion (int, optional) – Factor by which to increase the resolution for finding extrema using cubic spline interpolation. Higher values give more accurate extrema detection but increase computation time. Default: 100

  • apply_filter (bool, optional) – If True, apply frequency and amplitude filters to remove spurious extrema. Default: False

  • freq_ratio_lim (float, optional) – Lower limit on the ratio of frequencies for extrema filtering. An extremum is considered spurious if its frequency differs from neighbors by more than this factor. Used when apply_filter=True. Default: 1.4

  • value_ratio_lim (float, optional) – Lower limit on the value ratio for extrema filtering. An extremum is considered spurious if the amplitude variation between consecutive extrema is below this threshold. Calculated as: 2*(|x_max| - |x_min|)/(|x_max| + |x_min|) < value_ratio_lim Used when apply_filter=True. Default: 0.1

Returns:

result – 2D array of shape (len(t), n_var) where n_var depends on the selected options. The columns are organized as:

Index

Name

Description

Condition

0

x_avg

Time-averaged value between extrema

always

1

x_min

Minimum values interpolated in time

minmax=True

2

x_max

Maximum values interpolated in time

minmax=True

3

f

Oscillation frequency

frequency=True

4

φ

Oscillation phase angle

angle=True

Return type:

(N, n_var) numpy array