First Post. Making a LTSA in PAMGuard

This post will show you how to quickly make a publication ready long term spectral average using PAMGuard and MATLAB.

An LTSA (long term spectral average) is essentially a spectrogram  which shows particularly long time periods, e.g. hours, days or even months. They’re great for summarising passive acoustic studies, were acoustic data may have been collected over extended periods of time. This post is going to describe how to use PAMGuard (www.pamguard.org) , an open source tool kit for analysis to generate an LTSA. We’ll then import it into MALTAB and create a publishable figure.

To begin…PAMGuard

You need PAMGuard and the PAMGuard MATLAB library (www.pamguard.org). You also need MATLAB (MALTAB is expensive and not open source, two things I dislike. I intend to move to R but for now PAMGuard has a MATLAB library so we’re sticking with that). If you don’t have MATLAB this might work with GNU Octave, but no promises. You’ll also need some acoustic data, preferably a big data-set.

Open PAMGUARD with a blank configuration. Add the Sound Acquisition module by clicking File->Add Modules->Sound Processing->Sound Acquisition. Click Settings->Sound Acquisition settings… and in the dialog which appears select Audio File Folder or Multiple Files. Click Browse and select your folder of audio files. Click OK. 

An LTSA needs FFT data, that is data in the time frequency, rather than time amplitude domain, so we need to add an FFT module. File->Add Modules->Sound Processing->FFT (Spectrogram) Engine. Open the FFT Engine settings by clicking Settings->FFT (Spectrogram) Engine settings…Make sure all the channels you want to analyse are selected and click OK.

Next add the Long Term Spectral Average Module File->Add Modules->Sound Processing->Long Term Spectral Average. Open settings Settings->Long term spectral average settings…  and again make sure the channels you wish to analyse are slected, then click OK.

We need to save the data so add the Binary Storage and Database modules from the File->Add Modules->Utilities menu. If you don’t have Microsoft Access you can download drivers on the PAMGUARD website. Set up where you want to store data by selecting File->Database->Database Selection… and then File->Binary Storage options…Make sure you get this step right as this is where the LTSA data is saved.

Technically that’s us, however if you want to visualise data whilst PAMGuard is processing we need to add some displays. To add a main display go to File->Add Modules->User Display and File->Add Modules->Level Meter. Click Settings->Level Meter settings… to set up the level meter. In the top toolbar you should now see a User Display option. Click it and select New Spectrogram … This will bring up a Spectrogram Options dialog. In the Source Data drop down menu you can either select data from the LTSA module or the FFT module. Choose which you prefer and make sure each panel in the Spectrogram Display shows and different chanel. Click OK.

Now SAVE YOUR CONFIGURATION (File->Save Configueration)  and click the red button to start. PAMGuard should now start processing. Depending on the size of your data-set you can go away and make a cup of tea or wait a few weeks. To check things are working PAMGUARD should show moving level meters and the LTSA will (eventually) appear on the display. Binary files should also be generated inside the folder you selected for the Binary Storage module.

So that’s part one…phew.

Next…MATLAB

Now we’re going to use MATLAB to generate an image showing the LTSA. Note for power users of PAMGUARD, once all processing has finished you can open PAMGUARD in viewer mode to view the LTSA- but unfortunately you can’t generate a figure which would be suitable for a publication.

So, the idea is that we can open up the LTSA binary files generated by PAMGUARD and then make a colour map to display the data. You need to use the PAMGUARD MATLAB library for this- make sure to add the entire library folder to your MATLAB path.

Here are the functions you need on top of the PAMGuard MATALB library

function [ltsa_spectrum, ltsa_time, interval] =load_LTSA_folder(folder, channel, day_start, day_end, plotLTSA)
%% Load a folder of LTSA files and create an LTSA spectrum.

binary_files=findBinaryFiles(folder);

