add rename_languages argument; fix some documentation

Author: agricolamz

R/ec_tile_map.R

@@ -7,6 +7,10 @@
 #' @param annotate_feature Logical variable that specifies, whether to add feature values on the tile. This especially make sense in case of numeric features. Default value is \code{FALSE}.
 #' @param abbreviation Logical variable that specifies, whether use abbreviations for languages specified in the package. Default value is \code{TRUE}.
 #' @param hide_languages Character variable that specifies, which languages should be removed from the template.
+#' @param rename_languages This variable maps old language names to their corresponding new names. It can be represented as either:
+#' \itemize{
+#' \item{A named vector, where names are the old language names and values are the corresponding new language names.}
+#' \item{A data frame with two columns: \code{language} (the old language names) and \code{new_language_name} (the corresponding new language names).}}
 #'
 #' @returns a `ggplot2` object
 #' @export
@@ -43,7 +47,8 @@ ec_tile_map <- function(data = NULL,
                         title_position = "left",
                         annotate_feature = FALSE,
                         abbreviation = TRUE,
-                        hide_languages = NULL) {
+                        hide_languages = NULL,
+                        rename_languages = NULL) {
 
   # arguments check ---------------------------------------------------------
 
@@ -67,9 +72,33 @@ ec_tile_map <- function(data = NULL,
               is.character(hide_languages) | is.null(hide_languages),
             "The argument 'hide_languages' should be a character vector with languages, see 'ec_languages$language' for the possible values" =
               is.null(hide_languages) |
-              hide_languages %in% RCaucTile::ec_languages$language)
+              hide_languages %in% RCaucTile::ec_languages$language,
+            "The argument 'rename_languages' should be either a named character vector with languages as a name or dataframe with columns 'language' and 'new_language_name', see 'ec_languages$language' for the possible values" =
+              is.null(rename_languages) | "character" %in% class(rename_languages) | "data.frame" %in% class(rename_languages))
 
-  # redefine title_position -------------------------------------------------
+  if("data.frame" %in% class(rename_languages)){
+    stopifnot(
+      "The argument 'rename_languages' should be either a named character vector with languages as a name or dataframe with columns 'language' and 'new_language_name', see 'ec_languages$language' for the possible values" =
+        "language" %in% colnames(rename_languages),
+      "The argument 'rename_languages' should be either a named character vector with languages as a name or dataframe with columns 'language' and 'new_language_name', see 'ec_languages$language' for the possible values" =
+        "new_language_name" %in% colnames(rename_languages),
+      "The 'language' column in 'rename_languages' contains unexpected values, see 'ec_languages$language' for the possible values" =
+        rename_languages$language %in% RCaucTile::ec_languages$language)
+  } else if("character" %in% class(rename_languages)){
+    stopifnot(
+      "The names in 'rename_languages' contain unexpected values, see 'ec_languages$language' for the possible values" =
+        names(rename_languages) %in% RCaucTile::ec_languages$language)
+  }
+
+# restructure rename_languages --------------------------------------------
+
+  if("character" %in% class(rename_languages)){
+    rename_languages <- as.data.frame(rename_languages)
+    colnames(rename_languages) <- "new_language_name"
+    rename_languages$language <- rownames(rename_languages)
+  }
+
+# redefine title_position -------------------------------------------------
 
   if(title_position == "left") {
     title_position <- 0
@@ -99,15 +128,30 @@ ec_tile_map <- function(data = NULL,
       "The argument 'feature_column' should be a character vector with one value" =
         length(feature_column) == 1)
 
-    # merge EC dataset with data provided by a user ---------------------------
+# merge EC dataset with data provided by a user ---------------------------
 
     for_plot <- merge(RCaucTile::ec_languages, data, all.x = TRUE)
 
+
+# rename languages --------------------------------------------------------
+
+    if(!is.null(rename_languages)){
+      for_plot <- merge(for_plot, rename_languages, all.x = TRUE)
+      for_plot$language <- ifelse(is.na(for_plot$new_language_name),
+                                  for_plot$language,
+                                  for_plot$new_language_name)
+      for_plot$abbreviation <- ifelse(is.na(for_plot$new_language_name),
+                                  for_plot$abbreviation,
+                                  for_plot$new_language_name)
+    }
+
+# hide languages ----------------------------------------------------------
+
     if(!is.null(hide_languages)){
       for_plot <- for_plot[!(for_plot$language %in% hide_languages), ]
     }
 
-    # create a column with the name feature if there is no one ----------------
+# create a column with the name feature if there is no one ----------------
 
     names(for_plot)[names(for_plot) == feature_column] <- "feature"
 

docs/index.html

@@ -400,12 +400,12 @@ <h2 data-number="5" class="anchored" data-anchor-id="changing-values-order"><spa
 <section id="changing-the-language-template" class="level2" data-number="6">
 <h2 data-number="6" class="anchored" data-anchor-id="changing-the-language-template"><span class="header-section-number">6</span> Changing the language template</h2>
 <p>The East Caucasian language family exhibits significant dialectal differentiation. A unified genealogical classification of all idioms spoken in Daghestan does not exist. The default language inventory in <code>RCaucTile</code> is based on the genealogical classification from the Typological Atlas of the Languages of Daghestan (see <a href="https://lingconlab.ru/tald/languages.html">the languages page</a>). Therefore, it is highly probable that some researchers may wish to modify the default inventory by removing or altering the names of existing units.</p>
-<p>To remove specific languages from the template, list the desired languages in the <code>remove_languages</code> argument.</p>
+<p>To remove specific languages from the template, list the desired languages in the <code>hide_languages</code> argument.</p>
 <div class="cell">
 <div class="sourceCode cell-code" id="cb25"><pre class="sourceCode r code-with-copy"><code class="sourceCode r"><span id="cb25-1"><a href="#cb25-1" aria-hidden="true" tabindex="-1"></a><span class="fu">ec_tile_map</span>(ec_languages,</span>
 <span id="cb25-2"><a href="#cb25-2" aria-hidden="true" tabindex="-1"></a>            <span class="at">feature_column =</span> <span class="st">"morning_greetings"</span>,</span>
 <span id="cb25-3"><a href="#cb25-3" aria-hidden="true" tabindex="-1"></a>            <span class="at">title =</span> <span class="st">"Morning greetings (Naccarato, Verhees 2021)"</span>,</span>
-<span id="cb25-4"><a href="#cb25-4" aria-hidden="true" tabindex="-1"></a>            <span class="at">remove_languages =</span> <span class="fu">c</span>(<span class="st">"Gigatli"</span>, <span class="st">"Shari"</span>))</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<span id="cb25-4"><a href="#cb25-4" aria-hidden="true" tabindex="-1"></a>            <span class="at">hide_languages =</span> <span class="fu">c</span>(<span class="st">"Gigatli"</span>, <span class="st">"Shari"</span>))</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
 <div class="cell-output-display">
 <div>
 <figure class="figure">
