# Dominant Stride, Flap & Fluke Stroke Frequency

#### Usage

For the full theoretical description, refer to the dsf() technical description.

MATLAB
```[fpk, q] = dsf(A, sampling_rate, fc = NULL, Nfft = NULL, doplot = NULL)
```
R
```[fpk, q] <- dsf(A, sampling_rate, fc = NULL, Nfft = NULL, doplot = NULL)
```
###### Inputs
• `A:` Acceleration data (as an animal tag sensor data structure or a numeric matrix).
• `sampling_rate:` The sampling rate for A, in Hz. Only required if A is a matrix.
• `fc:` the cut-off frequency in Hz of the low-pass filter to be applied to A to eliminate high-frequency transients. Defaults to 5Hz.
• `Nfft:` the length of the Fast Fourier Transform used to compute spectrum levels.
• `doplot:` logical – whether or not to produce a plot.
###### Outputs
• `fpk:` The dominant stroke frequency (i.e., the peak frequency in the sum of the acceleration power spectra) in Hz.
• `q:` The quality of the peak measured by the peak power divided by the mean power of the spectra. q is between 0 and 1 with larger numbers indicating a clear peak.

#### Theoretical Description

Locomotion in many animals involves the oscillatory movement of limbs, fins or wings. The idea behind dominant stroke frequency is that animals tend to prefer a particular oscillation rate during routine transport. For the full theoretical description, refer to the dsf() technical explanation.

#### Technical Description

In this vignette, you will learn how to estimate the dominant stride, flap or fluke stroke frequency using the `dsf()` function over an interval in which propulsion is the main activity; this could be a complete dive, an interval of running, or of flapping flight. For the full technical description, refer to the dsf() technical explanation.

#### Verification

To verify that you have run `dsf()`correctly, just count how many full strokes occur in a period of time and use this to calculate how many strokes the animal performs in a second. For the full verification explanation, refer to the dsf() technical explanation.

#### Caveats

Although DSF is broadly similar across animals with similar size and locomotion style there can be significant variation within the same individual as well as within and across species. It is essential that the sampling rate of the sensor(s) used for computing the DSF is well above twice the highest stroke frequency of the animal. For the full caveats, refer to the dsf() technical explanation.

#### Load and Visualize the Test Data Set

Load the test dataset `testset1`, which belongs to the data recorded from a suction cup tag attached to the back of a beaked whale [Note]This dataset has already been converted from a source file that was offloaded from the tag into a NetCDF file. In doing so, some metadata was gleaned from the file and added to the data. Other metadata was added by hand.. This dataset is built into the tagtools package, so you can access it using `system.file`.

MATLAB
```bw_file_path = xxx
```
R
```bw_file_path <- system.file("extdata", "testset1.nc", package = 'tagtools', mustWork = TRUE)
```

Then use `plott()` to inspect it:

MATLAB
```plott(bw.P, bw.A, bw.M)
subplot(311)
ylabel('Depth')
subplot(312)
ylabel('Acc')
subplot(313)
ylabel('Mag')
legend({'x-axis','y-axis','z-axis'})
```
R
```plott(X = list(Depth = bw\$P, Acc = bw\$A, Mag = bw\$M))
```
MATLAB Output
R Output

This dataset contains a deep dive followed by a shallow dive. The dominant stroke frequency or “dsf” can be estimated using the `dsf()` function on a complete dive. We can also compare the dsf between different phases of the dive cycle, e.g., between descent and ascent phase where propulsion is the main activity [Note]It is common for animals to have a different dsf during the descent than the ascent phase, as an animal that encounters large forces (due to buoyancy), may respond by stroking faster..

#### Estimate the Dominant Stroke Frequency

For this example, we are going to estimate the dominant stroke frequency on a bout of steady swimming between minutes 35 and 42 in the sample data. If you want to find a bout of steady swimming in your own data, plot the triaxial acceleration data and look for something similar to the figure below [Note]See the theory section for a better understanding of animal locomotion and the dominant flap, stroke or stride frequency.:

MATLAB Output
R Output

Use `crop_to()` to pick out the accelerometer and magnetometer data (these could be either in the tag frame (`A` and `M`) or in the animal frame (`Aa` and `Ma`)) in that interval, in our case between minutes 35 and 42 in the data:

MATLAB
```Aseg= crop_to(bw.A,[35*60 42*60]);
Mseg= crop_to(bw.M,[35*60 42*60]);
```
R
```Aseg <- crop_to(X = bw\$A, tcues = c(35*60, 42*60))
Mseg <- crop_to(X = bw\$M, tcues = c(35*60, 42*60))
```

It’s also possible to plot the accelerometer and magnetometer along with the depth data over the segment to make sure you got the segment you wanted. Mimic the previous code to similarly crop the pressure (depth) data:

MATLAB
```Pseg = crop_to(P,[35*60 42*60]);
figure
plott(Pseg,Aseg,Mseg)
legend({'x-axis','y-axis','z-axis'})
```
R
```Dseg <- crop_to(X = bw\$P, tcues = c(35*60, 42*60))
plott(X = list(Depth = Dseg, Acc = Aseg, Mag = Mseg), interactive = TRUE)
```

Then, run `dsf()` on `Aseg` to get the mean stroking rate:

MATLAB
```dsfa = dsf(Aseg) % estimated stroking rate in Hz from the accelerometer data
dsfm = dsf(Mseg) % estimated stroking rate in Hz from the magnetometer data
```
R
```dsfa <- dsf(Aseg)\$fpk   # estimated stroking rate in Hz
dsfm <- dsf(Mseg)\$fpk   # another estimate
```

You could plot the power spectrum for the accelerometer and magnetometer segment data. To do so, run the dsf function again this time enabling the input argument doplot. Look at the figures generated:

MATLAB
```[fpk, q] = dsf(Aseg, sampling_rate = [], fc = [], Nfft = [], doplot = 1)
legend({'x-axis','y-axis','z-axis'})
```
R
```###missing!!!
```
MATLAB Output
R Output

These figures show the sum of the power spectrum for each axis with frequency (Hz) in the x axis and spectrum level in the y axis (m/s2 for accelerometer data and µT for the magnetometer data). You could zoom in the figures to see the frequency with the highest spectrum level, which roughly corresponds to the dsf.

#### Common Questions

Yes, they should be. The acceleration-based estimate is 0.3509, and the magnetometer-based estimate is 0.3489.

Locomotory movements in many animals involve cyclic variations in orientation as well as generation of specific acceleration. The orientation changes show up in both magnetometer and accelerometer while the specific acceleration only shows up in the accelerometer.

#### Further Resources

For a more in-depth explanation of the usage and inner workings of the `dsf()` tool, refer to the Technical Explanation of DSF.

For insight into the appropriate use of DSF in monitoring animal propulsion, refer to the Discussion on Gait Estimation and Analysis (coming soon).