Config file documentation

NEWS.md

@@ -17,7 +17,7 @@
 * Added automatic point scaling based on pedigree size.
 * Added optional segment size scaling based on pedigree size.
 * Hid the Sex key by default in `ggpedigree`.
-* Added a vignette describing `ggpedigree` configuration options.
+* Added two vignettes describing `ggpedigree` configuration options.
 
 ## Validation and messages
 * Performed required-column checks earlier in `ggpedigree()`, including `sex`.

vignettes/articles/v02_configuration.Rmd → vignettes/articles/v11_configuration_extended.Rmd

@@ -1,8 +1,8 @@
 ---
-title: "Extended: Using `config` to control ggpedigree plots"
+title: "Extended: More uses of `config` to control ggpedigree plots"
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{Extended: Using config to control ggpedigree plots}
+  %\VignetteIndexEntry{Extended: More uses of config to control ggpedigree plots}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
@@ -24,19 +24,16 @@ library(viridis) # viridis for color palettes
 library(tidyverse) # for data wrangling
 ```
 
-Every gg-based plotting function in `{ggpedigree}` accepts a `config` argument.
+Every gg-based plotting function in `{ggpedigree}` accepts a `config` argument. This is an easier way to control plot behavior without rewriting the plotting code.
 
-This is an easier way to control plot behavior without rewriting the plotting code.
-
-A `config` is a named list. Each element corresponds to one plotting, layout, or aesthetic option. You pass the list to the plotting function and the plot is drawn using those values.
+As already discussed, a `config` is a named list. Each element corresponds to one plotting, layout, or aesthetic option. You pass the list to the plotting function and the plot is drawn using those values.
 
 You do not need to supply every option. You only provide the options you want to change. Any options you do not specify will use the package defaults. You can see a full list of supported options and their defaults by reviewing the documentation for `getDefaultPlotConfig()`.
 
-This vignette demonstrates how `config` is used in practice.
 
 # Basic usage of `config` in `ggPedigree()`
 
-We will use the `potter` pedigree dataset bundled in `{BGmisc}`.
+As before, we will use the `potter` pedigree dataset bundled in `{BGmisc}`.
 
 ```{r}
 library(BGmisc)
@@ -77,7 +74,7 @@ ggPedigree(
   config = list(
     code_male = 1,
     code_female = 2,
-    code_unknown = 0
+    code_unknown = 3
   )
 )
 
@@ -293,7 +290,7 @@ plot_ped <- ggPedigree(
     sex_shape_male = "🚗"
   )
 )
