doc update

Author: dcomtois

NEWS.md

@@ -5,17 +5,20 @@
     when `NA`s are detected.
 - In `tb()`
   + Fix for broken proportions in freq tables
-  + New parameters `fct.to.chr` and `recalculate` for freq tables
+  + New parameters `fct.to.chr` and `recalculate` for `freq()` tables
   + Parameter `na.rm` deprecated
  - In `dfSummary()`: 
    + New parameter `class` allows switching off class reporting in *Variable*
      column.
- - In `freq()` & `ctable()`: 
-   + New parameter `na.val` allows specifying a value (factor level) that
+ - In `freq()`, `ctable()` and `dfSummary()`: 
+   + New parameter `na.val` allows specifying a value / factor level that
      is to be considered `NA`. In turn, the value "(Missing)" is no longer
-     considered missing by default; using `na.val = "(Missing)"`
-     will yield the same results.
+     considered missing by default (using `na.val = "(Missing)"`
+     will yield the same results).
    + Fix for weights not being applied correctly in by-group processing.
+   + **Labelled vectors** ("labelled" / "haven_labelled") are treated like
+     factors in `freq()`, and in `dfSummary()` when all values have a label.
+     Future versions will extend support to `ctable()`. 
  - In `descr()`: 
    + "n" (total number of observations, also displayed in heading) added to
      available statistics.
@@ -25,8 +28,7 @@
      excludes *Pct. Valid* from, *common* statistics.
    + Fix for *N* in header showing 1st group's size rather than global size.
    + Fix for weights not being applied correctly in by-group processing.
-- Optimized metadata extraction
-- Improved support for dplyr::group_by()
+- `define_keywords()` now uses RStudio's api for dialogs.
 - `llabel()` wrapper added for `label(x, all = TRUE)`
 
 # summarytools 1.0.2 (2022-07-10)

vignettes/introduction.Rmd

@@ -74,7 +74,7 @@ txt <- data.frame(
 )
 
 kable(txt, format = "html", escape = FALSE, align = c('l', 'l')) |>
-  kable_paper(full_width = FALSE, position = "left") |>
+  kable_classic(full_width = FALSE, position = "left") |>
   column_spec(1, extra_css = "vertical-align:top") |>
   column_spec(2, extra_css = "vertical-align:top")
 ```
@@ -115,11 +115,9 @@ Results can be
    weights 
  - **Multilingual**: 
    + Built-in translations exist for French, Portuguese, Spanish, Russian, and
-     Turkish. Users can easily add custom translations or modify existing ones
-     as needed 
+     Turkish. Users can easily add custom translations or modify existing
+     languages at will 
  - **Flexible and extensible**: 
-   + The built-in features used to support alternate languages provide a way to
-     modify a great number of terms used in outputs (headings and tables) 
    + **Pipe operators** from
      [magrittr](https://cran.r-project.org/package=magrittr) (`%>%`, `%$%`) and
      [pipeR](https://cran.r-project.org/package=pipeR) (`%>>%`) are fully
@@ -130,6 +128,12 @@ Results can be
    + **By-group processing** is easily achieved using the package's `stby()`
      function which is a slightly modified version of `base::by()`, but
      `dplyr::group_by()` is also supported 
+   + Version 1.1 introduced support for **labelled vectors** (classes *labelled* 
+     / *haven_labelled*), which are being treated as factors in `freq()`, and
+     in `dfSummary()` when all values are labelled. A future release will have
+     `ctable()` behave similarly. 
+   + Parameter `na.val` allows treating a special value as `NA` in `freq()`,
+     `ctable()` and `dfSummary()` (feature introduced in version 1.1.0). 
    + [**Pander options**](http://rapporter.github.io/pander/) can be used to
      customize or enhance plain text and markdown tables 
    + Base R's `format()` arguments are also supported by **summarytools**'
@@ -567,8 +571,10 @@ dfs$Variable <- NULL # This deletes the Variable column
 # 6. Grouped Statistics: stby() 
 
 To produce optimal results, **summarytools** has its own version of
-the base `by()` function. It's called `stby()`, and we use it exactly as we
-would `by()`:
+the base `by()` function. It's called `stby()`, and we use it as we
+would `by()`, with a notable difference: set the `useNA` parameter to `TRUE` 
+to create an additional group for observations containing `NA`s on the grouping variable(s) (see example in section 6.2).
+
 
 ```{r}
 (iris_stats_by_species <- stby(data      = iris, 
@@ -578,6 +584,7 @@ would `by()`:
                                transpose = TRUE))
 ```
 
+
 ## 6.1 Special Case of descr() with stby()
 
 When used to produce split-group statistics for a single variable, `stby()`
@@ -589,7 +596,8 @@ with(tobacco,
      stby(data    = BMI, 
           INDICES = age.gr, 
           FUN     = descr,
-          stats   = c("mean", "sd", "min", "med", "max"))
+          stats   = c("mean", "sd", "min", "med", "max"),
+          useNA   = TRUE)
 )
 ```
 
@@ -623,10 +631,8 @@ with(tobacco,
 
 To create grouped statistics with `freq()`, `descr()` or `dfSummary()`, it is
 possible to use **dplyr**'s `group_by()` as an alternative to `stby()`.
-Syntactic differences aside, one key distinction is that `group_by()` considers
-`NA` values on the grouping variable(s) as a valid category, albeit with a
-warning suggesting the use of `forcats::fct_na_value_to_level` to make
-`NA`'s explicit in factors. Following this advice, we get:
+Usings `forcats::fct_na_value_to_level` to make `NA`'s explicit in factors is
+recommended:
 
 ```{r, eval=FALSE}
 library(dplyr)
@@ -1263,8 +1269,8 @@ The package comes with no guarantees. It is a work in progress and
 feedback is welcome. Please open an [issue on GitHub](https://github.com/dcomtois/summarytools/issues) if you find a
 bug or wish to submit a feature request.
 
-**summarytools** is the result of **many** hours of work. If you find the
-package brings value to your work, please take a moment to make a small
+**summarytools** is the result of many hours of work. If it
+brings value to your work, please consider making a small
 donation using this [Paypal link](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=HMN3QJR7UMT7S&item_name=Help+scientists,+data+scientists+and+analysts+around+the+globe&currency_code=CAD&source=url).