diff --git a/AGENTS.md b/AGENTS.md index a94afd8..16382ab 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -# AGENTS.md + ## Overview ReadWriter is an R package providing convenience functions for reading from and writing to text-based data files. The package aims to streamline common I/O tasks and complements other tools in the `@vertesy` ecosystem. @@ -10,6 +10,12 @@ ReadWriter is an R package providing convenience functions for reading from and - `DESCRIPTION` – package metadata and dependency declarations. - `README.md` – installation instructions and a high-level overview. + + +### Update the Source, Not Just the Documentation + +Documentations rebuilt and overwritten from upstream sources: `.Rd` files from roxygen annotations and DESCRIPTION and NAMESPACE from `config.R` by `PackageTools::document_and_create_package()` relying on `devtools::document()` when I manually, regularly run `/Development/MYPACKAGE/Development/Create_the_MYPACKAGE_Package.R")`. Thus always update the upstream sources first, then fix the downstream documentations correspondingly. + ## Dependencies - Requires the `@vertesy` package [`Stringendo` (>=0.5.0)](https://github.com/vertesy/Stringendo) and CRAN packages `gtools`, `openxlsx`, `qs`, and `readr`. - Install `Stringendo` before installing ReadWriter: @@ -23,6 +29,10 @@ ReadWriter is an R package providing convenience functions for reading from and - Run `R -q -e "devtools::document()"` to regenerate Rd files before committing. - Verify the package with `R -q -e "devtools::check(document = FALSE)"`; checks should pass with no errors. - There is currently no automated test suite. Manual testing of new functionality is encouraged. +- In `/Development/MYPACKAGE/Development/Create_the_MYPACKAGE_Package.R")`, `PackageTools::document_and_create_package()` recreates an R package’s metadata and documentation from a configuration file. It runs `devtools::document()` to regenerate package documentation, including the DESCRIPTION and NAMESPACE. + + ## Getting started + New contributors should read `README.md` for installation details and review `R/ReadWriter.R` to understand available functions. For broader context and utility helpers, explore the `Stringendo` package and other repositories in the `@vertesy` organization. diff --git a/DESCRIPTION b/DESCRIPTION index 1b1aebc..f4f3d37 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -9,11 +9,12 @@ License: GPL-3 + file LICENSE BugReports: https://github.com/vertesy/ReadWriter/issues Depends: Stringendo (>= 0.5.0) -Imports: +Imports: gtools, openxlsx, qs, - readr + readr, + stringi Encoding: UTF-8 Packaged: 2026-08-25 16:41:37.734198 Roxygen: list(markdown = TRUE) diff --git a/Development/Create_the_ReadWriter_Package.R b/Development/Create_the_ReadWriter_Package.R index 1749f15..db44c14 100644 --- a/Development/Create_the_ReadWriter_Package.R +++ b/Development/Create_the_ReadWriter_Package.R @@ -86,7 +86,8 @@ for (scriptX in ls.scripts.full.path) { } file.edit(paste0(repository.dir, "/R/list.of.functions.in.", package.name, ".det.md")) file.edit(paste0(repository.dir, "/README.md")) -file.remove(paste0(repository.dir, "/R/list.of.functions.in.", package.name, ".det.md")) +# file.remove(paste0(repository.dir, "/R/list.of.functions.in.", package.name, ".det.md")) +file.remove(list.files(file.path(repository.dir, "R"), pattern = "^list\\.of\\.functions\\.in\\..+\\.det\\.md$", full.names = TRUE)) d$PackageTools() PackageTools::copy_github_badge("active") # Add badge to readme via clipboard diff --git a/Development/config.R b/Development/config.R index eae80d0..593f8b9 100644 --- a/Development/config.R +++ b/Development/config.R @@ -14,7 +14,7 @@ DESCRIPTION <- list( license = "GPL-3 + file LICENSE", depends = "Stringendo (>= 0.5.0)", remotes = "github::vertesy/Stringendo", - imports = "qs, openxlsx, gtools, readr", + imports = "qs, openxlsx, gtools, readr, stringi", suggests = "" ) diff --git a/NAMESPACE b/NAMESPACE index 035a34a..5d57af3 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -33,3 +33,4 @@ importFrom(readr,read_csv) importFrom(readr,read_csv2) importFrom(readr,read_delim) importFrom(readr,read_tsv) +importFrom(stringi,stri_detect_regex) diff --git a/R/Deprecated.Functions.R b/R/Deprecated.Functions.R index 1053249..e0621c3 100644 --- a/R/Deprecated.Functions.R +++ b/R/Deprecated.Functions.R @@ -54,73 +54,73 @@ read.simple.xls <- function(pfn = Stringendo::kollapse(...), row_namePos = NULL, # _________________________________________________________________________________________________ -#' -#' # _________________________________________________________________________________________________ -#' #' @title write.simple.xlsx.old -#' #' @description Write out a list of matrices/ data frames WITH ROW- AND COLUMN- -#' #' NAMES to a file with as an Excel (.xslx) file. Your output filename will be -#' #' either the variable's name. The output file will be located in "OutDir" -#' #' specified by you at the beginning of the script, or under your current -#' #' working directory. You can pass the PATH and VARIABLE separately (in -#' #' order), they will be concatenated to the filename. -#' #' @param named_list A list of data frames to write out -#' #' @param suffix A suffix added to the filename, Default: NULL -#' #' @param fname A string for a manually defined filename. Default: substitute(named_list) -#' #' @param o Set to TRUE to open file after writing out using 'system(open ...)' on OS X., Default: FALSE -#' #' @param TabColor Tab Color in Excel, Default: 'darkgoldenrod1' -#' #' @param Creator Creator, Default: '' -#' #' @param HeaderCex Header color, Default: 12 -#' #' @param HeaderLineColor Header line color, Default: 'darkolivegreen3' -#' #' @param HeaderCharStyle Header character style, Default: c("bold", "italic", "underline")[1] -#' #' @param row_names Have rownames? Default: TRUE -#' #' @param ... Multiple simple variables to parse. -#' #' @examples -#' #' \dontrun{ -#' #' if(interactive()){ -#' #' # write.simple.xlsx(my.list.of.data.frames) -#' #' } -#' #' } -#' #' @seealso -#' #' \code{\link[openxlsx]{write.xlsx}} -#' #' @export -#' #' @importFrom openxlsx write.xlsx createStyle -#' -#' write.simple.xlsx.old <- function(named_list -#' , filename = substitute(named_list) -#' , suffix = NULL -#' , o = FALSE -#' , TabColor = "darkgoldenrod1", HeaderLineColor = "darkolivegreen3" -#' , HeaderCex = 12, Creator = "" -#' , HeaderCharStyle = c("bold", "italic", "underline")[1] -#' , row_names = TRUE, ...) { -#' -#' warning("Switched using from openxlsx to readxl package 2023.11.22") -#' -#' fname <- Stringendo::sppp(filename, suffix) -#' if ( !('list' %in% class(named_list)) ) named_list <- list(named_list) # convert to a list if needed -#' -#' if (nchar(fname) > 100) fname <- kpp('_Output', idate()) -#' FnP <- kpp(kpps(getwd(), fname), "xlsx") -#' -#' hs <- openxlsx::createStyle(textDecoration = HeaderCharStyle, fontSize = HeaderCex -#' , fgFill = HeaderLineColor) -#' -#' if (row_names) { -#' FUNX <- function(x) rownames_to_column(as.data.frame(x), var = "genes") -#' named_list <- lapply(named_list, FUNX) -#' # named_list <- rownames_to_column(as.data.frame(named_list), var = "genes") -#' } -#' print(named_list) -#' print(rownames(named_list)) -#' -#' openxlsx::write.xlsx(x = named_list, file = FnP, rowNames = FALSE -#' , firstRow = TRUE -#' , firstCol = TRUE -#' , colWidths = "auto" -#' , headerStyle = hs, tabColour = TabColor, creator = Creator) -#' if (o) { system(paste0("open ", fix_special_characters_bash(FnP)), wait = FALSE) } -#' } # fun -#' +# +# # _________________________________________________________________________________________________ +# #' @title write.simple.xlsx.old +# #' @description Write out a list of matrices/ data frames WITH ROW- AND COLUMN- +# #' NAMES to a file with as an Excel (.xslx) file. Your output filename will be +# #' either the variable's name. The output file will be located in "OutDir" +# #' specified by you at the beginning of the script, or under your current +# #' working directory. You can pass the PATH and VARIABLE separately (in +# #' order), they will be concatenated to the filename. +# #' @param named_list A list of data frames to write out +# #' @param suffix A suffix added to the filename, Default: NULL +# #' @param fname A string for a manually defined filename. Default: substitute(named_list) +# #' @param o Set to TRUE to open file after writing out using 'system(open ...)' on OS X., Default: FALSE +# #' @param TabColor Tab Color in Excel, Default: 'darkgoldenrod1' +# #' @param Creator Creator, Default: '' +# #' @param HeaderCex Header color, Default: 12 +# #' @param HeaderLineColor Header line color, Default: 'darkolivegreen3' +# #' @param HeaderCharStyle Header character style, Default: c("bold", "italic", "underline")[1] +# #' @param row_names Have rownames? Default: TRUE +# #' @param ... Multiple simple variables to parse. +# #' @examples +# #' \dontrun{ +# #' if(interactive()){ +# #' # write.simple.xlsx(my.list.of.data.frames) +# #' } +# #' } +# #' @seealso +# #' \code{\link[openxlsx]{write.xlsx}} +# #' @export +# #' @importFrom openxlsx write.xlsx createStyle +# +# write.simple.xlsx.old <- function(named_list +# , filename = substitute(named_list) +# , suffix = NULL +# , o = FALSE +# , TabColor = "darkgoldenrod1", HeaderLineColor = "darkolivegreen3" +# , HeaderCex = 12, Creator = "" +# , HeaderCharStyle = c("bold", "italic", "underline")[1] +# , row_names = TRUE, ...) { +# +# warning("Switched using from openxlsx to readxl package 2023.11.22") +# +# fname <- Stringendo::sppp(filename, suffix) +# if ( !('list' %in% class(named_list)) ) named_list <- list(named_list) # convert to a list if needed +# +# if (nchar(fname) > 100) fname <- kpp('_Output', idate()) +# FnP <- kpp(kpps(getwd(), fname), "xlsx") +# +# hs <- openxlsx::createStyle(textDecoration = HeaderCharStyle, fontSize = HeaderCex +# , fgFill = HeaderLineColor) +# +# if (row_names) { +# FUNX <- function(x) rownames_to_column(as.data.frame(x), var = "genes") +# named_list <- lapply(named_list, FUNX) +# # named_list <- rownames_to_column(as.data.frame(named_list), var = "genes") +# } +# print(named_list) +# print(rownames(named_list)) +# +# openxlsx::write.xlsx(x = named_list, file = FnP, rowNames = FALSE +# , firstRow = TRUE +# , firstCol = TRUE +# , colWidths = "auto" +# , headerStyle = hs, tabColour = TabColor, creator = Creator) +# if (o) { system(paste0("open ", fix_special_characters_bash(FnP)), wait = FALSE) } +# } # fun +# # _________________________________________________________________________________________________ diff --git a/R/ReadWriter.R b/R/ReadWriter.R index 1e67a16..c197c54 100644 --- a/R/ReadWriter.R +++ b/R/ReadWriter.R @@ -957,10 +957,12 @@ write.simple.xlsx <- function( ) # assign row names if required + write_row_names <- has_row_names if (isFALSE(has_row_names)) { - assignRownames <- function(x) column.2.row.names(df, rowname_column = rowname_column, make_names = TRUE) + assignRownames <- function(x) column.2.row.names(x, rowname_column = rowname_column, make_names = TRUE) named_list <- lapply(named_list, assignRownames) message("Converting column ", rowname_column, " to row names: ", head(rownames(named_list[[1]]))) + write_row_names <- TRUE # the converted identifiers must still be written as the sheet's row names } FnP <- construct.file.path( @@ -970,7 +972,7 @@ write.simple.xlsx <- function( ) openxlsx::write.xlsx( - x = named_list, file = FnP, rowNames = has_row_names, + x = named_list, file = FnP, rowNames = write_row_names, firstRow = FreezeFirstRow, firstCol = FreezeFirstCol, headerStyle = hs, tabColour = TabColor, colWidths = "auto", creator = Creator @@ -1139,38 +1141,37 @@ write.simple.md.table <- function( #' @return The function does not return a value but writes the file to disk in the specified format. #' #' @importFrom qs qread +#' @importFrom stringi stri_detect_regex #' #' @export qs.2.table qs.2.table <- function(path, out_file = c("tsv", "csv", "csv2", "excel")[1]) { # Ensure that the file exists and is a .qs file - stopifnot(file.exists(path), stringi::stri_detect(str = path, regex = "\\.qs$")) + stopifnot(file.exists(path), stringi::stri_detect_regex(str = path, pattern = "\\.qs$")) # Ensure out_file is one of the allowed choices out_file <- match.arg(out_file, c("tsv", "csv", "csv2", "excel")) # Read in the .qs file - data <- qs:qread(path) + data <- qs::qread(path) - # Determine the output file extension and write the file based on the output format - path_out <- Stringendo::ppp(base_filename, out_file) - - if (out_file == "excel") { - # out_path <- ppp(base_filename, "xlsx") - Stringendo::ppp(base_filename, out_file) - ReadWriter::write.simple.xlsx(data, out_path) - } + # Base name (without extension) shared by all output formats + base_filename <- sub("\\.qs$", "", path) if (out_file == "tsv") { - ReadWriter::write.simple.tsv(data, path_out, separator = "\t") + ReadWriter::write.simple.tsv(data, manual_file_name = base_filename, separator = "\t") + out_path <- paste0(base_filename, ".tsv") } else if (out_file == "csv") { - ReadWriter::write.simple.tsv(data, path_out, separator = ",") + ReadWriter::write.simple.tsv(data, manual_file_name = base_filename, separator = ",") + out_path <- paste0(base_filename, ".csv") } else if (out_file == "csv2") { + ReadWriter::write.simple.tsv(data, manual_file_name = base_filename, separator = ";") out_path <- paste0(base_filename, ".csv") - ReadWriter::write.simple.tsv(data, path_out, separator = ";") } else if (out_file == "excel") { + # write.simple.xlsx() expects a list of sheets; wrap a bare table into one. + payload <- if (is.data.frame(data) || is.matrix(data)) list(data) else data + ReadWriter::write.simple.xlsx(payload, manual_file_name = base_filename) out_path <- paste0(base_filename, ".xlsx") - ReadWriter::write.simple.xlsx(data, out_path) } message("File saved as: ", out_path) diff --git a/man/convert.tsv.data.Rd b/man/convert.tsv.data.Rd index 5877db0..6992984 100644 --- a/man/convert.tsv.data.Rd +++ b/man/convert.tsv.data.Rd @@ -17,73 +17,6 @@ convert.tsv.data(df_by_read.simple.tsv, digitz = 2, na_rep = 0) Fix NA issues in data frames imported by the new read.simple.tsv. Set \code{na_rep} to NA if you want to keep NAs. } -\section{_________________________________________________________________________________________________}{ -#' @title write.simple.xlsx.old -#' @description Write out a list of matrices/ data frames WITH ROW- AND COLUMN- -#' NAMES to a file with as an Excel (.xslx) file. Your output filename will be -#' either the variable's name. The output file will be located in "OutDir" -#' specified by you at the beginning of the script, or under your current -#' working directory. You can pass the PATH and VARIABLE separately (in -#' order), they will be concatenated to the filename. -#' @param named_list A list of data frames to write out -#' @param suffix A suffix added to the filename, Default: NULL -#' @param fname A string for a manually defined filename. Default: substitute(named_list) -#' @param o Set to TRUE to open file after writing out using 'system(open ...)' on OS X., Default: FALSE -#' @param TabColor Tab Color in Excel, Default: 'darkgoldenrod1' -#' @param Creator Creator, Default: '' -#' @param HeaderCex Header color, Default: 12 -#' @param HeaderLineColor Header line color, Default: 'darkolivegreen3' -#' @param HeaderCharStyle Header character style, Default: c("bold", "italic", "underline")\link{1} -#' @param row_names Have rownames? Default: TRUE -#' @param ... Multiple simple variables to parse. -#' @examples -#' \dontrun{ -#' if(interactive()){ -#' # write.simple.xlsx(my.list.of.data.frames) -#' } -#' } -#' @seealso -#' \code{\link[openxlsx]{write.xlsx}} -#' @export -#' @importFrom openxlsx write.xlsx createStyle - -write.simple.xlsx.old <- function(named_list -, filename = substitute(named_list) -, suffix = NULL -, o = FALSE -, TabColor = "darkgoldenrod1", HeaderLineColor = "darkolivegreen3" -, HeaderCex = 12, Creator = "" -, HeaderCharStyle = c("bold", "italic", "underline")\link{1} -, row_names = TRUE, ...) { - -warning("Switched using from openxlsx to readxl package 2023.11.22") - -fname <- Stringendo::sppp(filename, suffix) -if ( !('list' \%in\% class(named_list)) ) named_list <- list(named_list) # convert to a list if needed - -if (nchar(fname) > 100) fname <- kpp('_Output', idate()) -FnP <- kpp(kpps(getwd(), fname), "xlsx") - -hs <- openxlsx::createStyle(textDecoration = HeaderCharStyle, fontSize = HeaderCex -, fgFill = HeaderLineColor) - -if (row_names) { -FUNX <- function(x) rownames_to_column(as.data.frame(x), var = "genes") -named_list <- lapply(named_list, FUNX) -# named_list <- rownames_to_column(as.data.frame(named_list), var = "genes") -} -print(named_list) -print(rownames(named_list)) - -openxlsx::write.xlsx(x = named_list, file = FnP, rowNames = FALSE -, firstRow = TRUE -, firstCol = TRUE -, colWidths = "auto" -, headerStyle = hs, tabColour = TabColor, creator = Creator) -if (o) { system(paste0("open ", fix_special_characters_bash(FnP)), wait = FALSE) } -} # fun -} - \seealso{ \code{\link[gtools]{na.replace}} }