Introducing new smoothing function

Fixes #11.

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: OpenPoseR
 Type: Package
 Title: Analyze Motion-Tracking Data Derived from Video Files Using OpenPose
-Version: 1.0.5
+Version: 1.1.0
 Authors@R: c(
     person("Patrick C.", "Trettenbrein", email = "[email protected]", role = c("aut", "cre")),
     person("Emiliano", "Zaccarella", email = "[email protected]", role = "aut"))
@@ -20,4 +20,5 @@ Imports:
     reshape,
     RColorBrewer,
     magick,
-    av
+    av,
+    kza

R/file_smooth_timeseries.R

@@ -0,0 +1,47 @@
+# file_smooth_timeseries()
+#
+# OpenPoseR (https://github.com/trettenbrein/OpenPoseR)
+# Patrick C. Trettenbrein, [email protected]
+#
+# A wrapper for the OpenPoseR function smooth_timeseries() that makes it possible to
+# directly pass a file name and or path including a file name to the function.
+
+file_smooth_timeseries <- function(file, span = 4, order = 6, overwrite = FALSE) {
+  # We at least need an input file
+  if(missing(file)) {
+    stop("Argument \"file\" must be specified. Path to CSV file inclduing file name and ending (*.csv).", call. = FALSE)
+  }
+
+  # Check whether file exists
+  if(!file.exists(file)) {
+    stop(paste("Couldn't find CSV file: ", file, sep = ""), call. = FALSE)
+  }
+
+  # Read file
+  data <- read.csv(file = file)
+
+  # Call clean_data()
+  smoothed_data <- smooth_timeseries(data[,1], span, order)
+
+  # Update file (i.e. overwrite) or crate new file?
+  if(overwrite==FALSE) {
+    output_file <- try(write.csv(smoothed_data, file = paste(gsub("\\.csv$", "", file),
+                                                           "_smoothed.csv", sep = ""),
+                                 row.names = FALSE))
+  } else {
+    output_file <- try(write.csv(smoothed_data, file = file, row.names = FALSE))
+  }
+
+  # We should tell the user whether the operation was a success
+  output <- FALSE
+  ## See if files were created successfully, if not issue a warning
+  if(is.null(output_file)) {
+    output <- TRUE
+  } else {
+    warning("Creating file for results of calling smooth_timeseries() failed.",
+            call. = FALSE)
+  }
+
+  # Return message about result
+  return(output)
+}

R/smooth_timeseries.R

@@ -0,0 +1,34 @@
+# smooth_timeseries()
+#
+# OpenPoseR (https://github.com/trettenbrein/OpenPoseR)
+# Patrick C. Trettenbrein, [email protected]
+#
+# Applies a Kolmogorov-Zurbenko filter to the given time series data.
+#
+# Note: This function is inspired by and partly based upon code for
+# smoothing procedures discussed by Wim Pouw ([email protected])
+# and James Trujillo ([email protected]) in the context of
+# the "Envision Bootcamp" 2021. Plese find further details here:
+# https://wimpouw.github.io/EnvisionBootcamp2021/MergingAcousticsMT.html
+
+smooth_timeseries <- function(data, span = 4, order = 6) {
+  # We'll be using the "kza" package, so let's require it
+  if (!requireNamespace("kza", quietly = TRUE)) {
+    stop("Package \"kza\" needed for this function to work. Please install it.", call. = FALSE)
+  } else {
+    # Load "kza" package
+    library("kza")
+  }
+
+  # We at least need some data to work with
+  if(missing(data)) {
+    stop("You have to pass the function a data frame to work with.",
+         call. = FALSE)
+  }
+
+  filtered_data <- kza(x = data, m = span, k = order, impute_tails = TRUE)
+  output <- filtered_data$kza
+
+  # Return result
+  return(output)
+}

README.md

@@ -33,7 +33,7 @@ For details on what OpenPoseR can (and can't) do, respectively, how you can use
 
 ## Installation  
 
-For now, OpenPoseR (current version: 1.0.5) can be installed using the following commands (you will need to have the ``devtools`` package installed):
+For now, OpenPoseR (current version: 1.1.0) can be installed using the following commands (you will need to have the ``devtools`` package installed):
 
 ```r
 # Install devtools from CRAN (if not already installed)

man/file_smooth_timeseries.Rd

@@ -0,0 +1,24 @@
+\name{file_smooth_timeseries}
+\alias{file_smooth_timeseries}
+\title{Smooth CSV file generated by en_velocity() or en_acceleration() using smooth_timeseries()}
+\usage{
+file_smooth_timeseries(file, span, order, overwrite = FALSE)
+}
+\arguments{
+\item{file}{Name of CSV file (*.csv) or path to file including filename.}
+\item{span}{The window for the filter.}
+\item{order}{The number of iterations.}
+\item{overwrite}{Optional. Defaults to FALSE. Will write output to "filename_smoothed.csv" in the input directory.}
+}
+\description{
+A wrapper for the OpenPoseR function smooth_timeseries() that makes it possible to directly pass a file name and or path including a file name to the function.
+
+Can be used to use smooth_timeseries() for a CSV file (*.csv) created using the en_velocity() or en_acceleration() functions without manually loading the data from the file into R first.
+}
+\examples{
+# Smooth file "~/myvideo/myvideo_body25_cleaned_en_velocity.csv"
+file_smooth_timeseries("~/myvideo/myvideo_body25_cleaned_en_velocity.csv")
+
+# Smooth file "~/myvideo/myvideo_body25_cleaned_en_velocity.csv" and do not overwrite file
+file_smooth_timeseries("~/myvideo/myvideo_body25_cleaned_en_velocity.csv", span = 4, order = 4, overwrite = TRUE)
+}

man/smooth_timeseries.Rd

@@ -0,0 +1,17 @@
+\name{smooth_timeseries}
+\alias{smooth_timeseries}
+\title{Smooth time series data of given data frame using a Kolmogorov-Zurbenko filter.}
+\usage{
+smooth_timeseries(data, span = 4, order = 6)
+}
+\arguments{
+\item{data}{A data frame with only one numerical column.}
+\item{span}{The window for the filter.}
+\item{order}{The number of iterations.}
+}
+\description{
+This function can be used to smooth time series data of given data frame using a Kolmogorov-Zurbenko filter. By default applies a "mild" filter and imputes the tails.
+}
+\examples{
+smooth_timeseries(data)
+}