n=1;
for i=1:length(binary_files)-1
[pathstr,name,ext] = fileparts(binary_files{i}) ;
if ~isempty(strfind(name, 'LTSA'))
[ltsa_data fileHeader fileFooter moduleheader modulefooter]=loadLTSAFile(binary_files{i});
if (isstruct(moduleheader))
interval=moduleheader.intervalSeconds;
end
for j=1:length(ltsa_data)
ltsa_channels=getChannels(ltsa_data(j).channelMap);
for k=1:length(ltsa_channels)
if (ltsa_channels(k)==channel)
disp(['LTSA file found ' num2str(i)])
%add ltsa data to array.
ltsa_spectrum(:,n)=ltsa_data(j).data(:,k);
ltsa_time(n)=ltsa_data(j).date;
ltsa_nFFT(n)=ltsa_data(j).nFFT;
n=n+1;
end
end
end
end
end

day_num_start=datenum(day_start,'dd-mm-yyyy HH:MM:SS');
day_num_end=datenum(day_end,'dd-mm-yyyy HH:MM:SS');
index_OK=find(ltsa_time> day_num_start & ltsa_time<=day_num_end);
ltsa_time=ltsa_time(index_OK);
ltsa_spectrum=ltsa_spectrum(:,index_OK); %grid of values.

%% Plot the LTSA
fftsize=length(ltsa_spectrum(:,1));
if (plotLTSA)

freqbin=sR/2/fftsize;
%need to make a meshgrid
[Xinterp,Yinterp] = meshgrid((1:length(ltsa_time))*(interval),(1:fftsize)*freqbin);

[Xinterp,Yinterp] = meshgrid(ltsa_time,(1:fftsize)*freqbin);

%%now plot a surface
surf(Xinterp, Yinterp, ltsa_spectrum,'EdgeColor','none')
colormap Hot;
caxis([0.005 0.25])
xlabel('Time (seconds)')
ylabel('Frequency (kHz)');
view(0,90) %%set view angle

end
end

and …

function [filenames]= findBinaryFiles(filePath)
%% Search a folder and find binary files which contains detection information. e.g. .pgdf files.
subFiles=dir(filePath);
filenames={};
for i=1:length(subFiles);

if (strcmp(subFiles(i).name,'.')==1 || strcmp(subFiles(i).name,'..')==1)
continue;
end

if (subFiles(i).isdir==1)
subFolderName=[filePath,'\', subFiles(i).name];
filenames=cat(2, filenames,findBinaryFiles(subFolderName));

else
binaryFileName=[filePath,'\',subFiles(i).name];
binaryChar=char(binaryFileName);
fileEnd=binaryChar(length(binaryChar)-3: length(binaryChar));
%add to binary file list
if (strcmp(fileEnd,'pgdf')==1)
filenames=cat(2,filenames ,binaryFileName(1,:));
end
end

end

end

A typicaL script with this stuff might look like….

%% Sound of Islay example
day_start='14-07-2013 08:00:00';
day_end='14-07-2013 17:30:00';
channel-0;

folder='C:\Users\Google Drive\research\hawaii\LTSA';

% load and plot LTSA data
[ltsa_spectrum, ltsa_time, intervalseconds] =load_LTSA_folder(folder, channel, day_start, day_end, true);

To run this code replace the folder name with the path to the binary files created in PAMGuard and channel with the channel number for which to generate the LTSA. day_start and day_end are the the start and end time of the LTSA- obviously these have to be within the range of the data which has been processed.

And what you get out is…

This is an LTSA of a drifter in a tidal stream. Recordings were made at 500kHz so this is a very high frequency. Note how high frequency the noise spikes are. I’ve gone a bit further in this plot and overlaid a green line showing the maximum detection range of a typical harbour porpoise with the noise. Note the reduction in range in noisy areas- tidal streams can really interfere with PAM equipment!

So how does this all work? Well the key function here is loadLTSAFile(filename); This is part of the PAMGuard MATLAB library and opens a single LTSA binary file. Each binary file contains a portion of the LTSA data. This is added to an array and saved. Then the plot simply creates a surface along with relevant bits and axis labels etc .

Try it out- drop me a message if it doesn’t work.