Merge pull request #34 from JulienBlasco/evolution-api-meta

New package version 1.0.0

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: tablexlsx
 Type: Package
 Title: Export Data Frames to Excel Workbook
-Version: 0.2.0
+Version: 1.0.0
 Authors@R:
     c(person(given = "Damien",
              family = "Dotta",

NEWS.md

@@ -1,13 +1,12 @@
-# tablexlsx (WIP)
+# tablexlsx 1.0.0
 
 This release includes :
 
-* `asTable` argument is now set to FALSE in function `add_table()` and `toxlsx()` #24
-* Slight changes to API in order to solve #19, #21 and #26 
-
-The main changes are that `mergecol` can now be used with multiple data frames, and that we can only supply character arguments instead of lists in the following cases:
-1. There is only one data.frame
-2. The value of the argument is to be the same for all data frames (e.g. same footnote)
+* `add_table()` and `toxlsx()` now accept a `bygroup` argument that splits the table into groups before writing to the sheet #23
+* most arguments to `add_table()` and `toxlsx()` can now be passed as atomic vectors. If the first argument is a single `data.frame`, the behavior is the same as for a lenght-one list. If the first argument is a list of `data.frame`s, those arguments are recycled in order to match the length of the list. This change applies to the arguments `tosheet`, `title`, `footnoteX`, `mergecol`, `bygroup`, `groupname` #19
+* when a list is passed to `toxlsx()`, the `mergecol` argument can now be specified for each data.frame of the list #21
+* `asTable` argument is now set to FALSE in functions `add_table()` and `toxlsx()` #24
+* Slight changes to API in order to solve #16 and #21 
 
 # tablexlsx 0.2.1
 

vignettes/aa-examples.Rmd

@@ -27,8 +27,9 @@ library(magrittr)
 2. [Export a list of several data frames to an xlsx file (each data frame in a different sheet)](#export-a-list-of-several-data-frames-to-an-xlsx-file-each-data-frame-in-a-different-sheet)
 3. [Export a data frame to an xlsx file (merging modalities for one column)](#export-a-data-frame-to-an-xlsx-file-merging-modalities-for-one-column)
 4. [Export a data frame to an xlsx file (merging modalities for several columns)](#export-a-data-frame-to-an-xlsx-file-merging-modalities-for-several-columns)
-5. [Export a list of several data frames to an xlsx file (several data frames in a same sheet)](#export-a-list-of-several-data-frames-to-an-xlsx-file-several-data-frames-in-a-same-sheet)
-6. [Export a list of data frames to an named xlsx file by specifying which data frame goes in which sheet, styling each column, giving a title and footnotes...](#export-a-list-of-data-frames-to-an-named-xlsx-file-by-specifying-which-data-frame-goes-in-which-sheet-styling-each-column-giving-a-title-and-footnotes)
+5. [Export a data frame to an xlsx file (splitting the data frame into groups)](#export-a-data-frame-to-an-xlsx-file-splitting-the-data-frame-into-groups)
+6. [Export a list of several data frames to an xlsx file (several data frames in a same sheet)](#export-a-list-of-several-data-frames-to-an-xlsx-file-several-data-frames-in-a-same-sheet)
+7. [Export a list of data frames to an named xlsx file by specifying which data frame goes in which sheet, styling each column, giving a title and footnotes...](#export-a-list-of-data-frames-to-an-named-xlsx-file-by-specifying-which-data-frame-goes-in-which-sheet-styling-each-column-giving-a-title-and-footnotes)
 
 Let's define an export folder that will be the same for all the examples on this page
 
@@ -85,16 +86,40 @@ Preview of the xlsx file in LibreOffice Calc :
 
 ## 4. Export a data frame to an xlsx file (merging modalities for several columns)
 
-```{r df-export-merge-, eval = FALSE}
+```{r df-export-merge-multiple, eval = FALSE}
+sorted_mtcars <- mtcars[
+  order(mtcars$gear, mtcars$am),
+  c("gear", "am", setdiff(names(mtcars), c("gear", "am")))
+  ]
+
+sorted_mtcars |>
+  toxlsx(path = mypath, mergecol = c("gear", "am"))
+```
+
+Preview of the xlsx file in LibreOffice Calc :  
+
+<img src="../man/figures/preview_Calc_ex4.png" width="100%" />
+
+## 5. Export a data frame to an xlsx file (splitting the data frame into groups)
+
+```{r df-export-split, eval = FALSE}
+df1 |> toxlsx(path = mypath, bygroup= "group", groupname=TRUE)
+```
+
+<img src="../man/figures/preview_Calc_exsplit.png" width="100%" />
+
+## 6. Export a list of several data frames to an xlsx file (several data frames in a same sheet)
+
+```{r list-export-same, eval = FALSE}
 tb1 <- data.frame(tables = c(rep("iris",5),rep("cars",2)),
                   var = c(names(iris),names(cars)))
 
 tb2 <- data.frame(tables = c("iris","cars","cars"),
                   rownumber = c(150,50,32))
 
 list(tb1,tb2) |>
-  toxlsx(tosheet = list("tb1" = "mydata",
-                        "tb2" = "mydata"),
+  toxlsx(tosheet = "mydata",
+         mergecol = "tables",
          footnote1 = list("tb1" = "The data set contains 3 classes of 50 instances each, where each class refers to a type of iris plant.",
                           "tb2" = "The data give the speed of cars and the distances taken to stop. Note that the data were recorded in the 1920s."),
          footnote2 = list("tb1" = "Predicted attribute: class of iris plant.",
@@ -104,11 +129,13 @@ list(tb1,tb2) |>
          path=mypath)
 ```
 
+Note that the arguments `tosheet` and `mergecol`, being length-one character vectors, are recycled for all data frames of the list.
+
 Preview of the xlsx file in LibreOffice Calc :  
 
 <img src="../man/figures/preview_Calc_ex5.png" width="100%" />
 
-## 6. Export a list of data frames to an named xlsx file by specifying which data frame goes in which sheet, styling each column, giving a title and footnotes...
+## 7. Export a list of data frames to an named xlsx file by specifying which data frame goes in which sheet, styling each column, giving a title and footnotes...
 
 ```{r list-export-complicated, eval = FALSE}
 iris <- iris %>% head()
@@ -119,6 +146,8 @@ list(iris,cars) |>
                         "cars" = "second"),
          title = list("iris" = "Head of iris",
                       "cars" = "Head of cars"),
+         mergecol = list("iris" = "Species",
+                         "cars" = "speed"),
          # The `columnstyle` argument is optional in toxlsx(). 
          # It is used only if you want to specify the format of each column
          columnstyle = list("iris" = list("c1" = "decimal",