After going through the technical explanation converting tag data into a NetCDF file, we hope we have convinced you about the benefits of this file format. Thus, if you have mat files from Dtag (versions 1, 2 and 3) deployments and you want to convert them into the .nc format, it is really easy if you follow these next steps. This tutorial is specific for Dtag deployments from Dtag version 3 (for Dtag version 1 and 2 the first step when loading the data is the different one).
Load the Test Data Set
For this practical we will use data from a suction cup tag attached to the back of a blue whale animal [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. The tag data name follows the standard DTAG protocol of: 2-letter Latin or common species initials, 2-digit
year, underscore, 3-digit Julian day of year, 1-letter animal of the day, e.g.:
bw_file_path = xxx %with a tage name of the type bw14_217aprh25.mat
bw = load(xx_file_path)
depid = 'bw14_217aprh25' ; %tag data following the standard DTAG protocol
Create sensor structures
Then convert the data matrices into sensor structures:
A = sens_struct(A,fs,'xx','acc')
P = sens_struct(p,fs,'xx','press')
M = sens_struct(M,fs,'xx','mag')
Aa = sens_struct(Aw,fs,'xx','acc')
Ma = sens_struct(Mw,fs,'xx','mag')
Indicate in the metadata that the accelerometer and magnetometer data are in the animal frame:
Load CAL file add information about cropped data and create metadata info structure
Load the cal file which contains information about the deployment that we will save in the metadata info structure:
bw14_cal_file_path = xxx %with a tage name of the type bw14_217acal.xml
bw14_cal = uiopen('bw14_217acal.xml',1)
The following step is not crucial but if the data was cropped and you know the start and end time of the cropping period, add it. Hint: it may be that this information is saved in the cal file. This deployment was not cropped, however, if you have one that has been, you can do the following, where x1 and x2 are the cropping times in seconds.
A.crop=[x1,x2]; M.crop=[x1,x2]; P.crop=[x1,x2]; Ma.crop=[x1,x2]; Aa.crop=[x1,x2];
A.crop_units=seconds' ; Aa.crop_units='seconds'; M.crop_units='seconds'; Ma.crop_units='seconds'; P.crop_units='seconds';
A.start_time='x1'; Aa.start_time='x1';
M.start_time= 'x1'; Ma.start_time='x1'; P.start_time='x1';
A.start_time_units='seconds'; Aa.start_time_units = 'seconds'; M.start_time_units ='seconds'; Ma.start_time_units ='seconds'; P.start_time_units ='seconds';
Add the history information in the creation of Aa and Ma.
A.history='sens_struct,crop_to';
M.history='sens_struct,crop_to';
P.history='sens_struct,crop_to';T.history='sens_struct,crop_to';
Aa.history='sens_struct,crop_to,tag2animal';
Ma.history='sens_struct,crop_to,tag2animal';
Make the metadata (replace xx with the initials of the data owner, making sure that they are listed in researchers.csv). For this particular deployment there are many metadata missing, thus we have only added the available information, but for your own deployments, please add as much information as possible as this is very valuable and will help to future researchers. See the metadata tutorial for a greater explanation of researchers.csv (in progress):
info = make_info(depid,'D3',depid(1:2),'xx') ;% change D3 if needed to the correspondent tag type, D2, D4, etc..
Edit the fields below so that they reflect the deployment method and location etc: Take the information from the DEPLOY or DEPLOYMENT sensor structure (mat file) or at the end of the cal .xml file that contains information regarding location, author, email from data owner, tag on position, tag on time, tag on placement, tag recovery position, tag recovery time, UTC to Local time, photo information…
info.project_name = 'SoCal';
info.project_datetime_start = '';
info.project_datetime_end = '';
info.dephist_deploy_locality = '';
info.dephist_deploy_method = 'suction cup';
info.dephist_deploy_location_lat ='33.4658';% the approx latitude of the tag deployment
info.dephist_deploy_location_lon='-118.4208';%the approx longitude of the tag deployment
info.tag_on_date='05_08_2014';
info.tag_on_time_local='10:9:25';
info.tag_on_time_utc='17:9:25';
info.utc2loc='-7';
info.tagger='';
info.rawdata_analyser='';
info.eamil_data_owner='';
If you know the following information add it to the info saying where the data came from:
info.dtype_source = sprintf('%sprh%d',depid,fs); % indicate the file that the data came from
info.dtype_nfiles = 1;
info.dtype_format = 'xml';
It is very important to save the OTAB (Orientation Table) matrix in Aa and Ma sensor structures.
Ma.otab=[0 0 0.2 0.82231 0.17]% for this specific example copy it from the .xml cal file.
Ma.otab=DEPLOY.OTAB; % in case you are copying the metadata from a .mat cal file.
Aa.otab=[0 0 0.2 0.82231 0.17]% for this specific example copy it from the .xml cal file.
Aa.otab=DEPLOY.OTAB; % in case you are copying the metadata from a .mat cal file.
Save the data and metadata to a .nc file:
ncname = sprintf('%ssens%d',depid,fs);% make a name for the.nc file
save_nc(ncname,info,P,A,M, Aa, Ma) ;% save the data
if temperature is present in the prh mat file (not available for this particular example), then save Temperature data in the ncfile as follows:
nc files are only formed by sensor structures, thus pitch, roll and heading orientation angles cannot be saved here. However, they are very easy to compute afterwards as you can see in the code below. See the animal orientation tutorial for greater detail.