@@ -414,7 +414,52 @@ <h2 data-number="6" class="anchored" data-anchor-id="changing-the-language-templ
 </div>
 </div>
 </div>
-<p>In order to change the names of existing languages in the template, you need …</p>
+<p>In order to change the names of existing languages in the template, you need to provide the <code>rename_languages</code> argument with an object that maps old language names to their corresponding new names. This can be represented as either:</p>
+<ul>
+<li>A named vector, where the names are the old language names and the values are the corresponding new language names.</li>
+</ul>
+<div class="cell">
+<div class="sourceCode cell-code" id="cb26"><pre class="sourceCode r code-with-copy"><code class="sourceCode r"><span id="cb26-1"><a href="#cb26-1" aria-hidden="true" tabindex="-1"></a>new_language_names <span class="ot">&lt;-</span> <span class="fu">c</span>(<span class="st">"Upper Andi"</span> <span class="ot">=</span> <span class="st">"Andi"</span>,</span>
+<span id="cb26-2"><a href="#cb26-2" aria-hidden="true" tabindex="-1"></a>                        <span class="st">"Northern Akhvakh"</span> <span class="ot">=</span> <span class="st">"Akhvakh"</span>)</span>
+<span id="cb26-3"><a href="#cb26-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb26-4"><a href="#cb26-4" aria-hidden="true" tabindex="-1"></a><span class="fu">ec_tile_map</span>(ec_languages,</span>
+<span id="cb26-5"><a href="#cb26-5" aria-hidden="true" tabindex="-1"></a>            <span class="at">feature_column =</span> <span class="st">"morning_greetings"</span>,</span>
+<span id="cb26-6"><a href="#cb26-6" aria-hidden="true" tabindex="-1"></a>            <span class="at">title =</span> <span class="st">"Morning greetings (Naccarato, Verhees 2021)"</span>,</span>
+<span id="cb26-7"><a href="#cb26-7" aria-hidden="true" tabindex="-1"></a>            <span class="at">hide_languages =</span> <span class="fu">c</span>(<span class="st">"Lower Andi"</span>, <span class="st">"Southern Akhvakh"</span>),</span>
+<span id="cb26-8"><a href="#cb26-8" aria-hidden="true" tabindex="-1"></a>            <span class="at">rename_languages =</span> new_language_names)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output-display">
+<div>
+<figure class="figure">
+<p><img src="index_files/figure-html/unnamed-chunk-20-1.png" class="img-fluid figure-img" width="1152"></p>
+</figure>
+</div>
+</div>
+</div>
+<ul>
+<li>A data frame with two columns: <code>language</code> (the old language names) and <code>new_language_name</code> (the corresponding new language names).</li>
+</ul>
+<div class="cell">
+<div class="sourceCode cell-code" id="cb27"><pre class="sourceCode r code-with-copy"><code class="sourceCode r"><span id="cb27-1"><a href="#cb27-1" aria-hidden="true" tabindex="-1"></a>new_language_names <span class="ot">&lt;-</span> <span class="fu">data.frame</span>(<span class="at">language =</span> <span class="fu">c</span>(<span class="st">"Upper Andi"</span>, <span class="st">"Northern Akhvakh"</span>),</span>
+<span id="cb27-2"><a href="#cb27-2" aria-hidden="true" tabindex="-1"></a>                                 <span class="at">new_language_name =</span> <span class="fu">c</span>(<span class="st">"Andi"</span>, <span class="st">"Akhvakh"</span>))</span>
+<span id="cb27-3"><a href="#cb27-3" aria-hidden="true" tabindex="-1"></a></span>
+<span id="cb27-4"><a href="#cb27-4" aria-hidden="true" tabindex="-1"></a><span class="fu">ec_tile_map</span>(ec_languages,</span>
+<span id="cb27-5"><a href="#cb27-5" aria-hidden="true" tabindex="-1"></a>            <span class="at">feature_column =</span> <span class="st">"morning_greetings"</span>,</span>
+<span id="cb27-6"><a href="#cb27-6" aria-hidden="true" tabindex="-1"></a>            <span class="at">title =</span> <span class="st">"Morning greetings (Naccarato, Verhees 2021)"</span>,</span>
+<span id="cb27-7"><a href="#cb27-7" aria-hidden="true" tabindex="-1"></a>            <span class="at">hide_languages =</span> <span class="fu">c</span>(<span class="st">"Lower Andi"</span>, <span class="st">"Southern Akhvakh"</span>),</span>
+<span id="cb27-8"><a href="#cb27-8" aria-hidden="true" tabindex="-1"></a>            <span class="at">rename_languages =</span> new_language_names)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
+<div class="cell-output-display">
+<div>
+<figure class="figure">
+<p><img src="index_files/figure-html/unnamed-chunk-21-1.png" class="img-fluid figure-img" width="1152"></p>
+</figure>
+</div>
+</div>
+</div>
+<p>As shown in the example above, we merged:</p>
+<ul>
+<li>Upper and Lower Andi into the joint “Andi” variable;</li>
+<li>Southern and Northern Akhvakh into the joint “Akhvakh” variable.</li>
+</ul>
 </section>
 
 </main>

