feat: add import_to_fst

NAMESPACE

@@ -85,6 +85,7 @@ export(identify_privacythreshold)
 export(identify_query)
 export(identify_shifts)
 export(identify_tenure)
+export(import_to_fst)
 export(import_wpa)
 export(internal_network_plot)
 export(is_date_format)

R/import_to_fst.R

@@ -0,0 +1,49 @@
+# --------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See LICENSE.txt in the project root for license information.
+# --------------------------------------------------------------------------------------------
+
+#' @title Read a Workplace Analytics query in CSV using and create a FST file in
+#'   the same directory for faster reading
+#'
+#' @description Uses `import_wpa()` to read a Workplace Analytics query in CSV
+#'   and convert this into the serialized FST format which is much faster to
+#'   read. The 'fst' package must be installed.
+#'
+#' @details
+#' The [fst](https://www.fstpackage.org/) package provides a way to serialize
+#' data frames in R which makes loading data much faster than CSV.
+#' `import_to_fst()` converts a CSV file into a FST file in the specified
+#' directory. Once this FST file is created, it can be read into R using
+#' `fst::read_fst()`.
+#'
+#' Internally, `import_to_fst()` uses `import_wpa()`, and additional arguments
+#' to `import_wpa()` can be passed with `...`.
+#'
+#' @param path String containing the path to the Workplace Analytics query to be
+#'   imported. The input file must be a CSV file, and the file extension must be
+#'   explicitly entered, e.g. `"/files/standard query.csv"`. The converted FST
+#'   file will be saved in the same directory with a different file extension.
+#' @param ... Additional arguments to pass to `import_wpa()`.
+#'
+#' @export
+import_to_fst <- function(path, ...){
+
+  # Check if fst is installed
+  if(!"fst" %in% installed.packages()){
+
+    stop('`fst` is not installed.
+         Run `install.packages("fst")` to install the package.')
+
+  }
+
+  temp_df <- import_wpa(path, ...)
+
+  path_fst <- gsub(pattern = "csv$",
+                   replacement = "fst",
+                   x = path)
+
+  fst::write_fst(temp_df, path_fst)
+
+  message("FST file sucessfully created at ", path_fst)
+}

man/import_to_fst.Rd

@@ -0,0 +1,32 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/import_to_fst.R
+\name{import_to_fst}
+\alias{import_to_fst}
+\title{Read a Workplace Analytics query in CSV using and create a FST file in
+the same directory for faster reading}
+\usage{
+import_to_fst(path, ...)
+}
+\arguments{
+\item{path}{String containing the path to the Workplace Analytics query to be
+imported. The input file must be a CSV file, and the file extension must be
+explicitly entered, e.g. \code{"/files/standard query.csv"}. The converted FST
+file will be saved in the same directory with a different file extension.}
+
+\item{...}{Additional arguments to pass to \code{import_wpa()}.}
+}
+\description{
+Uses \code{import_wpa()} to read a Workplace Analytics query in CSV
+and convert this into the serialized FST format which is much faster to
+read. The 'fst' package must be installed.
+}
+\details{
+The \href{https://www.fstpackage.org/}{fst} package provides a way to serialize
+data frames in R which makes loading data much faster than CSV.
+\code{import_to_fst()} converts a CSV file into a FST file in the specified
+directory. Once this FST file is created, it can be read into R using
+\code{fst::read_fst()}.
+
+Internally, \code{import_to_fst()} uses \code{import_wpa()}, and additional arguments
+to \code{import_wpa()} can be passed with \code{...}.
+}