refactor: 🚚 rename convert_file() -> convert() (#281)

# Description

Closes #278 

Needs a quick review.

## Checklist

- [X] Ran `just run-all`

Author: signekb

NAMESPACE

@@ -1,6 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
-export(convert_file)
+export(convert)
 export(list_sas_files)
 export(read_parquet_file)
 export(read_parquet_partition)

R/convert.R

@@ -16,11 +16,11 @@
 #' @export
 #' @examples
 #' sas_file <- fs::path_package("fastreg", "extdata", "test.sas7bdat")
-#' convert_file(
+#' convert(
 #'   path = sas_file,
 #'   output_dir = fs::path_temp("path/to/output/file")
 #' )
-convert_file <- function(
+convert <- function(
   path,
   output_dir,
   chunk_size = 10000000L
@@ -69,7 +69,7 @@ convert_file <- function(
 #' Read SAS chunk
 #'
 #' @param skip Number of rows to skip.
-#' @inheritParams convert_file
+#' @inheritParams convert
 #'
 #' @returns A tibble.
 #'
@@ -86,7 +86,7 @@ read_sas_chunk <- function(path, skip, chunk_size) {
 #' Gets the year and register name from the file name in `path` and creates
 #' a partition path `{output_dir}/{register_name}/year={year}/`.
 #'
-#' @inheritParams convert_file
+#' @inheritParams convert
 #'
 #' @returns The partition path.
 #'

README.md

@@ -67,13 +67,13 @@ pak::pak("dp-next/fastreg")
 
 ## Usage
 
-Use `convert_file()` to convert a single SAS file to Parquet in Hive
+Use `convert()` to convert a single SAS file to Parquet in Hive
 partition format:
 
 ``` r
 library(fastreg)
 
-convert_file(
+convert(
   path = "path/to/file.sas7bdat",
   output_dir = "path/to/output_dir/"
 )

README.qmd

@@ -67,13 +67,13 @@ pak::pak("dp-next/fastreg")
 
 ## Usage
 
-Use `convert_file()` to convert a single SAS file to Parquet in Hive
+Use `convert()` to convert a single SAS file to Parquet in Hive
 partition format:
 
 ```{r, eval = FALSE}
 library(fastreg)
 
-convert_file(
+convert(
   path = "path/to/file.sas7bdat",
   output_dir = "path/to/output_dir/"
 )

_pkgdown.yml

@@ -13,7 +13,7 @@ navbar:
 reference:
 - title: Main functions
 - contents:
-  - starts_with("convert")
+  - convert
   - read_register
   - read_parquet
   - use_targets_template

inst/template-targets.R

@@ -79,7 +79,7 @@ list(
   # directory having been cleaned.
   tar_target(
     name = parquet_files,
-    command = convert_file(path = sas_paths, output_dir = output_dir),
+    command = convert(path = sas_paths, output_dir = output_dir),
     pattern = map(sas_paths),
     cue = tar_cue(mode = "always")
   )

man/convert_file.Rd man/convert.Rdman/convert_file.Rd renamed to man/convert.Rd

@@ -10,11 +10,11 @@ sas_path <- fs::path_temp("sas_bef")
 save_as_sas(bef_list, sas_path)
 sas_bef <- fs::dir_ls(sas_path)
 
-# Test convert_file() ----------------------------------------------------------
+# Test convert() ----------------------------------------------------------
 
 # Setup: Convert single file
 single_file_path <- fs::path_temp("parquet_single_file")
-single_file_output <- convert_file(
+single_file_output <- convert(
   path = sas_bef[[1]],
   output_dir = single_file_path
 )
@@ -25,11 +25,11 @@ data_actual <- arrow::open_dataset(
   dplyr::as_tibble()
 data_expected <- haven::read_sas(sas_bef[[1]])
 
-test_that("convert_file() returns output_dir", {
+test_that("convert() returns output_dir", {
   expect_equal(single_file_output, single_file_path)
 })
 
-test_that("convert_file() preserves source data and adds expected columns", {
+test_that("convert() preserves source data and adds expected columns", {
   expect_equal(nrow(data_actual), nrow(data_expected))
   expect_identical(
     data_actual |> dplyr::select(-c("source_file", "year")),
@@ -48,7 +48,7 @@ test_that("convert_file() preserves source data and adds expected columns", {
   )
 })
 
-test_that("convert_file() creates parts with expected naming pattern", {
+test_that("convert() creates parts with expected naming pattern", {
   actual <- fs::path_file(fs::dir_ls(
     single_file_path,
     recurse = TRUE,
@@ -57,33 +57,33 @@ test_that("convert_file() creates parts with expected naming pattern", {
   expect_true(all(stringr::str_detect(actual, "^part-[a-f0-9]{6}\\.parquet$")))
 })
 
-test_that("convert_file() errors with incorrect input parameters", {
+test_that("convert() errors with incorrect input parameters", {
   # Incorrect path type.
   expect_error(
-    convert_file(path = 1, output_dir = single_file_output),
+    convert(path = 1, output_dir = single_file_output),
     regexp = "character"
   )
   # Path must exist.
   expect_error(
-    convert_file(path = fs::file_temp(), output_dir = single_file_output),
+    convert(path = fs::file_temp(), output_dir = single_file_output),
     regexp = "does not exist"
   )
   # Incorrect output_dir type.
   expect_error(
-    convert_file(path = sas_bef[[1]], output_dir = 1),
+    convert(path = sas_bef[[1]], output_dir = 1),
     regexp = "string"
   )
   # output_dir must be scalar.
   expect_error(
-    convert_file(
+    convert(
       path = sas_bef[[1]],
       output_dir = rep(single_file_output, times = 2)
     ),
     regexp = "length 1"
   )
   # Incorrect chunk size (lower than allowed).
   expect_error(
-    convert_file(
+    convert(
       path = sas_bef[[1]],
       output_dir = single_file_output,
       chunk_size = 10L
@@ -92,7 +92,7 @@ test_that("convert_file() errors with incorrect input parameters", {
   )
 })
 
-test_that("convert_file() partitions by year based on file name", {
+test_that("convert() partitions by year based on file name", {
   expected <- fs::path(
     single_file_output,
     register_name,
@@ -107,12 +107,12 @@ test_that("convert_file() partitions by year based on file name", {
   )
 })
 
-test_that("convert_file() creates expected n parts when chunk_size < nrow", {
+test_that("convert() creates expected n parts when chunk_size < nrow", {
   chunks_path <- fs::path_temp("chunks_path")
   chunk_size <- 10000L
   sas_file <- sas_bef[[1]]
 
-  convert_file(
+  convert(
     path = sas_file,
     output_dir = chunks_path,
     chunk_size = chunk_size

tests/testthat/test-convert.R

@@ -8,7 +8,7 @@ output_dir <- fs::path_temp("output_dir")
 
 # Convert files.
 purrr::walk(sas_bef, \(path) {
-  convert_file(path, output_dir)
+  convert(path, output_dir)
 })
 
 # Test read_register() ---------------------------------------------------------
@@ -121,7 +121,7 @@ test_that("read_register() reads files with different columns", {
 
   # Convert files.
   purrr::walk(sas_diff_cols, \(path) {
-    convert_file(path, diff_cols_output)
+    convert(path, diff_cols_output)
   })
 
   # Define expected columns.
@@ -152,7 +152,7 @@ test_that("read_register() errors with incompatible schemas", {
   incompatible_output <- fs::path_temp("incompatible")
   # Convert files.
   purrr::walk(sas_incompatible, \(path) {
-    convert_file(path, incompatible_output)
+    convert(path, incompatible_output)
   })
 
   expect_error(read_register(incompatible_output), "incompatible")

tests/testthat/test-read.R

@@ -57,20 +57,20 @@ page.
 
 ```{mermaid}
 %%| label: fig-flow
-%%| fig-cap: "Expected workflow for converting one SAS file using `convert_file()`."
+%%| fig-cap: "Expected workflow for converting one SAS file using `convert()`."
 %%| fig-alt: "A flowchart showing the expected flow of converting register SAS files to Parquet files."
 flowchart TD
     identify_paths("Identify register path(s)<br>with list_sas_files(path)")
     path[/"path<br>[Character vector]"/]
     output_dir[/"output_dir<br>[Character scalar]"/]
     chunk_size[/"chunk_size<br>[Integer scalar]"/]
-    convert_file("convert_file()")
+    convert("convert()")
     output[/"Parquet file(s)<br>written to output_dir"/]
 
     %% Edges
-    identify_paths -.-> path --> convert_file
-    output_dir & chunk_size --> convert_file
-    convert_file --> output
+    identify_paths -.-> path --> convert
+    output_dir & chunk_size --> convert
+    convert --> output
 
     %% Style
     style identify_paths fill:#FFFFFF, color:#000000, stroke-dasharray: 5 5
@@ -96,13 +96,13 @@ flowchart TD
 ```
 
 ::: callout-warning
-`convert_file()`, the core function behind converting SAS files to
-Parquet used within the targets template, creates an Arrow schema with
-data types based on the first file chunk. This means that data type
-schemas are defined *within* files only. As a result, if there's a drift
-in data types across SAS files in the same register, this may not be
-identified in the conversion process, but will become evident when
-attempting to read the register.
+`convert()`, the core function behind converting SAS files to Parquet
+used within the targets template, creates an Arrow schema with data
+types based on the first file chunk. This means that data type schemas
+are defined *within* files only. As a result, if there's a drift in data
+types across SAS files in the same register, this may not be identified
+in the conversion process, but will become evident when attempting to
+read the register.
 
 We use this design to ensure that subsequent chunks follow the same
 schema as the first, as we don't want to have different data types