Changed project to package. Folder structure overhauled, roxygen comm…

…ents added, very little content changed.

.Rbuildignore

@@ -0,0 +1,14 @@
+^.*\.Rproj$
+^\.Rproj\.user$
+^devel/*
+^Misc/*
+^MatlabBinaryFiles/*
+^TestFiles/*
+^README\.Rmd$
+^README-.*\.png$
+^NEWS\.Rmd$
+^NEWS\.md$
+tar.gz$
+.gitignore
+^\.travis\.yml$
+^appveyor\.yml$

DESCRIPTION

@@ -0,0 +1,11 @@
+Package: PamBinaries
+Title: Loads Pamguard Binary Data
+Version: 1.0
+Authors@R: person("Taiki", "Sakai", email = "taiki.sakai@noaa.gov", role = c("aut", "cre"))
+Description: Loads binary file output from Pamguard into R. This is a translation of Matlab
+    code written by Michael Oswald.
+Depends: R (>= 3.4.0)
+License: GNU General Public License
+Encoding: UTF-8
+LazyData: true
+RoxygenNote: 6.0.1

Notes.R → Misc/Notes.R

@@ -20,7 +20,7 @@ as.numeric(ymd_hms("2017-04-27 21:29:15 UTC")) -
 
 as.numeric(ymd_hms("2014-08-06 18:41:47 UTC")) -
     as.numeric(ymd_hms("2014-06-18 01:39:00 UTC")) #mine
-1407350507811.00
+1407350507811.00 - a #matlab millis
 a <- clicktest$dataSet[[1]]$millis
 sprintf('%f', a)
 

NAMESPACE

@@ -0,0 +1,3 @@
+# Generated by roxygen2: do not edit by hand
+
+export(loadPamguardBinaryFile)

PamBinaries.Rproj

@@ -0,0 +1,18 @@
+Version: 1.0
+
+RestoreWorkspace: Default
+SaveWorkspace: Default
+AlwaysSaveHistory: Default
+
+EnableCodeIndexing: Yes
+UseSpacesForTab: Yes
+NumSpacesForTab: 4
+Encoding: UTF-8
+
+RnwWeave: Sweave
+LaTeX: XeLaTeX
+
+BuildType: Package
+PackageUseDevtools: Yes
+PackageInstallArgs: --no-multiarch --with-keep.source
+PackageRoxygenize: rd,collate,namespace

R/countChannels.R

@@ -0,0 +1,26 @@
+#' @title Count Number of Active Channels
+#' 
+#' @description Counts the number of active channels
+#'   given a channel mapping
+#'   
+#' @param channelMap Mapping of channels as a binary number
+#' 
+#' @return The number of active channels (number of ones)
+#' 
+#' @author Taiki Sakai \email{taiki.sakai@noaa.gov}
+#' 
+#' @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.
+#'   
+countChannels <- function(channelMap) {
+    nC <- 0
+    j <- 1
+    for(i in 1:30) {
+        if(bitwAnd(channelMap, j) != 0) {
+            nC <- nC + 1
+        }
+        j <- j * 2
+    }
+    return(nC)
+}

R/dateNumToMillis.R

@@ -0,0 +1,16 @@
+#' @title Convert Date Number to Milliseconds
+#' 
+#' @description Converts numeric date to millisecond date.
+#'   
+#' @param datenum Numeric value of a date.
+#' 
+#' @return Date as milliseconds
+#' 
+#' @author Taiki Sakai \email{taiki.sakai@noaa.gov}
+#' 
+#' @note Conversion to milliseconds to match how Java stores
+#'   dates. Doesn't appear to ever be used.
+#'   
+dateNumToMillis <- function(datenum) {
+    datenum * 1000
+}

loadPamguardBinaryFile.R → R/loadPamguardBinaryFile.R

@@ -1,8 +1,18 @@
-# Program to load a Pamguard binary file
-
-# open binary file and read data
-library(R.utils)
-sourceDirectory('./HelperFuncs') # Check these have been updated
+#' @title 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.
+#' 
+#' @param fileName The name of the binary file to be read
+#' 
+#' @return This function returns a list containing two objects. Data contains
+#'   all the binary data read. fileInfo contains metadata information for the file.
+#' 
+#' @author Taiki Sakai \email{taiki.sakai@noaa.gov}
+#' 
+#' @export
+#' 
 loadPamguardBinaryFile <- function(fileName) {
     tryCatch({
         fid <- file(fileName, open='rb')
@@ -143,7 +153,7 @@ loadPamguardBinaryFile <- function(fileName) {
                    {
                        # print(5)
                        if(length(fileInfo$fileHeader)==0) {
-                           print('Error: found data before file header. Abortng load.')
+                           print('Error: found data before file header. Aborting load.')
                            break
                        }
                        dataPoint <- readPamData(fid, fileInfo)
@@ -157,6 +167,6 @@ loadPamguardBinaryFile <- function(fileName) {
         print(e)
     })
     close(fid)
-    list(dataSet=dataSet, fileInfo=fileInfo)
+    list(data=dataSet, fileInfo=fileInfo)
 }
 

R/millisToDateNum.R

@@ -0,0 +1,18 @@
+#' @title Convert Java Millisecond Time to R
+#' 
+#' @description Converts Java millisecond time into numeric
+#'   time that R uses. 
+#'   
+#' @param millis Millisecond time from Java
+#' 
+#' @return Numeric time used by R.
+#' 
+#' @author Taiki Sakai \email{taiki.sakai@noaa.gov}
+#' 
+#' @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.
+#'   
+millisToDateNum <- function(millis) {
+    millis / 1000
+}

HelperFuncs/pamBinRead.R → R/pamBinRead.R

@@ -1,21 +1,28 @@
-# Pamguard binary reader helper
-# Easier to translate from Java, uses bigendian
+#' @title Read Pamguard Binary Data
+#' 
+#' @description A wrapper for reading various types of binary data.
+#'   
+#' @param fid The binary file being read
+#' @param what The type of data to read. Int64 is not handled natively
+#'   by R, see note.
+#' @param n The number of objects to read.
+#' 
+#' @return Data of the type and number specified.
+#' 
+#' @author Taiki Sakai \email{taiki.sakai@noaa.gov}
+#' 
+#' @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.
+#'   
 pamBinRead <- function(fid, what=c('int8', 'int16', 'int32',
                                    'int64', 'float', 'character'), n) {
     endian <- 'big'
     switch(match.arg(what),
            int8 = readBin(fid, 'integer', n=n, size=1, endian=endian),
            int16 = readBin(fid, 'integer', n=n, size=2, endian=endian),
            int32 = readBin(fid, 'integer', n=n, size=4, endian=endian),
-           # int64 = {
-           #     if(n != 1) {
-           #         print(paste('WARNING: Currently does not accurately ',
-           #                     'read more than one int64 at a time.'))
-           #     }
-           #     a <- as.numeric(readBin(fid, 'integer', n=n, size=4, endian=endian))
-           #     b <- as.numeric(readBin(fid, 'integer', n=n, size=4, endian=endian))
-           #     a*2^32 + b
-           # },
            int64 = {
                  if(n != 1) {
                        print(paste('WARNING: Currently does not accurately ',
@@ -28,6 +35,5 @@ pamBinRead <- function(fid, what=c('int8', 'int16', 'int32',
            },
            float = readBin(fid, 'numeric', n=n, size=4, endian=endian),
            character = rawToChar(readBin(fid, 'raw', n=n, size=1, endian=endian))
-           # character = readBin(fid, 'character', n=1, endian=endian)
     )
 }

HelperFuncs/readAISData.R → R/readAISData.R

@@ -1,12 +1,16 @@
-# Reads binary data stored by the AIS Processing module.
-#
-# Inputs:
-#     fid = file identifier
-#     fileInfo = structure holding the file header, module header, a handle
-#     data = a structure containing the standard data
-# Output:
-#     data = structure containing data from a single object
-
+#' @title Read AIS Data
+#' 
+#' @description Reads binary data stored by the AIS Processing module.
+#'   
+#' @param fid binary file identifier
+#' @param fileInfo structure holding the file header and module header
+#' @param data a structure containing standard data
+#' 
+#' @return a structure containing data from a single object, and a logical
+#'   flag if an error has occurred
+#' 
+#' @author Taiki Sakai \email{taiki.sakai@noaa.gov}
+#' 
 readAISData <- function(fid, fileInfo, data) {
     error <- FALSE
 

HelperFuncs/readClickData.R → R/readClickData.R

@@ -1,13 +1,16 @@
-# Reads binary data stored by the Click Detector.
-#
-# Inputs:
-#     fid = file identifier
-#     fileInfo = structure holding the file header, module header, a handle
-#     data = a structure containing the standard data
-#
-# Output:
-#     data = structure containing data from a single object
-
+#' @title Read Click Data
+#' 
+#' @description Reads binary data stored by the Click Detector module.
+#'   
+#' @param fid binary file identifier
+#' @param fileInfo structure holding the file header and module header
+#' @param data a structure containing standard data
+#' 
+#' @return a structure containing data from a single object, and a logical
+#'   flag if an error has occurred
+#' 
+#' @author Taiki Sakai \email{taiki.sakai@noaa.gov}
+#' 
 readClickData <- function(fid, fileInfo, data) {
     error <- FALSE
     tryCatch({

R/readClickFooter.R

@@ -0,0 +1,20 @@
+#' @title 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.
+#'   
+#' @param file binary file to be read
+#' 
+#' @return footer information for Click Detector module
+#' 
+#' @author Taiki Sakai \email{taiki.sakai@noaa.gov}
+#' 
+readClickFooter <- function(file) {
+    footer <- readStdModuleFooter(file)
+    if(footer$binaryLength != 0) {
+        footer$typesCountLength <- pamBinRead(file, 'int16', n=1)
+        footer$typesCount <- pamBinRead(file, 'int32', n=footer$typesCountLength)
+    }
+    return(footer)
+}