docs/index.qmd

@@ -205,4 +205,35 @@ ec_tile_map(ec_languages,
             hide_languages = c("Gigatli", "Shari"))
 ```
 
-In order to change the names of existing languages in the template, you need ...
+In order to change the names of existing languages in the template, you need to provide the `rename_languages` argument with an object that maps old language names to their corresponding new names. This can be represented as either:
+
+- A named vector, where the names are the old language names and the values are the corresponding new language names.
+
+```{r}
+new_language_names <- c("Upper Andi" = "Andi",
+                        "Northern Akhvakh" = "Akhvakh")
+
+ec_tile_map(ec_languages,
+            feature_column = "morning_greetings",
+            title = "Morning greetings (Naccarato, Verhees 2021)",
+            hide_languages = c("Lower Andi", "Southern Akhvakh"),
+            rename_languages = new_language_names)
+```
+
+- A data frame with two columns: `language` (the old language names) and `new_language_name` (the corresponding new language names).
+
+```{r}
+new_language_names <- data.frame(language = c("Upper Andi", "Northern Akhvakh"),
+                                 new_language_name = c("Andi", "Akhvakh"))
+
+ec_tile_map(ec_languages,
+            feature_column = "morning_greetings",
+            title = "Morning greetings (Naccarato, Verhees 2021)",
+            hide_languages = c("Lower Andi", "Southern Akhvakh"),
+            rename_languages = new_language_names)
+```
+
+As shown in the example above, we merged:
+
+- Upper and Lower Andi into the joint "Andi" variable;
+- Southern and Northern Akhvakh into the joint "Akhvakh" variable.