-plot_ped
+
 ggplot2::ggsave(
   filename = "custom_sex_emoji_pedigree.png",
   plot = plot_ped,
@@ -303,10 +300,15 @@ ggplot2::ggsave(
 )
 ```
 
-Note that when using emoji shapes, it is best to use `ggsave()` to save the plot to a file, as some R graphics devices may not render emoji correctly. Notice how the emoji shapes appear in the saved PNG file below compares to the image rendered above, which may vary because of differences in font rendering.
+
+![](emoji_preview.png){width="7in" height="5in"}
+
+Note that when using emoji shapes, it is best to use `ggsave()` to save the plot to a file, as some R graphics devices may  render emoji differently. Notice how the emoji shapes appear in the saved PNG file below compares to the image rendered during the preview above. These may vary because of differences in font rendering.
 
 ![](custom_sex_emoji_pedigree.png){width="7in" height="5in"}
 
+
+
 ## 5) Affected status overlay
 
 Affected status behavior is controlled by keys such as:

vignettes/v00_plots.Rmd

@@ -377,4 +377,4 @@ p +
 
 # Advanced Examples: Large Pedigrees with self-loops
 
-Additional examples are provided as articles that demonstrate more complex pedigree plots. You can find these on the [ggpedigree website](https://r-computing-lab.github.io/ggpedigree/). These articles cover advanced topics such as: multiple families, self-loops, and other advanced features.
+Additional examples are available in the online documentation to keep the package file size reasonable. These are provided as articles that demonstrate more complex pedigree plots. You can find these on the [ggpedigree website](https://r-computing-lab.github.io/ggpedigree/). These articles cover advanced topics such as: multiple families, self-loops, and other advanced features.

vignettes/v10_configuration.R

@@ -0,0 +1,28 @@
+## ----setup, include=FALSE-----------------------------------------------------
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  fig.width = 7,
+  fig.height = 5
+)
+
+## ----libraries, message=FALSE, warning=FALSE----------------------------------
+library(ggpedigree) # ggPedigree lives here
+library(BGmisc) # helper utilities & example data
+library(ggplot2) # ggplot2 for plotting
+library(viridis) # viridis for color palettes
+library(tidyverse) # for data wrangling
+
+## -----------------------------------------------------------------------------
+library(BGmisc)
+data("potter")
+
+## -----------------------------------------------------------------------------
+ggPedigree(
+  potter,
+  famID = "famID",
+  personID = "personID",
+  momID = "momID",
+  dadID = "dadID"
+)
+

vignettes/v10_configuration.Rmd

@@ -0,0 +1,101 @@
+---
+title: "Using config to control ggpedigree plots"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Using config to control ggpedigree plots}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r setup, include=FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  fig.width = 7,
+  fig.height = 5
+)
+```
+
+```{r libraries, message=FALSE, warning=FALSE}
+library(ggpedigree) # ggPedigree lives here
+library(BGmisc) # helper utilities & example data
+library(ggplot2) # ggplot2 for plotting
+library(viridis) # viridis for color palettes
+library(tidyverse) # for data wrangling
+```
+
+This vignette demonstrates how to use the `config` argument to control the behavior of pedigree plots in the `{ggpedigree}` package.
+
+Every gg-based plotting function in `{ggpedigree}` accepts a `config` argument. A `config` is a named list. Each element corresponds to one plotting, layout, or aesthetic option. You pass the list to the plotting function and the plot is drawn using those values.
+
+You do not need to supply every option. You only provide the options you want to change. Any options you do not specify will use the package defaults. You can see a full list of supported options and their defaults by reviewing the documentation for `getDefaultPlotConfig()`.
+
+This vignette demonstrates how `config` is used in practice. An extended list of all available options is provided in the online documentation.
+
+# Basic usage of `config` in `ggPedigree()`
+
+We will use the `potter` pedigree dataset bundled in `{BGmisc}`.
+
+```{r}
+library(BGmisc)
+data("potter")
+```
+
+A basic pedigree plot uses defaults:
+
+```{r}
+ggPedigree(
+  potter,
+  famID = "famID",
+  personID = "personID",
+  momID = "momID",
+  dadID = "dadID"
+)
+```
+
+## Sex coding: `code_male` and `code_female`
+
+`ggPedigree()` (and other ggpedigree plots that use sex) need to know how sex is encoded in your data so they can assign the correct **shapes** (and optionally **colors**) for female, male, and unknown.
+
+The `code_male` and `code_female` config options define which values in your sex column should be treated as male vs female. The defaults assume:
+
+-   `code_female = 0`
+-   `code_male = 1`
+
+If your dataset uses different codes (for example `1/2` or `"M"/"F"`), override these in `config`.
+
+``` r
+# Example: sex coded as 1 = male, 2 = female
+ggPedigree(
+  ped,
+  famID = "famID",
+  personID = "personID",
+  momID = "momID",
+  dadID = "dadID",
+  config = list(
+    code_male = 1,
+    code_female = 2,
+    code_unknown = 3
+  )
+)
+
+# Example: sex coded as "M" / "F"
+ggPedigree(
+  ped,
+  famID = "famID",
+  personID = "personID",
+  momID = "momID",
+  dadID = "dadID",
+  config = list(
+    code_male = "M",
+    code_female = "F"
+  )
+)
+```
+
+Once the sex codes are interpreted correctly, the plot uses the corresponding shape settings (`sex_shape_female`, `sex_shape_male`, `sex_shape_unknown`) and, when enabled, sex-based coloring (`sex_color_include`, `sex_color_palette`).
+
+
+# Advanced Examples
+
+Additional examples are available in the online documentation to keep the package file size reasonable. These are provided as articles that demonstrate more complex pedigree plots. You can find these on the [ggpedigree website](https://r-computing-lab.github.io/ggpedigree/).