Theoretical description
What is it?
For tags placed on free-swimming animals, the tag axes will not generally coincide with the animal’s axes. The tag A and M data will therefore tell you how the tag, not the animal, is oriented. This can be corrected if you know the orientation of the tag on the animal, i.e., the pitch, roll and heading of the tag when the animal is horizontal and pointing north. Three steps are needed to do this: First the tag orientation on the whale is inferred by looking at accelerometer values when the animal is near the surface. The orientation may change if the tag moves or slides during a deployment and so we make an ‘orientation table’ that describes the sequence of orientations of the tag. This table is then used to convert tag frame measurements into animal frame
Technical description
Usage of tool
To infer the tag-to-animal orientation there are two existing tools: prh_predictor1 and prh_predictor2. Both tools predict the tag position on a diving animal parametrized by its pitch, roll and yaw (which we shall call p0, r0, and h0), the canonical angles between the principal axes of the tag and the animal. The tag orientation on the animal can change with time and these functions provide a way to estimate the orientation at the start and end of each suitable dive. In fact these functions provide a graphical interface showing the estimated tag-to-animal orientation throughout the deployment.
How to know which tool should be used?
- If the animal of your tag deployment rests horizontally at the surface (at least on average) and dives steeply away from the surface without an initial roll, then use
prh_predictor1. E.g. sperm whales and pilot whales. - If the animal of your tag deployment animal makes a sequence of short dives between respirations and that the animal remains upright (i.e., does not roll) during these shallow dives, then use
prh_predictor2. E.g. beaked whales and humpback whales.
We are going to see an example of each below.
prh_predictor1, pilot whale case study
PRH = prh_predictor1(P,A,TH,DIR)
prh_predictor1(P, A, sampling_rate = NULL, TH = 100, DIR = "descent")
Inputs:
- P. is a dive depth vector or sensor structure with units of m H2O.
A:A sensor data structure, anx3acceleration matrix with columns[ax ay az]or an acceleration sensor list (e.g., from readtag.R).Acan be in any consistent unit, e.g., g or m/s2.fs:The sampling rate of the sensor data in Hz (samples per second). This is only needed if A is not a sensor structure and if filtering is required. If A is a sensor data list, sampling_rate is obtained from its metadata (A.sampling_rate).TH: (optional) minimum dive depth threshold (default is 100m). Only the descents at the start of dives deeper than TH will be analysed (and the ascents at the end of dives deeper than TH if ALL is true).DIR: (optional) dive direction constraint. The default (and if DIR=0) is to only analyse descents as these tend to give better results. But if DIR=1, both descents and ascents are analysed.
Outputs:
PRH= [cue,p0,r0,h0,q] with a row for each dive edge analysed. cue is the time in second-since-tagon of the dive edge analysed. [p0,r0,h0] are the deduced tag orientation angles in radians. q is the quality indicator with a low value (e.g., <0.05) indicating that the data fit more consistently with the assumptions of the method.
Load and visuzlize data
Use load_nc to read testset5.nc which is from a pilot whale in the Canary Islands [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.
Plot the dive profile to choose the minimum dive depth threshold.
gm_file_path = testset5.nc
gm = load_nc(gm_file_path)
figure
plott(gm.P)
ylabel('Depth m')
pv_file_path <- system.file("extdata", "testset6.nc", package = 'tagtools', mustWork = TRUE)
xx <- load_nc(pv_file_path )
Expand to show figure …
How to choose the minimum dive depth threshold?
Seeing the dive profile we will choose 400 m as the minimum dive depth threshold.
For any other tag deployment you should choose the minimum dive depth threshold as the one that contains enough dives throughout the deployment so as to be able to identify tag movements but without including really shallow dives. This is because the deeper the dives, the more steep the animal is going to descend and therefore the more accurate the p0r0h0 will be estimated.
As you can see we have not set DIR and therefore this is set as the default to only use the descent phase of the dives. We will always start with this scenario which is simpler, and if we find that the tag moves within a dive or that we are not able to get a good orientation table by analysing only descents, then we will use also the ascent phase.
Expand to show figure …
As you can see in the figure above, a graphical interface will open showing the dive profile (top), the estimated tag-to-animal orientations throughout the deployment (middle panel), and the quality of these estimates (bottom panel).
In the middle panel, the blue, red and yellow dots show the p0, r0 and h0 estimates, respectively, at the start of each dive. A quality measure of <0.05 in the bottom panel indicates that the data fit well with the assumptions of the method. However, there are cases in which the data fit well with the assumptions of the method and the quality measure is higher than 0.05.
If the tag does not move on the animal from dive to dive, then p0, r0 and h0 should be fairly constant across dives. If they are not constant it can be due to a sudden change (e.g., the tag gets hit) or a slow movement of the tag on the animal. In this case it seems that there is a change in tag orientation between dives 6 and 7.
The prh_predictor1 tool automatically picks segments of data to analyse and you should check that it did this well, especially if the ‘quality’ number is >0.05. The 3rd dive has a slightly bad quality: position the mouse near one of the 3rd dive orientation points and type e to edit.
Expand to show figure …
A second window, like the one above, will appear in which the top panel shows the acceleration data in the tag frame for the current dive edge. Blue, red and yellow represent the x, y and z axis, respectively. The bottom panel shows the acceleration data after correction using the p0, r0 and h0 estimates printed above the panel. Two black rectangles show the data segments that have been chosen for analysis and these may need to be moved. The left-hand or ‘surface’ segment should be positioned just before the start of the dive. The right-hand or ‘dive’ segment should be just after the start of the dive. The surface segment should cover an interval of consistent surfacing behaviour (either logging or shallow diving). The dive segment should contain only roll-free steep diving, i.e., the blue and red lines (the x-and y-axes) should be close to -9.8 m/s2 and 0, respectively, in the lower panel. Both segments should cover an integer number of shallow dives or fluke strokes (see image below) Isn’t this last statement important for the tool to work better?. The segment edges are numbered 1 to 4 from the left. To change a segment, position the mouse where you want it to start or end and type the appropriate number (1 to 4). The segment will move and the p0, r0, h0 and quality will be re-calculated. When you are satisfied with the estimate quality, type q to return to the first figure.
We have modify the segments position as you can see in the image below, improving slightlz the quality, q = 0.05.
Expand to show figure …
Produce the orientation table.
We need to create an orientation table (OTAB) that summarizes the tag orientation on the animal as a function of time. Each row of the OTAB matrix describes the orientation of the tag on the animal over a time interval. If there are two moves, the OTAB will have three lines: the initial orientation and the orientation after each move, i.e.:
OTAB = [otab1;otab2;otab3]
Each row defines how the tag is oriented on the animal and has the form:
otabn = [t1,t2,p0,r0,h0]
where t1 and t2 are the start and end times of the move (in seconds-since-tag-on), and p0, r0, h0 are the new orientation Euler angles after the move (in radians). The initial orientation (i.e., the first row in the OTAB) always has t1=t2=0. For subsequent moves, if the move is instantaneous, use t2=t1. If the move is gradual, set t1 to the time at which the movement appears to start and set t2 to the time when the move appears to be complete.
Making the OTAB is a bit of a black art. prh_predictor1 is not infinitely precise and an apparent change of less than 10 degrees is probably not worth worrying about. We are going to assume there is just one move (i.e., during the 6th dive) in our pilot whale data.
Position the mouse over the blue (p0), red (r0) and yellow (h0) lines before the move and click the left button on each to get the angle (in degrees). Make the first OTAB line:
(This is the description we gave at the workshop in BCN, however, I do it sligthly different, so would like to know your opinion. When the tag does not move, but the p0r0h0 are slightly different from dive to dive, I took the average from the PRH output which is already in radians).
%in our case we got the following p0, r0 and h0 but you should write the ones you got!
p0=-47.8785;
r0=78,0054;
h0=-0.031;
otab1 = [0,0,[p0,r0,h0]*pi/180]
where p0, r0 and h0 are your readings. The pi/180 converts these into radians.
For the second OTAB line, read off the p0, r0 and h0 values after the move and decide when the move actually happens (let’s say it is a sudden move at the end of the dive, e.g., at 10100 seconds). Then: (This is the description we gave at the workshop in BCN, however, I do it sligthly different, so would like to know your opinion. When there is a movement, in order to know if this is a sudden movement or a gradual movement and if a sudden movement to know when this one exactly occurs I plot the norm2(A) and have a look at the signal.
For the second OTAB line, we know that there has been a tag movement between the start of dive 6 and the start of dive 7. In order to know if there is a gradual or a sudden movement and when this occurs, we will plot the norm of the accelerometer data. Have a look between 9300 and 10800 seconds, (start of dive 6 and the start of dive 7), and compare the magnitude of the signal within that period and also with the period before and after.
figure
plot((1:length(P.data))/fs,(norm2(A.data)))
hold on
plot((1:length(P.data))/fs,P.data/100)% we plot depth to better visualize the periods within a dive in the acceleration signal.
Expand to show figure …
In this particular case, there is not clear difference in the magnitude of the accelerometer signal. Thus, we cannot specify with confidence if this is a sudden or a continuous movement and when it occurs. This is because the tag moved in orientation but it did not get displaced forwards or backwards in the body.
A sudden slide movement can be detected as a sudden change in the magnitude of the accelerometer data, which will be bigger in tags located closer to the fluke versus closer to the centre of mass of the whale, near the dorsal fin. Dives during which sudden movement occurs but the time of the movement is unsure were not used for fine scale biomechanics’ or energetics analysis. (ref Lucia’s PhD).
As we cannot tell the type of movement and the time of it, for the second OTAB line, read off the p0, r0 and h0 values after the move (point 7, at the start of the 7th dive) and decide when the move actually happens (let’s say it is a sudden move at the end of the dive, e.g., at 10100 seconds). We will later check if this is a good option or not. Then:
%in our case we got the following p0, r0 and h0 but you should write the ones you got!
p0=61.2033;
r0=52.9211;
h0=37.3817;
otab2= [10100,10100,[p0,r0,h0]*pi/180]
dsfa <- dsf(beb$Aa)$fpk # estimated stroking rate in Hz
Finally, type ‘q’ to quit prh_predictor1 andmake the OTAB matrix:
Verify OTAB with tag-on animal pictures (optional)
Pictures showing the position of the tag on the whale are useful to compare with the prhpredictor results. For this it is crucial to know which is the front part of the tag and which one is the posterior part to visually estimate how many degrees the tag is off the x y and z alignment axis of the whale. For Dtags, the hydrophones are located in the anterior part and the posterior part is where the VHF antenna is located. In the picture below. This particular tag follows the left-hand rule (see below) and so, the orientation of the tag on the tagged pilot whale should be approximately: xx degrees pitch, xx degrees roll and xx degrees yaw. It would be great to have a picture of the tag on the whale and the time of it, if before or after the tag movement, to have a complete example.
You should check with your manufacturer and tag provider which hand-rule is programed within your devide, and so the one you should use.
Following the left-hand rule the dorso-ventral, longitudinal and lateral axes correspond to the thumb, fore and centre finger respectively placed as three mutually orthogonal axes with the thumb pointing upwards. A negative pitch means a forward pitch (front part of the tag down), a negative roll means right rolling (right part of the tag down) and a negative yaw means an anticlockwise rotation of the tag when viewed from above.
Following the right-hand rule, the dorso-ventral, longitudinal and lateral axes correspond to the thumb, fore and centre finger respectively placed as three mutually orthogonal axes with the thumb pointing downwards. A negative pitch means a backwards pitch (front part of the tag up), a negative roll means left rolling (left part of the tag down) and a negative yaw means an anticlockwise rotation of the tag when viewed from above.
For both rules, the direction of each finger indicates the positive direction along each axis. Rotations around the dorso-ventral axis are known as yawing (y), around the lateral axis as pitching (p) and around the longitudinal axis as rolling (r).
Maybe we can add a figure here. A simple version of Figure 4 from Cade et al 2021 https://animalbiotelemetry.biomedcentral.com/articles/10.1186/s40317-021-00256-w
Tag frame to animal frame
Use your OTAB to convert tag frame measurements (A or M) to animal frame:
For this particular database, only A is provided, but in case you want to also convert tag frame magnetometer measurements to animal frame, you could do so in a similar way,
Aa should now contain acceleration data like what would have been recorded by a tag aligned with the animal’s axes, i.e., in the animal frame.
Verification
The complexity of the tag orientation estimation process can lead to some errors due to poor data selection or to algorithm failures. Thus, after the sensor data in the body frame is produced, there are several consistency checks that need to be done to assure that the tag alignment was estimated correctly. By definition, pitch should be negative during all descent phases, positive during all ascent phases and the mean pitch at the surface should be 0. Assuming that there is negligible specific acceleration at low frequencies, the mean x- and y-axis of the body frame acceleration (Aw) during surfacing events should be close to zero, while the Aw z-axis should be close to 1g. During the descent phase the Aw x-axis hould become negative while the Aw-z axis approaches zero. During the ascent phase the opposite should occur, the Aw x-axis should become positive while the Aw-z axis reduces accordingly. Aw y-axis should vary around zero during the whole dive with more variability during the foraging phase.
Shall we also talk about the good negative correlation that should be between depth rate and pitch?
So, lets compute smoothpitch and smoothroll from Aa and plot them to check they make sense (see animal orientation tutorial for a greater explanation) and verify that we have achieved a good tag-whale alignement for the whole deployment:
%%%see dsf and animal orientation tutorial to better understand the code below.
dsfa = dsf(A)
fc = 0.70*dsfa %this is approximately 70% of the dsf (0.35 Hz)
Af = comp_filt(Aa, fc);
Alow = Af{1}; % low frequency A data
[smoothpitch,smoothroll]=a2pr(Alow);
figure;
plott(P,fs,smoothpitch*180/pi,fs, Aa,fs)
subplot(311);
ylabel('Depth')
subplot(312);
ylabel('Smoothpitch')
subplot(313);
ylabel('Aa')
legend({'x-axis','y-axis','z-axis'})
Expand to show figure …
The pitch and roll vectors are in radians (hence the *180/pi to covert to degrees) and have the same sampling rate as Aa. Zoom in to check if the animal is in a realistic orientation when it is at the surface.
Are you happy with your results?
All seems good, when descending pitch is negative and positive when ascending while at the surface pitch is around zero when the animal is doing small dives, but slightly positive when logging, see surfacing after dive 4th and 5th. It could be that the animal is logging with a slightly positive pitch. Aw, also loosk good with the fluke stroke signal in the x and z axis but almost none in the y axis.
We can see that we did not choose the momment fo the sudden movement correctly as at 10100 seconds, approx. 168.5 minutes, the values of pitch and Aa signal change completely.
If you feel like, improve your OTAB and perform this check again (hint: the pitch seems to start being wrong around minutes 160-161.5. But have in mind that finding the exact moment of the sudden or gradual movement may be quite difficult and at the end it may be better to dischard this 6th dive from further biomechanics and energetics analysis.
Save the data
When you are comfortable that the tag is well aligned to the animal frame, add the corrected data to the archive file:
There is no need to also save pitch and roll because these can be easily re-computed from Aa. The archive file should only contain source data or data that has been corrected. The orientation correction steps and the OTAB are stored in Aa, and so this information is saved automatically in your archive file.
prh_predictor2, Cuvier’s beaked whale case study
PRH = prh_predictor2(P,A,fs,MAXD)
prh_predictor1(P, A, sampling_rate = NULL, MAXD = 10)
Inputs:
- P. is a dive depth vector or sensor structure with units of m H2O.
A:A sensor data structure, anx3acceleration matrix with columns[ax ay az]or an acceleration sensor list (e.g., from readtag.R).Acan be in any consistent unit, e.g., g or m/s2.fs:The sampling rate of the sensor data in Hz (samples per second). This is only needed if A is not a sensor structure and if filtering is required. If A is a sensor data list, sampling_rate is obtained from its metadata (A.sampling_rate).- MAXD: (optional) maximum depth of near-surface dives. The default value is 10 m. This is used to find contiguous surface intervals suitable for analysis.
Outputs:
PRH= [cue,p0,r0,h0,q] with a row for each dive edge analysed. cue is the time in second-since-tagon of the dive edge analysed. [p0,r0,h0] are the deduced tag orientation angles in radians. q is the quality indicator with a low value (e.g., <0.05) indicating that the data fit more consistently with the assumptions of the method.
Load and visuzlize data
Use load_nc to read zc05_167a_extract.nc which is from a Cuvier’s beaked whale in the Ligurian sea [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.
Plot the dive profile to choose the minimum dive depth threshold.
zc_file_path = zc05_167a_extract.nc
zc = load_nc(zc_file_path)
figure
plott(zc.P,fs)
ylabel('Depth m')
pv_file_path <- system.file("extdata", "testset6.nc", package = 'tagtools', mustWork = TRUE)
xx <- load_nc(pv_file_path )
Expand to show figure …
How to choose MAXD?
I do not really get how it works!Also this deployment does not seem to have a tag movement at least from the cal file I have!
As you can see we have not set MAXD and therefore this is set as default of 10 m of maximum depth of near-surface dives, finding contiguous surface intervals suitable for analysis. We will always start with the default scenario.
Expand to show figure …
As you can see in the figure above, a graphical interface will open showing the dive profile (top), the estimated tag-to-animal orientations throughout the deployment (middle panel), and the quality of these estimates (bottom panel).
In the middle panel, the blue, red and yellow dots show the p0, r0 and h0 estimates, respectively, at the start of each dive. A quality measure of <0.05 in the bottom panel indicates that the data fit well with the assumptions of the method. However, there are cases in which the data fit well with the assumptions of the method and the quality measure is higher than 0.05.
If the tag does not move on the animal from dive to dive, then p0, r0 and h0 should be fairly constant across dives. If they are not constant it can be due to a sudden change (e.g., the tag gets hit) or a slow movement of the tag on the animal. In this case it seems that there is a change in tag orientation after the second deep dive.
The prh_predictor2 tool automatically picks segments of data to analyse and you should check that it did this well, especially if the ‘quality’ number is >0.05. All dives seem to have a good quality, q<0.05.
However, if you want to inspect any of the dives, you can go over the point and hit e for edit. Let’s have a look at the 8th point (at the end of the second dive)
Expand to show figure …
A second window, like the one above, will appear in which the top panel shows the acceleration data in the tag frame for the current dive edge. Blue, red and yellow represent the x, y and z axis, respectively. The bottom panel shows the acceleration data after correction using the p0, r0 and h0 estimates printed above the panel. One black rectangle shows the data segments that has been chosen for analysis and this may need to be moved. The ‘surface’ segment should be positioned just before the start of the dive and should cover an interval of consistent surfacing behaviour (either logging or shallow diving). The segment edges are numbered 1 to 2 from the left. To change a segment, position the mouse where you want it to start or end and type the appropriate number (1 to 2). The segment will move and the p0, r0, h0 and quality will be re-calculated. When you are satisfied with the estimate quality, type q to return to the first figure.
This example seems good so we do not need to modify anything.
But lest also inspect the last point, which seems a bit suspicious.
Expand to show figure …
The tag fells off just a few seconds after the end of the black box and therefore we should not trust the orietnation of a tag that is partially detached.
Produce the orientation table.
We need to create an orientation table (OTAB) that summarizes the tag orientation on the animal as a function of time. Each row of the OTAB matrix describes the orientation of the tag on the animal over a time interval. If there are two moves, the OTAB will have three lines: the initial orientation and the orientation after each move, i.e.:
OTAB = [otab1;otab2;otab3]
Each row defines how the tag is oriented on the animal and has the form:
otabn = [t1,t2,p0,r0,h0]
where t1 and t2 are the start and end times of the move (in seconds-since-tag-on), and p0, r0, h0 are the new orientation Euler angles after the move (in radians). The initial orientation (i.e., the first row in the OTAB) always has t1=t2=0. For subsequent moves, if the move is instantaneous, use t2=t1. If the move is gradual, set t1 to the time at which the movement appears to start and set t2 to the time when the move appears to be complete.
Making the OTAB is a bit of a black art. prh_predictor2 is not infinitely precise and an apparent change of less than 10 degrees is probably not worth worrying about. We are going to assume there is just one move (i.e., during the 2nd deep dive) in our pilot whale data.
Position the mouse over the blue (p0), red (r0) and yellow (h0) lines before the move and click the left button on each to get the angle (in degrees). Make the first OTAB line:
(This is the description we gave at the workshop in BCN, however, I do it sligthly different, so would like to know your opinion. When the tag does not move, but the p0r0h0 are slightly different from dive to dive, I took the average from the PRH output which is already in radians).
%in our case we got the following p0, r0 and h0 but you should write the ones you got!
p0=-36.7211;
r0=-2.3939;
h0=86.2056;
otab1 = [0,0,[p0,r0,h0]*pi/180]
where p0, r0 and h0 are your readings. The pi/180 converts these into radians.
For the second OTAB line, read off the p0, r0 and h0 values after the move and decide when the move actually happens (let’s say it is a gradual move between the begining and the end of the second deep dive). Then: (This is the description we gave at the workshop in BCN, however, I do it sligthly different, so would like to know your opinion. When there is a movement, in order to know if this is a sudden movement or a gradual movement and if a sudden movement to know when this one exactly occurs I plot the norm2(A) and have a look at the signal.
For the second OTAB line, we know that there has been a tag movement between the start and the end of the second deep dive. In order to know if there is a gradual or a sudden movement and when this occurs, we will plot the norm of the accelerometer data. Have a look between 10800 and 14100seconds, and compare the magnitude of the signal within that period and also with the period before and after.
figure
plot((1:length(P.data))/fs,(norm2(A.data)))
hold on
plot((1:length(P.data))/fs,P.data/100)% we plot depth to better visualize the periods within a dive in the acceleration signal.
Expand to show figure …
In this particular case, there is not clear difference in the magnitude of the accelerometer signal. Thus, we cannot specify with confidence if this is a sudden or a continuous movement and when it occurs. This is because the tag moved in orientation but it did not get displaced forwards or backwards in the body.
A sudden slide movement can be detected as a sudden change in the magnitude of the accelerometer data, which will be bigger in tags located closer to the fluke versus closer to the centre of mass of the whale, near the dorsal fin. Dives during which sudden movement occurs but the time of the movement is unsure were not used for fine scale biomechanics’ or energetics analysis. (ref Lucia’s PhD).
As we cannot tell the type of movement and the time of it, for the second OTAB line, read off the p0, r0 and h0 values after the move (point 8, at the end of the 2nd deep dive) and decide when the move actually happens (let’s say it is a gradual move between the begining and the end of the second deep dive, between seconds 10800 and 14100. We will later check if this is a good option or not. Then:
%in our case we got the following p0, r0 and h0 but you should write the ones you got!
p0=-67.2654;
r0=8.8369;
h0=107.257;
otab2= [10800 ,14100,[p0,r0,h0]*pi/180]
dsfa <- dsf(beb$Aa)$fpk # estimated stroking rate in Hz
Finally, type ‘q’ to quit prh_predictor1 andmake the OTAB matrix:
Verify OTAB with tag-on animal pictures (optional)
Pictures showing the position of the tag on the whale are useful to compare with the prhpredictor results. For this it is crucial to know which is the front part of the tag and which one is the posterior part to visually estimate how many degrees the tag is off the x y and z alignment axis of the whale. For Dtags, the hydrophones are located in the anterior part and the posterior part is where the VHF antenna is located. In the picture below. This particular tag follows the left-hand rule (see below) and so, the orientation of the tag on the tagged pilot whale should be approximately: xx degrees pitch, xx degrees roll and xx degrees yaw. It would be great to have a picture of the tag on the whale and the time of it, if before or after the tag movement, to have a complete example.
You should check with your manufacturer and tag provider which hand-rule is programed within your devide, and so the one you should use.
Following the left-hand rule the dorso-ventral, longitudinal and lateral axes correspond to the thumb, fore and centre finger respectively placed as three mutually orthogonal axes with the thumb pointing upwards. A negative pitch means a forward pitch (front part of the
tag down), a negative roll means right rolling (right part of the tag down) and a
negative yaw means an anticlockwise rotation of the tag when viewed from above.
Following the right-hand rule, the dorso-ventral, longitudinal and lateral axes correspond to the thumb, fore and centre finger respectively placed as three mutually orthogonal axes with the thumb pointing downwards. A negative pitch means a backwards pitch (front part of the tag up), a negative roll means left rolling (left part of the tag down) and a negative yaw means an anticlockwise rotation of the tag when viewed from above.
For both rules, the direction of each finger indicates the positive direction along each axis. Rotations around the dorso-ventral axis are known as yawing (y), around the lateral axis as pitching (p) and around the longitudinal axis as rolling (r).
Maybe we can add a figure here. A simple version of Figure 4 from Cade et al 2021 https://animalbiotelemetry.biomedcentral.com/articles/10.1186/s40317-021-00256-w
Tag frame to animal frame
Use your OTAB to convert tag frame measurements (A and M) to animal frame:
Aa = tag2animal(gm.A,OTAB)
Ma = tag2animal(gm.M,OTAB) ;
Aa <- tag2animal(gm$A,OTAB)
Ma <- tag2animal(gm$M,OTAB) ;
Aa and Ma should now contain acceleration and magnetometer data, respectively like what would have been recorded by a tag aligned with the animal’s axes, i.e., in the animal frame.
Verification
The complexity of the tag orientation estimation process can lead to some errors due to poor data selection or to algorithm failures. Thus, after the sensor data in the body frame is produced, there are several consistency checks that need to be done to assure that the tag alignment was estimated correctly. By definition, pitch should be negative during all descent phases, positive during all ascent phases and the mean pitch at the surface should be 0. Assuming that there is negligible specific acceleration at low frequencies, the mean x- and y-axis of the body frame acceleration (Aw) during surfacing events should be close to zero, while the Aw z-axis should be close to 1g. During the descent phase the Aw x-axis should become negative while the Aw-z axis approaches zero. During the ascent phase the opposite should occur, the Aw x-axis should become positive while the Aw-z axis reduces accordingly. Aw y-axis should vary around zero during the whole dive with more variability during the foraging phase.
Shall we also talk about the good negative correlation that should be between depth rate and pitch?
So, lets compute smoothpitch and smoothroll from Aa and plot them to check they make sense (see animal orientation tutorial for a greater explanation) and verify that we have achieved a good tag-whale alignement for the whole deployment:
%%%see dsf and animal orientation tutorial to better understand the code below.
dsfa = dsf(A)
fc = 0.70*dsfa %this is approximately 70% of the dsf (0.35 Hz)
Af = comp_filt(Aa, fc);
Alow = Af{1}; % low frequency A data
[smoothpitch,smoothroll]=a2pr(Alow);
figure;
plott(P,fs,smoothpitch*180/pi,fs, Aa,fs)
subplot(311);
ylabel('Depth')
subplot(312);
ylabel('Smoothpitch')
subplot(313);
ylabel('Aa')
legend({'x-axis','y-axis','z-axis'})
Expand to show figure …
The pitch and roll vectors are in radians (hence the *180/pi to covert to degrees) and have the same sampling rate as Aa. Zoom in to check if the animal is in a realistic orientation when it is at the surface.
Are you happy with your results?
All seems good, when descending pitch is negative and positive when ascending while at the surface pitch is around zero when the animal is doing small dives. Aw, also looks good with the fluke stroke signal in the x and z axis but almost none in the y axis.
We can see that during the surfacings of the last two shallow dives, pitch does not center at zero. We personally, will not use this data as the tag could be partially detached, really close in time to the tag off. To know if a tag is partially detached see Remove High Frequency Noise Due to Tag Vibration tutorial.
Save the data
When you are comfortable that the tag is well aligned to the animal frame, add the corrected data to the archive file:
There is no need to also save pitch and roll because these can be easily re-computed from Aa. The archive file should only contain source data or data that has been corrected. The orientation correction steps and the OTAB are stored in Aa, and so this information is saved automatically in your archive file.
Caveats
If the tag does not move on the animal from dive to dive then p0, r0 and h0 should be fairly constant across dives, i.e., the difference between p0, r0 and h0 before and after the dive should be less than 10 degrees. This is the expected maximum error of the inference method when the whale behaviour follows the assumptions closely.
The complexity of the tag orientation estimation process can lead to some errors due to poor data selection or to algorithm failures. Thus, after the sensor data in the body frame is produced, there are several consistency checks that need to be done to assure that the tag alignment was estimated correctly.