Package 'PamBinaries'

Title: Read and Process 'Pamguard' Binary Data
Description: Functions for easily reading and processing binary data files created by 'Pamguard' (<https://www.pamguard.org/>). All functions for directly reading the binary data files are based on 'MATLAB' code written by Michael Oswald.
Authors: Taiki Sakai [aut, cre], Michael Oswald [aut], Douglas Gillespie [ctb]
Maintainer: Taiki Sakai <[email protected]>
License: GNU General Public License
Version: 1.9.2
Built: 2025-02-07 02:56:19 UTC
Source: https://github.com/taikisan21/pambinaries

Help Index


Add Frequency and Time to Pamguard Whistle Binaries

Description

Adds items freq and time to a Pamguard binary file from the Whistle & Moan Detector

Usage

contourToFreq(data, verbose = FALSE)

Arguments

data

either a PamBinary class object or just the $data from a PamBinary object

verbose

logical flag to print calculated parameters

Value

data with items freq and time added. These use the calculated FFT window length, hope size, and sample rate to compute the frequency and time values of the saved whistle contour

Author(s)

Taiki Sakai [email protected]

Examples

# load example whistle file
wmFile <- system.file('extdata', 'WM.pgdf', package='PamBinaries')
wmData <- loadPamguardBinaryFile(wmFile)
# converts contour and FFT slice numbers to frequency and time values
wmData <- contourToFreq(wmData)
wmData$data[[1]]$contour
wmData$data[[1]]$freq
wmData$data[[1]]$time

Convert Pamguard Numeric Date to POSIXct

Description

a simple helper to convert Pamguard's numeric date to POSIXct format

Usage

convertPgDate(dateNum)

Arguments

dateNum

date as a numeric, seconds since 1970-01-01 per standard Pamguard output. Timezone is UTC

Value

A POSIXct date in UTC

Author(s)

Taiki Sakai [email protected]

Examples

# load the example click binary data, leaving date as numeric
clickFile <- system.file('extdata', 'Click.pgdf', package='PamBinaries')
clickData <- loadPamguardBinaryFile(clickFile, convertDate = FALSE)
# convert date to POSIXct
convertPgDate(clickData$data[[1]]$date)

Count Number of Active Channels

Description

Counts the number of active channels given a channel mapping

Usage

countChannels(channelMap)

Arguments

channelMap

Mapping of channels as a binary number

Value

The number of active channels (number of ones)

Note

Altered from original script to loop through 30 instead 32 because R stores only 32 bit integers. Should not ever have enough channels for this to matter.

Author(s)

Taiki Sakai [email protected]


Convert Date Number to Milliseconds

Description

Converts numeric date to millisecond date.

Usage

dateNumToMillis(datenum)

Arguments

datenum

Numeric value of a date.

Value

Date as milliseconds

Note

Conversion to milliseconds to match how Java stores dates. Doesn't appear to ever be used.

Author(s)

Taiki Sakai [email protected]


Load and Format Background Noise Data

Description

Reads and formats background noise data from Pamguard binary files or if not present in the original file will try to read the accompanying .pgnf noise file if it exists

Usage

loadBackgroundNoise(x)

plotBackgroundNoise(x)

combineBackgroundNoise(x, forPlot = FALSE)

Arguments

x

character pointing to a Pamguard binary file, or a PamBinary object created by loadPamguardBinaryFile. For plotting or combining, either of these or the output from loadBackgroundNoise

forPlot

logical flag when combining noise data. If used for plotting purposes this will insert NA columns into background data so that images show up with time gaps as expected. Leave as FALSE unless you are sure you want this.

Value

A list with times storing the POSIXct time of each background measurement, and background a matrix of background values. For binary data based on spectrogram measurements, there will also be freq the frequency in Hertz for each column of background measurement

Author(s)

Taiki Sakai [email protected]

Examples

# load the example click binary data, leaving date as numeric
gplFile <- system.file('extdata', 'GPL.pgdf', package='PamBinaries')
gplNoise <- loadBackgroundNoise(gplFile)
print(gplNoise)
plotBackgroundNoise(gplNoise)

Load Pamguard Binary File

Description

This function will load in the data from a Pamguard binary file. It will figure out the type of data being read based on the header of the file. All functions based on Matlab code written by Michael Oswald.

Usage

loadPamguardBinaryFile(
  fileName,
  skipLarge = FALSE,
  skipData = FALSE,
  debug = FALSE,
  keepUIDs = NULL,
  convertDate = FALSE,
  ...
)

Arguments

fileName

The name of the binary file to be read

skipLarge

Should we skip large parts of binaries? Currently only applicable to whistle, click, and DIFAR data

skipData

Should we skip all data and only read headers and footers?

debug

logical flag to show more info on errors

keepUIDs

If not NULL, a vector of UIDs to read. All UIDs not in this vector will not be read.

convertDate

logical flag to convert date from numeric to POSIXct. Defaults to FALSE for speed, can reduce time by

...

Arguments passed to other functions

Value

This function returns a list containing two objects. Data contains all the binary data read. fileInfo contains metadata information for the file.

Author(s)

Taiki Sakai [email protected]

Examples

# read example whistle data
wmFile <- system.file('extdata', 'WM.pgdf', package='PamBinaries')
whistleData <- loadPamguardBinaryFile(wmFile)
# works the same for different kinds of binary files
clickFile <- system.file('extdata', 'Click.pgdf', package='PamBinaries')
clickData <- loadPamguardBinaryFile(clickFile)
# convert date to POSIXct (default does not because it is faster)
clickPOSIX <- loadPamguardBinaryFile(clickFile, convertDate = TRUE)
clickData$data[[1]]$date
clickPOSIX$data[[1]]$date
# read only the fileInfo portion, has empty $data item
clickInfo <- loadPamguardBinaryFile(clickFile, skipData = TRUE)
# skip reading the large click waveforms, much faster if you dont need them
clickLess <- loadPamguardBinaryFile(clickFile, skipLarge = TRUE)
object.size(clickData)
object.size(clickLess)
# only read specific UID numbers
clickSpecific <- loadPamguardBinaryFile(clickFile, keepUIDs = c(4000006, 4000007))
names(clickSpecific$data)

Convert Java Millisecond Time to R

Description

Converts Java millisecond time into numeric time that R uses.

Usage

millisToDateNum(millis)

Arguments

millis

Millisecond time from Java

Value

Numeric time used by R.

Note

Original function was more relevant as Matlab and Java use different time origins. Java & R both use 1970-01-01, but Java stores as milliseconds vs seconds in R.

Author(s)

Taiki Sakai [email protected]


Read Pamguard Binary Data

Description

A wrapper for reading various types of binary data.

Usage

pamBinRead(
  fid,
  what = c("int8", "int16", "int32", "int64", "uint8", "uint16", "float", "double",
    "character"),
  n,
  seek = FALSE
)

Arguments

fid

The binary file being read

what

The type of data to read. Int64 is not handled natively by R, see note.

n

The number of objects to read.

seek

Whether or not to just seek instead of reading

Value

Data of the type and number specified.

Note

R does not natively support 64-bit integers. Current implementation is to read an int64 as 8 separate 1-byte raw pieces. These are converted from hexidecimal, shifted by the appropriate power of 2, then summed. Currently cannot read more than one int64 at a time, shouldn't be necessary.

Author(s)

Taiki Sakai [email protected]


Convert a PamBinary Object to Data Frame

Description

Converts a PamBinary object into a data frame. The data.frame will combine all of the data from the data part of the PamBinary object, but will not include annotations data, click waveforms, DIFAR demux data, or contours from the WMD detector. These are skipped because they are either inconsistent in their size, or are large objects. The function pbToDf is also called when as.data.frame is called on a PamBinary class object.

Usage

pbToDf(pb, templateNames = NULL)

Arguments

pb

a PamBinary class object created by loadPamguardBinaryFile

templateNames

if using the click template classifier, the names of the species for the click templates. These will be used as the names of the columns in the dataframe, and the length of this must exactly match the number of templates used. Will add columns for the threshold, match, and reject correlation values for each template name provided

Value

a data.frame containing most of the binary data read in. Will not contain most annotation data, click waveforms, DIFAR demux data, or contour information from WMD detector. These are skipped because they are either incosistent in their size, or are large objects. Click template classifier information will be included if templateNames are supplied. If binary is from noise band monitor, noise data will be stored in columns noiseMean, noisePeak, and octaveBands, and the resulting dataframe will have a row for each separate octave band stored

Author(s)

Taiki Sakai [email protected]

Examples

# load the data
clickFile <- system.file('extdata', 'Click.pgdf', package='PamBinaries')
clickData <- loadPamguardBinaryFile(clickFile)
# two methods two convert to a dataframe
head(pbToDf(clickData))
head(data.frame(clickData))

Plot Whistle Contour

Description

Plots the entire whistle contour saved in a Pamguard Whistle & Moan Detector binary file, highlighting the selected contour

Usage

plotWMD(data, id = 1, ...)

Arguments

data

either a PamBinary class object, or just the $data from a PamBinary object, or a single detection from the $data

id

the id of the whistle to plot, either an index or Pamguard UID

...

parameters to pass to other functions

Value

A ggplot object

Author(s)

Taiki Sakai [email protected]

Examples

# load example whistle file
wmFile <- system.file('extdata', 'WM.pgdf', package='PamBinaries')
wmData <- loadPamguardBinaryFile(wmFile)
plotWMD(wmData, 1)
plotWMD(wmData, 2)

Read AIS Data

Description

Reads binary data stored by the AIS Processing module.

Usage

readAISData(fid, fileInfo, data, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read Beam Former Annotation

Description

Reads binary data stored by beam former annotation module

Usage

readBeamFormerAnnotation(fid, fileInfo, anVersion, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

anVersion

annotation version

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read Bearing Annotation

Description

Reads binary data stored by bearing annotation module

Usage

readBearingAnnotation(fid, fileInfo, anVersion, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

anVersion

annotation version

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read Click Detector Background data

Description

Reads in the background data saved by the Click Detector

Usage

readClickBackground(fid, fileInfo, data)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header, module header, and the appropriate function to read module specific data

data

a structure containing standard data

Value

a structure containing data from a single object

Author(s)

Michael Oswald [email protected]


Read Click Classifier Annotation

Description

Reads binary data stored by Click Classifier annotations

Usage

readClickClsfrAnnotation(fid, fileInfo, debug = FALSE)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

debug

logical flag to show more info on errors

Value

a vector of click classifiers, represented by the click type flag

Author(s)

Taiki Sakai [email protected]


Read Click Data

Description

Reads binary data stored by the Click Detector module.

Usage

readClickData(
  fid,
  fileInfo,
  data,
  skipLarge = FALSE,
  debug = FALSE,
  getWave,
  onlyWave
)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

skipLarge

a flag for whether or not to skip reading large wave file

debug

logical flag to show more info on errors

getWave

DEPRECATED: see skipLarge

onlyWave

DEPRECATED: see skipLarge

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read Click Footer

Description

Reads module footer information for the Click Detector module. Note that sometimes there is no additional footer information, so check first whether or not the binaryLength variable is 0.

Usage

readClickFooter(file)

Arguments

file

binary file to be read

Value

footer information for Click Detector module

Author(s)

Taiki Sakai [email protected]


Read Click Trigger Level

Description

Reads binary data stored by the click detector trigger

Usage

readClickTriggerData(fid, fileInfo, data, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read Click Trigger Header

Description

Reads file header information specific to the click trigger module

Usage

readClickTriggerHeader(file)

Arguments

file

binary file to be read

Value

header information for the click trigger

Author(s)

Taiki Sakai [email protected]


Read Clip Data

Description

Reads binary data stored by the Clip Generator module.

Usage

readClipData(fid, fileInfo, data, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read DbHt Data

Description

Reads binary data stored by the DbHt module.

Usage

readDbHtData(fid, fileInfo, data, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read Difar Data

Description

Reads binary data stored by the Difar Processing module.

Usage

readDifarData(fid, fileInfo, data, skipLarge = FALSE, debug = FALSE)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

skipLarge

a flag of whether or not to skip reading the waveform

debug

logical flag to show more info on errors

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read Deep Learning Annotation

Description

Reads binary data stored by the DbHt module.

Usage

readDLAnnotation(fid, fileInfo, anVersion, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

anVersion

annotation version

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read Deep Learning Detection Data

Description

Reads binary data stored by the DbHt module.

Usage

readDLDetData(fid, fileInfo, data, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read Deep Learning Model Data

Description

Reads binary data stored by the Deep Learning Model module

Usage

readDLModelData(fid, fileInfo, data, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read File Footer

Description

Reads in the binary file footer. The input variable version is the file format read in from the file header. As of version 3, the file footer includes the lowest and highest UID values in the file.

Usage

readFileFooterInfo(fid, version)

Arguments

fid

binary file to be read

version

binary file version

Value

footer information common to all files

Author(s)

Taiki Sakai [email protected]


Read File Header

Description

Reads file header information common to all files

Usage

readFileHeader(file, readExtra = FALSE)

Arguments

file

binary file to be read

readExtra

flag if there is extra information to read

Value

header information common to all files

Author(s)

Taiki Sakai [email protected]


Read GPL Detections

Description

Reads binary data stored by the GPL Module.

Usage

readGPLDetections(fid, fileInfo, data, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Michael Oswald [email protected]


Read Java UTF-8 String

Description

Reads a Java UTF-8 string. The first 2 bytes are the length of the string, then the string itself.

Usage

readJavaUTFString(file)

Arguments

file

binary file to be read

Value

the string and its length

Author(s)

Taiki Sakai [email protected]


Read LTSA Data

Description

Reads binary data stored by the LTSA module.

Usage

readLTSAData(fid, fileInfo, data, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read LTSA Header

Description

Reads file header information specific to the LTSA module

Usage

readLTSAHeader(file)

Arguments

file

binary file to be read

Value

header information for the LTSA module

Author(s)

Taiki Sakai [email protected]


Read Matched Classifier Annotation

Description

Reads annotations from the matched click classifier. The matched matched click classifier annotates click detections with a threshold, matchcorr and rejectcorr values. The threshold value is used in the binary classification process. If it exceeds a hard value then the click is classified with the set type. The matchcorr and rejectcorr values are simply the correlation values of the match and reject templates with the click.

Usage

readMatchClsfrAnnotation(fid, fileInfo, anVersion, debug = FALSE)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

anVersion

version id of annotation module

debug

logical flag to show more info on errors

Value

a vector with the threshold, matchcorr, and rejectcorr values. See description.

Author(s)

Taiki Sakai [email protected]


Read Noise Band Data

Description

Reads binary data stored by the Noise Band Monitor.

Usage

readNoiseBandData(fid, fileInfo, data, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read Noise Monitor Data

Description

Reads binary data stored by the Noise Monitor.

Usage

readNoiseMonData(fid, fileInfo, data, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read Noise Monitor Header

Description

Reads file header information specific to the Noise Monitor module

Usage

readNoiseMonHeader(file)

Arguments

file

binary file to be read

Value

header information for the Noise Monitor module

Author(s)

Taiki Sakai [email protected]


Read Pamguard Data

Description

Reads in the object data that is common to all modules. This reads up to (but not including) the object binary length, and then calls a function to read the module-specific data.

Usage

readPamData(fid, fileInfo, skipLarge, debug = FALSE, keepUIDs, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header, module header, and the appropriate function to read module specific data

skipLarge

Should we skip large parts of binaries? Currently only applicable to whistle, click, and DIFAR data

debug

logical flag to show more info on errors

keepUIDs

If not NULL, a vector of UIDs to read. All UIDs not in this vector will not be read.

...

Arguments passed to other functions

Value

a structure containing data from a single object

Author(s)

Taiki Sakai [email protected]


Read Right Whale Edge Detector Data

Description

Reads binary data stored by the Right Whale Edge Detector.

Usage

readRWEDetectorData(fid, fileInfo, data, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read Spectral Background data

Description

Reads in the background data saved by various detectors (e.g WMD, Right Whale Edge Detector, etc) EXCEPT FOR the Click Detector

Usage

readSpectralBackground(fid, fileInfo, data)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header, module header, and the appropriate function to read module specific data

data

a structure containing standard data

Value

a structure containing data from a single object

Author(s)

Michael Oswald [email protected]


Read Standard Module Footer

Description

Reads the module footer information common to all modules. Differs from the legacy code in that it does not read in or skip any information specific to a module.

Usage

readStdModuleFooter(file)

Arguments

file

binary file to be read

Value

footer information common to all modules

Author(s)

Taiki Sakai [email protected]


Read Standard Module Header

Description

Reads the module header information common to all modules. Differs from the legacy code in that it does not read in or skip any information specific to a module.

Usage

readStdModuleHeader(file)

Arguments

file

binary file to be read

Value

header information common to all modules

Author(s)

Taiki Sakai [email protected]


Read TDBL Annotation

Description

Reads binary data stored by TDBL annotation module

Usage

readTDBLAnnotation(fid, fileInfo, anVersion, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

anVersion

annotation version

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read Target Motion Annotation

Description

Reads binary data stored by beam former annotation module

Usage

readTMAnnotation(fid, fileInfo, anVersion, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

anVersion

annotation version

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read a Tritech Track

Description

Reads binary data stored by the Gemini Tritech Module

Usage

readTritechTrack(fid, fileInfo, data, debug = FALSE, ...)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

debug

logical flag to show more info on errors

...

Arguments passed to other functions

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Benjamin Blundell [email protected]


Read Whistle and Moan Data

Description

Reads binary data stored by the Whistle & Moan Detector

Usage

readWMDData(fid, fileInfo, data, skipLarge = FALSE, debug = FALSE)

Arguments

fid

binary file identifier

fileInfo

structure holding the file header and module header

data

a structure containing standard data

skipLarge

a flag for whether or not to skip reading large contours

debug

logical flag to show more info on errors

Value

a structure containing data from a single object, and a logical flag if an error has occurred

Author(s)

Taiki Sakai [email protected]


Read Whistle & Moan Detector Header

Description

Reads file header information specific to the Whistle & Moan Detector module

Usage

readWMDHeader(file)

Arguments

file

binary file to be read

Value

header information for the Whistle & Moan Detector module

Author(s)

Taiki Sakai [email protected]