Skip to content

solve errors in acceleration computation and adjust user guide #588

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JuleAdrian wants to merge 7 commits into
base: main
Choose a base branch
from
Open

solve errors in acceleration computation and adjust user guide #588

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7239b6f
solve errors in acceleration computation and adjust user guide
JuleAdrian Nov 4, 2026
7db436c
adjust user guide
JuleAdrian Nov 4, 2026
1e19032
adjust user guide
JuleAdrian Nov 4, 2026
b6f3d09
adjust formatting
JuleAdrian Nov 4, 2026
7587a81
adjust formatting
JuleAdrian Nov 4, 2026
ced1d54
adjust formatting
JuleAdrian Nov 4, 2026
de57a97
adjust formatting
JuleAdrian Nov 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 29 additions & 19 deletions notebooks/user_guide.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2670,6 +2670,7 @@
{
"cell_type": "markdown",
"metadata": {
"jp-MarkdownHeadingCollapsed": true,
"jupyter": {
"outputs_hidden": false
}
Expand All @@ -2679,41 +2680,50 @@
"\n",
"Compute the individual acceleration for each pedestrian.\n",
"\n",
"For computing the individuals' acceleration at a specific frame $a_i(t_k)$,\n",
"For computing the individuals' acceleration at a specific frame $a_i(t_k)$\n",
"a specific frame step ($n$) is needed.\n",
"Together with the {class}`trajectory data<trajectory_data.TrajectoryData>` $fps$ of\n",
"the trajectory data $fps$ the time frame $\\Delta t$ for\n",
"computing the speed becomes:\n",
"the trajectory data, the time frame $\\Delta t$ for\n",
"computing the speed and the acceleration becomes:\n",
"\n",
"$$\n",
"\\Delta t = 2 n / fps\n",
" \\Delta t = 2 n / fps\n",
"$$\n",
"\n",
"This time step describes how many frames before and after the current\n",
"position $X(t_k)$ are used to compute the movement.\n",
"These positions are called $X(t_{k+n})$, $X(t_{k-n})$\n",
"respectively.\n",
"\n",
"In order to compute the acceleration at time $t_k$, we first calculate the\n",
"displacements $\\bar{X}$ around $t_{k+n}$ and $t_{k-n}$:\n",
"The acceleration at time $t_k$ can be calculated from the speeds\n",
"$v(t_{k+n})$ and $v(t_{k-n})$:\n",
"\n",
"$$\n",
"\\bar{X}(t_{k+n}) = X(t_{k+2n}) - X(t_{k})\n",
" v(t_{k+n}) = \\bar{X}(t_{k+n}) / \\Delta t\n",
"$$\n",
"$$\n",
"\\bar{X}(t_{k-n}) = X(t_{k}) - X(t_{k-2n})\n",
" v(t_{k-n}) = \\bar{X}(t_{k-n}) / \\Delta t\n",
"$$\n",
"\n",
"The acceleration is then calculated from the difference of the displacements\n",
"using the displacements $\\bar{X}(t_{k+n})$ and $\\bar{X}(t_{k-n})$\n",
"during $\\Delta t$ around $t_{k+n}$ and $t_{k-n}$:\n",
"\n",
"$$\n",
"\\Delta\\bar{X}(t_k) = \\bar{X}(t_{k+n}) - \\bar{X}(t_{k-n})\n",
" \\bar{X}(t_{k+n}) = X(t_{k+2n}) - X(t_{k})\n",
"$$\n",
"$$\n",
" \\bar{X}(t_{k-n}) = X(t_{k}) - X(t_{k-2n})\n",
"$$\n",
"The acceleration $a_i(t_k)$ is then calculated from the difference of\n",
"the speeds divided by the time interval $\\Delta t$:\n",
"\n",
"divided by the square of the time interval $\\Delta t$:\n",
"\n",
"$$\n",
"a_i(t_k) = \\Delta\\bar{X}(t_k) / \\Delta t^{2}\n",
" a_i(t_k) = (v(t_{k+n}) - v(t_{k-n})) / \\Delta t\n",
"$$\n",
"which is simplified to\n",
"$$\n",
" a_i(t_k) = \\Delta\\bar{X}(t_k) / (\\Delta t^{2})\n",
"$$\n",
"using\n",
"$$\n",
" \\Delta\\bar{X}(t_k) = \\bar{X}(t_{k+n}) - \\bar{X}(t_{k-n})\n",
"$$\n",
"$$\n",
" \\Delta\\bar{X}(t_k) = X(t_{k+2n}) - 2*X(t_{k}) + X(t_{k-2n})\n",
"$$\n",
"\n",
"When getting closer to the start, or end of the trajectory data, it is not\n",
Expand Down
51 changes: 33 additions & 18 deletions pedpy/methods/acceleration_calculator.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,23 +30,27 @@ def compute_individual_acceleration(

For computing the individuals' acceleration at a specific frame
:math:`a_i(t_k)`, a specific frame step (:math:`n`) is needed.
Together with the
:attr:`~trajectory_data.TrajectoryData.frame_rate` of the trajectory data
:math:`fps` the time frame :math:`\Delta t` for computing the speed
becomes:
Together with the :attr:`~trajectory_data.TrajectoryData.frame_rate`
of the trajectory data :math:`fps` the time frame :math:`\Delta t`
for computing the speed and the acceleration becomes:

.. math::

\Delta t = 2 n / fps

This time step describes how many frames before and after the current
position :math:`X(t_k)` are used to compute the movement.
These positions are called :math:`X(t_{k+n})`, :math:`X(t_{k-n})`
respectively.
The acceleration at time :math:`t_k` can be calculated from the speeds
:math:`v(t_{k+n})` and :math:`v(t_{k-n})`:

In order to compute the acceleration at time :math:`t_k`, we first
calculate the displacements :math:`\bar{X}` around :math:`t_{k+n}` and
:math:`t_{k-n}`:
.. math::

v(t_{k+n}) = \bar{X}(t_{k+n}) / \Delta t

.. math::

v(t_{k-n}) = \bar{X}(t_{k-n}) / \Delta t

using the displacements :math:`\bar{X}(t_{k+n})` and :math:`\bar{X}(t_{k-n})`
during :math:`\Delta t` around :math:`t_{k+n}` and :math:`t_{k-n}`:

.. math::

Expand All @@ -56,18 +60,29 @@ def compute_individual_acceleration(

\bar{X}(t_{k-n}) = X(t_{k}) - X(t_{k-2n})

The acceleration is then calculated from the difference of the
displacements

The acceleration :math:`a_i(t_k)` is then calculated from the difference of
the speeds divided by the time interval :math:`\Delta t`:

.. math::

\Delta\bar{X}(t_k) = \bar{X}(t_{k+n}) - \bar{X}(t_{k-n})
a_i(t_k) = (v(t_{k+n}) - v(t_{k-n})) / \Delta t

divided by the square of the time interval :math:`\Delta t`:
which is simplified to

.. math::

a_i(t_k) = \Delta\bar{X}(t_k) / (\Delta t^{2})

using

.. math::

\Delta\bar{X}(t_k) = \bar{X}(t_{k+n}) - \bar{X}(t_{k-n})

.. math::

a_i(t_k) = \Delta\bar{X}(t_k) / \Delta t^{2}
\Delta\bar{X}(t_k) = X(t_{k+2n}) - 2*X(t_{k}) + X(t_{k-2n})


When getting closer to the start, or end of the trajectory data, it is not
Expand Down Expand Up @@ -298,7 +313,7 @@ def _compute_individual_acceleration(
components in x and y direction if compute_acceleration is True
"""
columns = [ID_COL, FRAME_COL, ACC_COL]
time_interval = movement_data.window_size / frame_rate
time_interval = 0.5 * movement_data.window_size / frame_rate

# Compute displacements in x and y direction
movement_data[["dd_x", "dd_y"]] = (
Expand All @@ -318,7 +333,7 @@ def _compute_individual_acceleration(
movement_data[ACC_COL] = (
np.dot(movement_data[["dd_x", "dd_y"]].to_numpy(), movement_direction)
/ np.linalg.norm(movement_direction)
/ time_interval**2
/ (time_interval**2)
)

if compute_acceleration_components:
Expand Down
18 changes: 9 additions & 9 deletions pedpy/methods/method_utils.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1002,8 +1002,8 @@ def _compute_movement_acceleration_exclude_border(
) -> pd.DataFrame:
"""Compute the individual movement in the time interval frame_step.

The movement is computed for the interval [frame - frame_step: frame +
frame_step], if one of the boundaries is not contained in the trajectory
The movement is computed for the interval [frame - 2 * frame_step: frame +
2 * frame_step], if one of the boundaries is not contained in the trajectory
frame these points will not be considered.

Args:
Expand All @@ -1022,16 +1022,16 @@ def _compute_movement_acceleration_exclude_border(
"""
df_movement = traj_data.data.copy(deep=True)

df_movement[START_POSITION_COL] = df_movement.groupby(by=ID_COL).point.shift(2 * frame_step)
df_movement["start_frame"] = df_movement.groupby(by=ID_COL).frame.shift(2 * frame_step)
df_movement[START_POSITION_COL] = df_movement.groupby(by=ID_COL).point.shift(-2 * frame_step)
df_movement["start_frame"] = df_movement.groupby(by=ID_COL).frame.shift(-2 * frame_step)
Comment on lines +1025 to +1026

@schroedtert schroedtert Nov 8, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

start and end are swapped. Start uses shift(-2n), which is the future, and end uses shift(2n), which is the past. Purely semantics, otherwise here and the speed movement calculation use different notations for start and end


df_movement[MID_POSITION_COL] = df_movement.groupby(by=ID_COL).point.shift(frame_step)
df_movement["mid_frame"] = df_movement.groupby(by=ID_COL).frame.shift(frame_step)
df_movement[MID_POSITION_COL] = df_movement.point
df_movement["mid_frame"] = df_movement.frame

df_movement[END_POSITION_COL] = df_movement.point
df_movement["end_frame"] = df_movement.frame
df_movement[END_POSITION_COL] = df_movement.groupby(by=ID_COL).point.shift(2 * frame_step)
df_movement["end_frame"] = df_movement.groupby(by=ID_COL).frame.shift(2 * frame_step)

df_movement[WINDOW_SIZE_COL] = df_movement.end_frame - df_movement.mid_frame
df_movement[WINDOW_SIZE_COL] = df_movement.end_frame - df_movement.start_frame

@schroedtert schroedtert Nov 8, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is where window_size becomes −4n.

@JuleAdrian JuleAdrian Nov 12, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this is natural because we use the speed difference (each speed calculated using delta_t=2n/fps) between two time points which are delta_t=2n/fps apart as explained in the doctoring/user guide:
a(t_k)=(v(t_k+n) - v(t_k-n)) / (2n/fps)
with v(t_k+n) = (x(t_k+2n) - x(t_k)) / (2n/fps)
and v(t_k-n) = (x(t_k) - x(t_k-2n)) / (2n/fps).
So, it is consistent that the parameter frame_step in the same way (when computing speed or acceleration). I tried to make this clear in the explanations, but I can try to improve the explanation further.

return df_movement[
[
ID_COL,
Expand Down
Loading