From e20d857023ec5b7974f4526e1fe189188fc95abf Mon Sep 17 00:00:00 2001 From: chartgerink Date: Mon, 11 Nov 2024 14:42:00 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20epiverse?= =?UTF-8?q?-trace/safeframe@c1d267c6865d9a60d5b166364fa37c2188209844=20?= =?UTF-8?q?=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pkgdown.yml | 2 +- reference/index.html | 6 ++ reference/label_variables.html | 110 +++++++++++++++++++++++++++++++++ search.json | 2 +- sitemap.xml | 1 + 5 files changed, 119 insertions(+), 2 deletions(-) create mode 100644 reference/label_variables.html diff --git a/pkgdown.yml b/pkgdown.yml index fdf92ea..89e441d 100644 --- a/pkgdown.yml +++ b/pkgdown.yml @@ -4,7 +4,7 @@ pkgdown_sha: c40ba2c989e786bbb2829b431114d26375bbe19a articles: compat-dplyr: compat-dplyr.html design-principles: design-principles.html -last_built: 2024-11-11T14:31Z +last_built: 2024-11-11T14:41Z urls: reference: https://epiverse-trace.github.io/safeframe/reference article: https://epiverse-trace.github.io/safeframe/articles diff --git a/reference/index.html b/reference/index.html index d64f701..b462b46 100644 --- a/reference/index.html +++ b/reference/index.html @@ -66,6 +66,12 @@

All functionstidyverse functions
+ label_variables() + +
+
Add labels to variables
+
+ labels()
diff --git a/reference/label_variables.html b/reference/label_variables.html new file mode 100644 index 0000000..8ea5722 --- /dev/null +++ b/reference/label_variables.html @@ -0,0 +1,110 @@ + +Add labels to variables — label_variables • safeframe + Skip to contents + + +
+
+
+

Add labels to variables

+ Source: R/label_variables.R +
label_variables.Rd
+
+ +
+

Internal. This function will label pre-defined variables in a +data.frame by adding a label attribute to the column. This can be used for +one or multiple variables at the same time.

+
+ +
+

Usage

+ 
label_variables(x, labels)
+
+ +
+

Arguments

+ + +
x
+

a data.frame or a tibble, with at least one column

+ + +
labels
+

A named list with variable names in x as list names and the +labels as list values. Values set to NULL remove the label.

+ +
+
+

Value

+

The function returns the original object with an additional "label" +attribute on each provided variable.

+
+
+

Details

+

If used several times, the previous label is removed silently. +Only accepts known variables from the provided data.frame.

+
+ +
+ + +
+

Developed by Chris Hartgerink.

+
+ +
+

Site built with pkgdown 2.1.1.9000.

+
+ +
+ + + + + + + diff --git a/search.json b/search.json index 72b20d3..2c49a54 100644 --- a/search.json +++ b/search.json @@ -1 +1 @@ -[{"path":"https://epiverse-trace.github.io/safeframe/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"MIT License","title":"MIT License","text":"Copyright (c) 2022 package authors Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"verbs-operating-on-rows","dir":"Articles","previous_headings":"","what":"Verbs operating on rows","title":"Compatibility with dplyr","text":"safeframe modify anything regarding behaviour row-operations. , fully compatible dplyr verbs operating rows ---box. can see following examples safeframe produce errors, warnings messspeeds labels conserved dplyr operations rows.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrarrange","dir":"Articles","previous_headings":"Verbs operating on rows","what":"dplyr::arrange() ✅","title":"Compatibility with dplyr","text":"","code":"x %>% arrange(speed) %>% head() #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrdistinct","dir":"Articles","previous_headings":"Verbs operating on rows","what":"dplyr:distinct() ✅","title":"Compatibility with dplyr","text":"","code":"x %>% distinct() %>% head() #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrfilter","dir":"Articles","previous_headings":"Verbs operating on rows","what":"dplyr::filter() ✅","title":"Compatibility with dplyr","text":"","code":"x %>% filter(speed >= 50) %>% head() #> #> // safeframe object #> [1] speed dist #> <0 rows> (or 0-length row.names) #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrslice","dir":"Articles","previous_headings":"Verbs operating on rows","what":"dplyr::slice() ✅","title":"Compatibility with dplyr","text":"","code":"x %>% slice(5:10) #> #> // safeframe object #> speed dist #> 1 8 16 #> 2 9 10 #> 3 10 18 #> 4 10 26 #> 5 10 34 #> 6 11 17 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles x %>% slice_head(n = 5) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles x %>% slice_tail(n = 5) #> #> // safeframe object #> speed dist #> 1 24 70 #> 2 24 92 #> 3 24 93 #> 4 24 120 #> 5 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles x %>% slice_min(speed, n = 3) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles x %>% slice_max(speed, n = 3) #> #> // safeframe object #> speed dist #> 1 25 85 #> 2 24 70 #> 3 24 92 #> 4 24 93 #> 5 24 120 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles x %>% slice_sample(n = 5) #> #> // safeframe object #> speed dist #> 1 23 54 #> 2 14 80 #> 3 12 14 #> 4 19 46 #> 5 19 68 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"verbs-operating-on-columns","dir":"Articles","previous_headings":"","what":"Verbs operating on columns","title":"Compatibility with dplyr","text":"operations columns, safeframe : stay invisible conserve labels labelled column affected operation trigger lost_labels_action() labelled columns affected operation","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrmutate-partial","dir":"Articles","previous_headings":"Verbs operating on columns","what":"dplyr::mutate() ✓ (partial)","title":"Compatibility with dplyr","text":"incomplete compatibility dplyr::mutate() simple renames without actual modification column don’t update labels. scenario, users rather use dplyr::rename() Although dplyr::mutate() able leverspeed full power safeframe labels, safeframe objects behave expected way data.frame :","code":"# In place modification doesn't lose labels x %>% mutate(speed = speed + 10) %>% head() #> #> // safeframe object #> speed dist #> 1 14 2 #> 2 14 10 #> 3 17 4 #> 4 17 22 #> 5 18 16 #> 6 19 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles # New columns don't affect existing labels x %>% mutate(ticket = speed >= 50) %>% head() #> #> // safeframe object #> speed dist ticket #> 1 4 2 FALSE #> 2 4 10 FALSE #> 3 7 4 FALSE #> 4 7 22 FALSE #> 5 8 16 FALSE #> 6 9 10 FALSE #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles # .keep = \"unused\" generate expected tag loss conditions x %>% mutate(edad = speed, .keep = \"unused\") %>% head() #> Warning: The following labelled variables are lost: #> speed - Miles per hour #> #> // safeframe object #> dist edad #> 1 2 4 #> 2 10 4 #> 3 4 7 #> 4 22 7 #> 5 16 8 #> 6 10 9 #> #> labelled variables: #> dist - Distance in miles #> edad - Miles per hour"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrpull","dir":"Articles","previous_headings":"Verbs operating on columns","what":"dplyr::pull() ✅","title":"Compatibility with dplyr","text":"dplyr::pull() returns vector, results, expected, loss safeframe class labels:","code":"x %>% pull(speed) #> [1] 4 4 7 7 8 9 10 10 10 11 11 12 12 12 12 13 13 13 13 14 14 14 14 15 15 #> [26] 15 16 16 17 17 17 18 18 18 18 19 19 19 20 20 20 20 20 22 23 24 24 24 24 25 #> attr(,\"label\") #> [1] \"Miles per hour\""},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrrelocate","dir":"Articles","previous_headings":"Verbs operating on columns","what":"dplyr::relocate() ✅","title":"Compatibility with dplyr","text":"","code":"x %>% relocate(speed, .before = 1) %>% head() #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrrename-dplyrrename_with","dir":"Articles","previous_headings":"Verbs operating on columns","what":"dplyr::rename() & dplyr::rename_with() ✅","title":"Compatibility with dplyr","text":"dplyr::rename() fully compatible ---box safeframe, meaning labels updated time columns renamed. possibly uses names<-() hood, safeframe provides custom names<-.safeframe() method :","code":"x %>% rename(edad = speed) %>% head() #> #> // safeframe object #> edad dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> edad - Miles per hour #> dist - Distance in miles x %>% rename_with(toupper) %>% head() #> #> // safeframe object #> SPEED DIST #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> SPEED - Miles per hour #> DIST - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrselect","dir":"Articles","previous_headings":"Verbs operating on columns","what":"dplyr::select() ✅","title":"Compatibility with dplyr","text":"dplyr::select() fully compatible safeframe, including columns renamed select():","code":"# Works fine x %>% select(speed, dist) %>% head() #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles # labels are updated! x %>% select(dist, edad = speed) %>% head() #> #> // safeframe object #> dist edad #> 1 2 4 #> 2 10 4 #> 3 4 7 #> 4 22 7 #> 5 16 8 #> 6 10 9 #> #> labelled variables: #> dist - Distance in miles #> edad - Miles per hour"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"verbs-operating-on-groups","dir":"Articles","previous_headings":"","what":"Verbs operating on groups ✘","title":"Compatibility with dplyr","text":"Groups yet supported. Applying verb operating group safeframe silently convert back data.frame tibble.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrbind_rows","dir":"Articles","previous_headings":"Verbs operating on data.frames","what":"dplyr::bind_rows() ✅","title":"Compatibility with dplyr","text":"","code":"dim(x) #> [1] 50 2 dim(bind_rows(x, x)) #> [1] 100 2"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrbind_cols","dir":"Articles","previous_headings":"Verbs operating on data.frames","what":"dplyr::bind_cols() ✘","title":"Compatibility with dplyr","text":"bind_cols() currently incompatible safeframe: labels second element lost Warnings produced lost labels, even labels actually lost","code":"bind_cols( suppressWarnings(select(x, speed)), suppressWarnings(select(x, dist)) ) %>% head() #> Warning: The following labelled variables are lost: #> speed - Miles per hour #> Warning: The following labelled variables are lost: #> dist - Distance in miles #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"joins","dir":"Articles","previous_headings":"Verbs operating on data.frames","what":"Joins ✘","title":"Compatibility with dplyr","text":"Joins currently compatible safeframe labels second element silently dropped.","code":"full_join( suppressWarnings(select(x, speed, dist)), suppressWarnings(select(x, dist, speed)) ) %>% head() #> Joining with `by = join_by(speed, dist)` #> Warning in full_join(suppressWarnings(select(x, speed, dist)), suppressWarnings(select(x, : Detected an unexpected many-to-many relationship between `x` and `y`. #> ℹ Row 17 of `x` matches multiple rows in `y`. #> ℹ Row 17 of `y` matches multiple rows in `x`. #> ℹ If a many-to-many relationship is expected, set `relationship = #> \"many-to-many\"` to silence this warning. #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrpick","dir":"Articles","previous_headings":"Verbs operating on multiple columns","what":"dplyr::pick() ✘","title":"Compatibility with dplyr","text":"pick() makes tidyselect functions work usually tidyselect-incompatible functions, : , expect work safeframe custom tidyselect-like function: has_label() ’s case since pick() currently strips attributes, including safeframe class labels. unclassing documented ?pick: pick() returns data frame containing selected columns current group.","code":"x %>% dplyr::arrange(dplyr::pick(ends_with(\"loc\"))) %>% head() #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/design-principles.html","id":"scope","dir":"Articles","previous_headings":"","what":"Scope","title":"Design Principles for {safeframe}","text":"safeframe provides generic labelling validation tools. contrast original versions linelist (<=v1.1.4), safeframe functions variable level instead object level. validation tooling specific type checking variables providing feedback potential data loss coercion. aim complex validations time.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/design-principles.html","id":"naming-conventions","dir":"Articles","previous_headings":"","what":"Naming conventions","title":"Design Principles for {safeframe}","text":"separate functions much reasonable files R/. tests available file R/, follows convention test-.R tests/testthat/. source code respective tests. try make function names descriptive possible, keeping short. make package easy use understand.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/design-principles.html","id":"inputoutputinteroperability","dir":"Articles","previous_headings":"","what":"Input/Output/Interoperability","title":"Design Principles for {safeframe}","text":"data frame object can passed safeframe. Output safeframe remains data frame object, additional safeframe class attribute. means remains interoperable regular data frame operations one may attempt . safeframe interoperable pipes (, |> %>%). allows easy chaining functions. Note guarantees label attributes preserved piping wrangling another way. example, dplyr drops variable level attributes using dplyr::mutate().","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/design-principles.html","id":"design-decisions","dir":"Articles","previous_headings":"","what":"Design decisions","title":"Design Principles for {safeframe}","text":"Generic: package designed generic tool labelling validating data. ensure package can used wide range contexts limited specific use case. specific use cases implemented separate packages. Local: keep functions local possible. means operations precise feasible, non-destructive ensure changes one variable unexpectedly affect another. helps ensure package predictable easy use + maintain. Minimize number functions: aim keep number functions package minimum. helps usability maintainability. Base R: aim use base R functions possible. ensure package lightweight many dependencies. example use labelled labelling package. feel like uphold one design decisions, please let us know 😊","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/design-principles.html","id":"quirks","dir":"Articles","previous_headings":"Design decisions","what":"Quirks","title":"Design Principles for {safeframe}","text":"package development quirks. outline quirks aware : Currently, emptying labels leads setting \"\" (empty character strings). Preferably end setting NULL end.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/design-principles.html","id":"dependencies","dir":"Articles","previous_headings":"","what":"Dependencies","title":"Design Principles for {safeframe}","text":"checkmate - provide assertions function arguments lifecycle - help manage function lifecycle rlang - ... list parsing tidyselect - ensure can use pipes has_label()","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/design-principles.html","id":"development-journey","dir":"Articles","previous_headings":"","what":"Development journey","title":"Design Principles for {safeframe}","text":"safeframe package major refactor linelist v1.1.4. refactor necessary make package generic make codebase maintainable. refactor completed series steps documented #37.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Chris Hartgerink. Maintainer, author. Hugo Gruson. Reviewer.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Hartgerink C (2024). safeframe: Generic Data Labelling Validating. R package version 0.0.1, https://github.com/epiverse-trace/safeframe, https://epiverse-trace.github.io/safeframe/.","code":"@Manual{, title = {safeframe: Generic Data Labelling and Validating}, author = {Chris Hartgerink}, year = {2024}, note = {R package version 0.0.1, https://github.com/epiverse-trace/safeframe}, url = {https://epiverse-trace.github.io/safeframe/}, }"},{"path":"https://epiverse-trace.github.io/safeframe/index.html","id":"safeframe-generic-data-labelling-and-validating-","dir":"","previous_headings":"","what":"Generic Data Labelling and Validating","title":"Generic Data Labelling and Validating","text":"safeframe provides functions label validate data kind. safeframe abstraction linelist, applies principles epidemiological linelist data. original proposal package can found Discussion board.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Generic Data Labelling and Validating","text":"can install development version safeframe GitHub :","code":"# install.packages(\"pak\") pak::pak(\"epiverse-trace/safeframe\")"},{"path":"https://epiverse-trace.github.io/safeframe/index.html","id":"getting-started","dir":"","previous_headings":"","what":"Getting started","title":"Generic Data Labelling and Validating","text":"","code":"library(safeframe) # Create a safeframe object x <- make_safeframe(cars, speed = 'Miles per hour', dist = 'Distance in miles') # Validate the data are of a specific type validate_safeframe(x, speed = 'numeric', # speed should be numeric # type() is a helper function of related classes dist = type('numeric') # dist should be numeric, integer )"},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/index.html","id":"lifecycle","dir":"","previous_headings":"Development","what":"Lifecycle","title":"Generic Data Labelling and Validating","text":"package currently experimental, defined RECON software lifecycle. means essential features mechanisms still developed, package ready use outside development team.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/index.html","id":"contributions","dir":"","previous_headings":"Development","what":"Contributions","title":"Generic Data Labelling and Validating","text":"Contributions welcome via pull requests. Anything bigger typo fix small documentation update discussed issue first. want report bug suggest enhancement, please open issue. 😊 See also general Epiverse TRACE contribution document. make easier us evaluate contribution, please run following commands submitting pull request ensure code consistent rest package: reduce time takes us review contribution. Thank ! 😊","code":"styler::style_pkg() devtools::document() spelling::update_wordlist(pkg = \".\", vignettes = TRUE) lintr::lint_package() devtools::test() devtools::check()"},{"path":"https://epiverse-trace.github.io/safeframe/index.html","id":"related-projects","dir":"","previous_headings":"Development","what":"Related projects","title":"Generic Data Labelling and Validating","text":"project related existing projects R languages, also differs following aspects: labelled: package labelling data R, focused labelling variables validating . linelist: package managing validating linelist data - original inspiration safeframe.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/index.html","id":"code-of-conduct","dir":"","previous_headings":"Development","what":"Code of Conduct","title":"Generic Data Labelling and Validating","text":"Please note safeframe project released Contributor Code Conduct. contributing project, agree abide terms.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/has_label.html","id":null,"dir":"Reference","previous_headings":"","what":"A selector function to use in tidyverse functions — has_label","title":"A selector function to use in tidyverse functions — has_label","text":"selector function use tidyverse functions","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/has_label.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"A selector function to use in tidyverse functions — has_label","text":"","code":"has_label(labels)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/has_label.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"A selector function to use in tidyverse functions — has_label","text":"labels character vector labels want operate ","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/has_label.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"A selector function to use in tidyverse functions — has_label","text":"numeric vector containing position columns requested labels","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/has_label.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"A selector function to use in tidyverse functions — has_label","text":"Using pipeline results 'safeframe' object, maintain variable labels time. primarily useful make pipelines human readable.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/has_label.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"A selector function to use in tidyverse functions — has_label","text":"","code":"## create safeframe x <- make_safeframe(cars, speed = \"Miles per hour\", dist = \"Distance in miles\" ) head(x) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles if (require(dplyr) && require(magrittr)) { x %>% select(has_label(c(\"Miles per hour\", \"Distance in miles\"))) %>% head() } #> Loading required package: dplyr #> #> Attaching package: ‘dplyr’ #> The following objects are masked from ‘package:stats’: #> #> filter, lag #> The following objects are masked from ‘package:base’: #> #> intersect, setdiff, setequal, union #> Loading required package: magrittr #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Get the list of labels in a safeframe — labels","title":"Get the list of labels in a safeframe — labels","text":"function returns list labels identifying specific variable types safeframe object.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Get the list of labels in a safeframe — labels","text":"","code":"labels(x, show_null = FALSE)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Get the list of labels in a safeframe — labels","text":"x safeframe object show_null logical indicating complete list labels, including NULL ones, returned; FALSE, labels non-NULL value returned; defaults FALSE","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Get the list of labels in a safeframe — labels","text":"function returns named list names indicate column correspond , values indicate relevant labels.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Get the list of labels in a safeframe — labels","text":"Labels stored label attribute column variable.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Get the list of labels in a safeframe — labels","text":"","code":"## make a safeframe x <- make_safeframe(cars, speed = \"Miles per hour\") ## check non-null labels labels(x) #> $speed #> [1] \"Miles per hour\" #> ## get a list of all labels, including NULL ones labels(x, TRUE) #> $speed #> [1] \"Miles per hour\" #> #> $dist #> NULL #>"},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels_df.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract a data.frame of all labelled variables — labels_df","title":"Extract a data.frame of all labelled variables — labels_df","text":"function returns data.frame, labelled variables (stored safeframe object) renamed. Note output longer safeframe, regular data.frame. Unlabeled variables unaffected.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels_df.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract a data.frame of all labelled variables — labels_df","text":"","code":"labels_df(x)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels_df.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract a data.frame of all labelled variables — labels_df","text":"x safeframe object","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels_df.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract a data.frame of all labelled variables — labels_df","text":"data.frame variables renamed according labels.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels_df.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract a data.frame of all labelled variables — labels_df","text":"","code":"x <- make_safeframe(cars, speed = \"Miles per hour\", dist = \"Distance in miles\" ) ## get a data.frame with variables renamed based on labels labels_df(x) #> Miles per hour Distance in miles #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85"},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Check for lost labels and throw relevant warning or error — lost_labels","title":"Check for lost labels and throw relevant warning or error — lost_labels","text":"internal function checks labels present old labels new labels. labels lost, throws warning error based specified action.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Check for lost labels and throw relevant warning or error — lost_labels","text":"","code":"lost_labels(old, new, lost_action)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Check for lost labels and throw relevant warning or error — lost_labels","text":"old named list old labels. new named list new labels. lost_action character string specifying action take labels lost. Can \"none\", \"warning\", \"error\".","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Check for lost labels and throw relevant warning or error — lost_labels","text":"None. Throws warning error labels lost.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels_action.html","id":null,"dir":"Reference","previous_headings":"","what":"Check and set behaviour for lost labels — lost_labels_action","title":"Check and set behaviour for lost labels — lost_labels_action","text":"function determines behaviour adopt labelled variables safeframe lost example subsetting. achieved using options defined safeframe package.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels_action.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Check and set behaviour for lost labels — lost_labels_action","text":"","code":"lost_labels_action(action = c(\"warning\", \"error\", \"none\"), quiet = FALSE) get_lost_labels_action()"},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels_action.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Check and set behaviour for lost labels — lost_labels_action","text":"action character indicating behaviour adopt labelled variables lost: \"error\" (default) issue error; \"warning\" issue warning; \"none\" nothing quiet logical indicating message displayed; used outside pipelines","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels_action.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Check and set behaviour for lost labels — lost_labels_action","text":"returns NULL; option set options(\"safeframe\")","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels_action.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Check and set behaviour for lost labels — lost_labels_action","text":"errors warnings generated safeframe case labelled variable loss custom class safeframe_error safeframe_warning respectively.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels_action.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Check and set behaviour for lost labels — lost_labels_action","text":"","code":"# reset default - done automatically at package loading lost_labels_action() #> Lost labels will now issue a warning. # check current value get_lost_labels_action() #> [1] \"warning\" # change to issue errors when tags are lost lost_labels_action(\"error\") #> Lost labels will now issue an error. get_lost_labels_action() #> [1] \"error\" # change to ignore when tags are lost lost_labels_action(\"none\") #> Lost labels will now be ignored. get_lost_labels_action() #> [1] \"none\" # reset to default: warning lost_labels_action() #> Lost labels will now issue a warning."},{"path":"https://epiverse-trace.github.io/safeframe/reference/make_safeframe.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a safeframe from a data.frame — make_safeframe","title":"Create a safeframe from a data.frame — make_safeframe","text":"function converts data.frame tibble safeframe object, data labelled validated. output seem data.frame, safeframe-aware packages able automatically use labelled fields data cleaning analysis.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/make_safeframe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a safeframe from a data.frame — make_safeframe","text":"","code":"make_safeframe(x, ...)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/make_safeframe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a safeframe from a data.frame — make_safeframe","text":"x data.frame tibble ... named list variable names x list names labels list values. Values set NULL remove label. specifying labels, please also see default_values.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/make_safeframe.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create a safeframe from a data.frame — make_safeframe","text":"function returns safeframe object.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/reference/make_safeframe.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create a safeframe from a data.frame — make_safeframe","text":"","code":"x <- make_safeframe(cars, speed = \"Miles per hour\", dist = \"Distance in miles\" ) ## print result - just first few entries head(x) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles ## check labels labels(x) #> $speed #> [1] \"Miles per hour\" #> #> $dist #> [1] \"Distance in miles\" #> ## Labels can also be passed as a list with the splice operator (!!!) my_labels <- list( speed = \"Miles per hour\", dist = \"Distance in miles\" ) new_x <- make_safeframe(cars, !!!my_labels) ## The output is strictly equivalent to the previous one identical(x, new_x) #> [1] TRUE"},{"path":"https://epiverse-trace.github.io/safeframe/reference/names-set-.safeframe.html","id":null,"dir":"Reference","previous_headings":"","what":"Rename columns of a safeframe — names<-.safeframe","title":"Rename columns of a safeframe — names<-.safeframe","text":"function can used rename columns safeframe (, adjust variable names).","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/names-set-.safeframe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Rename columns of a safeframe — names<-.safeframe","text":"","code":"# S3 method for class 'safeframe' names(x) <- value"},{"path":"https://epiverse-trace.github.io/safeframe/reference/names-set-.safeframe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Rename columns of a safeframe — names<-.safeframe","text":"x safeframe object value character vector set new names columns x","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/names-set-.safeframe.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Rename columns of a safeframe — names<-.safeframe","text":"safeframe new column names","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/names-set-.safeframe.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Rename columns of a safeframe — names<-.safeframe","text":"","code":"## create safeframe x <- make_safeframe(cars, speed = \"Miles per hour\", dist = \"Distance in miles\" ) head(x) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles ## change names names(x)[1] <- \"mph\" ## see results: columns have been updated head(x) #> #> // safeframe object #> mph dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> mph - Miles per hour #> dist - Distance in miles # This also works with using `dplyr::rename()` because it uses names<-() # under the hood if (require(dplyr) && require(magrittr)) { x <- x %>% rename(speed = \"mph\") head(x) labels(x) } #> $speed #> [1] \"Miles per hour\" #> #> $dist #> [1] \"Distance in miles\" #>"},{"path":"https://epiverse-trace.github.io/safeframe/reference/print.safeframe.html","id":null,"dir":"Reference","previous_headings":"","what":"Printing method for safeframe objects — print.safeframe","title":"Printing method for safeframe objects — print.safeframe","text":"function prints safeframe objects.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/print.safeframe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Printing method for safeframe objects — print.safeframe","text":"","code":"# S3 method for class 'safeframe' print(x, ...)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/print.safeframe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Printing method for safeframe objects — print.safeframe","text":"x safeframe object ... arguments passed 'print'","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/print.safeframe.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Printing method for safeframe objects — print.safeframe","text":"Invisibly returns object.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/print.safeframe.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Printing method for safeframe objects — print.safeframe","text":"","code":"## create safeframe x <- make_safeframe(cars, speed = \"Miles per hour\", dist = \"Distance in miles\" ) ## print object - using only the first few entries head(x) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles # version with a tibble if (require(tibble) && require(magrittr)) { cars %>% tibble() %>% make_safeframe( speed = \"Miles per hour\", dist = \"Distance in miles\" ) } #> Loading required package: tibble #> #> // safeframe object #> # A tibble: 50 × 2 #> speed dist #> #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> # ℹ 40 more rows #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/reference/safeframe-package.html","id":null,"dir":"Reference","previous_headings":"","what":"Base Tools for Labelling and Validating Data — safeframe-package","title":"Base Tools for Labelling and Validating Data — safeframe-package","text":"safeframe package provides tools help label validate data. 'safeframe' class adds column level attributes 'data.frame'. labelled, variables can seamlessly used downstream analyses, making data pipelines robust reliable.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/safeframe-package.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Base Tools for Labelling and Validating Data — safeframe-package","text":"package aim complete integration dplyr functions. example, dplyr::mutate() dplyr::bind_rows() preserve labels. provide compatibility dplyr::rename().","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/safeframe-package.html","id":"main-functions","dir":"Reference","previous_headings":"","what":"Main functions","title":"Base Tools for Labelling and Validating Data — safeframe-package","text":"make_safeframe(): create safeframe objects data.frame tibble set_labels(): change add labelled variables safeframe labels(): get list labels safeframe labels_df(): get data.frame tagged variables lost_labels_action(): change behaviour actions labelled variables lost (e.g removing columns storing labelled variables) issue warnings, errors, nothing get_lost_labels_action(): check current behaviour actions labelled variables lost","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/safeframe-package.html","id":"dedicated-methods","dir":"Reference","previous_headings":"","what":"Dedicated methods","title":"Base Tools for Labelling and Validating Data — safeframe-package","text":"Specific methods commonly used handle data.frame provided safeframe objects, typically help flag prevent actions alter lose labelled variables (may thus break downstream data pipelines). names() <- (related functions, dplyr::rename()) rename labels needed x[...] <- x[[...]] <- (see sub_safeframe): adopt desired behaviour labelled variables lost print(): prints info safeframe addition data.frame tibble","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/reference/safeframe-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Base Tools for Labelling and Validating Data — safeframe-package","text":"Maintainer: Chris Hartgerink chris@data.org (ORCID) contributors: Hugo Gruson hugo@data.org (ORCID) [reviewer]","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/safeframe-package.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Base Tools for Labelling and Validating Data — safeframe-package","text":"","code":"# using base R style x <- make_safeframe(cars[1:50, ], speed = \"Miles per hour\", dist = \"Distance in miles\" ) x #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles ## check labelled variables labels(x) #> $speed #> [1] \"Miles per hour\" #> #> $dist #> [1] \"Distance in miles\" #> ## robust renaming names(x)[1] <- \"identifier\" x #> #> // safeframe object #> identifier dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> identifier - Miles per hour #> dist - Distance in miles ## example of dropping labels by mistake - default: warning x[, 2] #> Warning: The following labelled variables are lost: #> identifier - Miles per hour #> #> // safeframe object #> dist #> 1 2 #> 2 10 #> 3 4 #> 4 22 #> 5 16 #> 6 10 #> 7 18 #> 8 26 #> 9 34 #> 10 17 #> 11 28 #> 12 14 #> 13 20 #> 14 24 #> 15 28 #> 16 26 #> 17 34 #> 18 34 #> 19 46 #> 20 26 #> 21 36 #> 22 60 #> 23 80 #> 24 20 #> 25 26 #> 26 54 #> 27 32 #> 28 40 #> 29 32 #> 30 40 #> 31 50 #> 32 42 #> 33 56 #> 34 76 #> 35 84 #> 36 36 #> 37 46 #> 38 68 #> 39 32 #> 40 48 #> 41 52 #> 42 56 #> 43 64 #> 44 66 #> 45 54 #> 46 70 #> 47 92 #> 48 93 #> 49 120 #> 50 85 #> #> labelled variables: #> dist - Distance in miles ## to silence warnings when labels are dropped lost_labels_action(\"none\") #> Lost labels will now be ignored. x[, 2] #> #> // safeframe object #> dist #> 1 2 #> 2 10 #> 3 4 #> 4 22 #> 5 16 #> 6 10 #> 7 18 #> 8 26 #> 9 34 #> 10 17 #> 11 28 #> 12 14 #> 13 20 #> 14 24 #> 15 28 #> 16 26 #> 17 34 #> 18 34 #> 19 46 #> 20 26 #> 21 36 #> 22 60 #> 23 80 #> 24 20 #> 25 26 #> 26 54 #> 27 32 #> 28 40 #> 29 32 #> 30 40 #> 31 50 #> 32 42 #> 33 56 #> 34 76 #> 35 84 #> 36 36 #> 37 46 #> 38 68 #> 39 32 #> 40 48 #> 41 52 #> 42 56 #> 43 64 #> 44 66 #> 45 54 #> 46 70 #> 47 92 #> 48 93 #> 49 120 #> 50 85 #> #> labelled variables: #> dist - Distance in miles ## to trigger errors when labels are dropped # lost_labels_action(\"error\") # x[, 2:5] ## reset default behaviour lost_labels_action() #> Lost labels will now issue a warning. # using tidyverse style ## example of creating a safeframe, adding a new variable, and adding a label ## for it if (require(dplyr) && require(magrittr)) { x <- cars %>% tibble() %>% make_safeframe( speed = \"Miles per hour\", dist = \"Distance in miles\" ) %>% mutate(result = if_else(speed > 50, \"fast\", \"slow\")) %>% set_labels(result = \"Ticket yes/no\") head(x) ## extract labelled variables x %>% select(has_label(c(\"Ticket yes/no\"))) ## Retrieve all labels x %>% labels() ## Select based on variable name x %>% select(starts_with(\"speed\")) } #> Warning: The following labelled variables are lost: #> speed - Miles per hour #> dist - Distance in miles #> Warning: The following labelled variables are lost: #> dist - Distance in miles #> result - Ticket yes/no #> #> // safeframe object #> # A tibble: 50 × 1 #> speed #> #> 1 4 #> 2 4 #> 3 7 #> 4 7 #> 5 8 #> 6 9 #> 7 10 #> 8 10 #> 9 10 #> 10 11 #> # ℹ 40 more rows #> #> labelled variables: #> speed - Miles per hour"},{"path":"https://epiverse-trace.github.io/safeframe/reference/set_labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Change labels of a safeframe object — set_labels","title":"Change labels of a safeframe object — set_labels","text":"function changes labels safeframe object, using syntax constructor make_safeframe().","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/set_labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Change labels of a safeframe object — set_labels","text":"","code":"set_labels(x, ...)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/set_labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Change labels of a safeframe object — set_labels","text":"x data.frame tibble ... named list variable names x list names labels list values. Values set NULL remove label. specifying labels, please also see default_values.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/set_labels.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Change labels of a safeframe object — set_labels","text":"function returns safeframe object.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/reference/set_labels.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Change labels of a safeframe object — set_labels","text":"","code":"## create a safeframe x <- make_safeframe(cars, speed = \"Miles per hour\") labels(x) #> $speed #> [1] \"Miles per hour\" #> ## add new labels and fix an existing one x <- set_labels(x, dist = \"Distance\") labels(x) #> $speed #> [1] \"Miles per hour\" #> #> $dist #> [1] \"Distance\" #> ## remove labels by setting them to NULL old_labels <- labels(x) x <- set_labels(x, speed = NULL, dist = NULL) labels(x) #> $speed #> [1] \"\" #> #> $dist #> [1] \"\" #> ## setting labels providing a list (used to restore old labels here) x <- set_labels(x, !!!old_labels) labels(x) #> $speed #> [1] \"Miles per hour\" #> #> $dist #> [1] \"Distance\" #>"},{"path":"https://epiverse-trace.github.io/safeframe/reference/sub_safeframe.html","id":null,"dir":"Reference","previous_headings":"","what":"Subsetting of safeframe objects — [.safeframe","title":"Subsetting of safeframe objects — [.safeframe","text":"[] [[]] operators safeframe objects behaves like regular data.frame tibble, check labelled variables lost, takes appropriate action case (warning, error, ignore, depending general option set via lost_labels_action()) .","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/sub_safeframe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Subsetting of safeframe objects — [.safeframe","text":"","code":"# S3 method for class 'safeframe' x[i, j, drop = FALSE] # S3 method for class 'safeframe' x[i, j] <- value # S3 method for class 'safeframe' x[[i, j]] <- value # S3 method for class 'safeframe' x$name <- value"},{"path":"https://epiverse-trace.github.io/safeframe/reference/sub_safeframe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Subsetting of safeframe objects — [.safeframe","text":"x safeframe object vector integer logical subset rows safeframe j vector character, integer, logical subset columns safeframe drop logical indicating , single column selected, data.frame class dropped return simple vector, case safeframe class lost well; defaults FALSE value replacement used entries identified x name literal character string name (possibly backtick quoted). extraction, normally (see ‘Environments’) partially matched names object.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/sub_safeframe.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Subsetting of safeframe objects — [.safeframe","text":"drop happening, safeframe. Otherwise atomic vector.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/reference/sub_safeframe.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Subsetting of safeframe objects — [.safeframe","text":"","code":"if (require(dplyr) && require(magrittr)) { ## create a safeframe x <- cars %>% make_safeframe( speed = \"Miles per hour\", dist = \"Distance in miles\" ) %>% mutate(result = if_else(speed > 50, \"fast\", \"slow\")) %>% set_labels(result = \"Ticket\") x ## dangerous removal of a labelled column setting it to NULL issues warning x[, 1] <- NULL x x[[2]] <- NULL x x$age <- NULL x } #> Warning: The following labelled variables are lost: #> speed - Miles per hour #> Warning: The following labelled variables are lost: #> result - Ticket #> #> // safeframe object #> dist #> 1 2 #> 2 10 #> 3 4 #> 4 22 #> 5 16 #> 6 10 #> 7 18 #> 8 26 #> 9 34 #> 10 17 #> 11 28 #> 12 14 #> 13 20 #> 14 24 #> 15 28 #> 16 26 #> 17 34 #> 18 34 #> 19 46 #> 20 26 #> 21 36 #> 22 60 #> 23 80 #> 24 20 #> 25 26 #> 26 54 #> 27 32 #> 28 40 #> 29 32 #> 30 40 #> 31 50 #> 32 42 #> 33 56 #> 34 76 #> 35 84 #> 36 36 #> 37 46 #> 38 68 #> 39 32 #> 40 48 #> 41 52 #> 42 56 #> 43 64 #> 44 66 #> 45 54 #> 46 70 #> 47 92 #> 48 93 #> 49 120 #> 50 85 #> #> labelled variables: #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/reference/type.html","id":null,"dir":"Reference","previous_headings":"","what":"Type Selection Helper — type","title":"Type Selection Helper — type","text":"Function swiftly provide access generic categories types within R. can used provide comprehensive typesetting creating safeframe object.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/type.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Type Selection Helper — type","text":"","code":"type(x)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/type.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Type Selection Helper — type","text":"x Character indicating desired type. Options include date, category, numeric, binary time.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/type.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Type Selection Helper — type","text":"vector classes","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/type.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Type Selection Helper — type","text":"","code":"x <- make_safeframe(cars, speed = \"Miles per hour\", dist = \"Distance in miles\" ) validate_types( x, speed = type(\"numeric\"), dist = \"numeric\" ) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Checks the labels of a safeframe object — validate_labels","title":"Checks the labels of a safeframe object — validate_labels","text":"function evaluates validity labels safeframe object checking : ) labels present ii) labels list character NULL values.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Checks the labels of a safeframe object — validate_labels","text":"","code":"validate_labels(x)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Checks the labels of a safeframe object — validate_labels","text":"x safeframe object","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_labels.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Checks the labels of a safeframe object — validate_labels","text":"checks pass, safeframe object; otherwise issues error.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_labels.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Checks the labels of a safeframe object — validate_labels","text":"","code":"## create a valid safeframe x <- cars |> make_safeframe( speed = \"Miles per hour\", dist = \"Distance in miles\" ) x #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles ## the below issues an error as safeframe doesn't know any defaults ## note: tryCatch is only used to avoid a genuine error in the example tryCatch(validate_safeframe(x), error = paste) #> [1] \"Error in validate_types(x, ...): Assertion on 'types' failed: Must have length >= 1, but has length 0.\\n\" ## validation requires you to specify the types directly validate_safeframe(x, speed = c(\"integer\", \"numeric\"), dist = \"numeric\" ) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_safeframe.html","id":null,"dir":"Reference","previous_headings":"","what":"Checks the content of a safeframe object — validate_safeframe","title":"Checks the content of a safeframe object — validate_safeframe","text":"function evaluates validity safeframe object checking object class, labels, types variables. combines validation checks made validate_types() validate_labels(). See 'Details' section information checks performed.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_safeframe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Checks the content of a safeframe object — validate_safeframe","text":"","code":"validate_safeframe(x, ...)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_safeframe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Checks the content of a safeframe object — validate_safeframe","text":"x safeframe object ... named list variable names x list names related types list values.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_safeframe.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Checks the content of a safeframe object — validate_safeframe","text":"checks pass, safeframe object; otherwise issues error.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_safeframe.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Checks the content of a safeframe object — validate_safeframe","text":"following checks performed: x safeframe object variables x well-formed label attribute variables correspond specified types","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_safeframe.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Checks the content of a safeframe object — validate_safeframe","text":"","code":"## create a valid safeframe x <- cars |> make_safeframe( speed = \"Miles per hour\", dist = \"Distance in miles\" ) x #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles ## validation validate_safeframe(x, speed = c(\"numeric\", \"factor\"), dist = \"numeric\" ) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles ## the below issues an error ## note: tryCatch is only used to avoid a genuine error in the example tryCatch(validate_safeframe(x, speed = c(\"numeric\", \"factor\"), dist = \"factor\" ), error = paste) #> [1] \"Error: Some labels have the wrong class:\\n - dist: Must inherit from class 'factor', but has class 'numeric'\\n\\n\""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_types.html","id":null,"dir":"Reference","previous_headings":"","what":"Type check variables — validate_types","title":"Type check variables — validate_types","text":"function checks type variables safeframe accepted classes. checks type provided variables ignores provided.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_types.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Type check variables — validate_types","text":"","code":"validate_types(x, ...)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_types.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Type check variables — validate_types","text":"x safeframe object ... named list variable names x list names related types list values.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_types.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Type check variables — validate_types","text":"named list.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_types.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Type check variables — validate_types","text":"","code":"x <- make_safeframe(cars, speed = \"Miles per hour\", dist = \"Distance in miles\" ) x #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles ## the below would issue an error ## note: tryCatch is only used to avoid a genuine error in the example tryCatch(validate_types(x), error = paste) #> [1] \"Error in validate_types(x): Assertion on 'types' failed: Must have length >= 1, but has length 0.\\n\" ## to allow other types, e.g. gender to be integer, character or factor validate_types(x, speed = \"numeric\", dist = c( \"integer\", \"character\", \"numeric\" )) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/reference/vars_labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Internal printing function for variables and labels — vars_labels","title":"Internal printing function for variables and labels — vars_labels","text":"Internal printing function variables labels","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/vars_labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Internal printing function for variables and labels — vars_labels","text":"","code":"vars_labels(vars, labels)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/vars_labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Internal printing function for variables and labels — vars_labels","text":"vars character vector variable names labels character vector labels","code":""}] +[{"path":"https://epiverse-trace.github.io/safeframe/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"MIT License","title":"MIT License","text":"Copyright (c) 2022 package authors Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"verbs-operating-on-rows","dir":"Articles","previous_headings":"","what":"Verbs operating on rows","title":"Compatibility with dplyr","text":"safeframe modify anything regarding behaviour row-operations. , fully compatible dplyr verbs operating rows ---box. can see following examples safeframe produce errors, warnings messspeeds labels conserved dplyr operations rows.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrarrange","dir":"Articles","previous_headings":"Verbs operating on rows","what":"dplyr::arrange() ✅","title":"Compatibility with dplyr","text":"","code":"x %>% arrange(speed) %>% head() #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrdistinct","dir":"Articles","previous_headings":"Verbs operating on rows","what":"dplyr:distinct() ✅","title":"Compatibility with dplyr","text":"","code":"x %>% distinct() %>% head() #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrfilter","dir":"Articles","previous_headings":"Verbs operating on rows","what":"dplyr::filter() ✅","title":"Compatibility with dplyr","text":"","code":"x %>% filter(speed >= 50) %>% head() #> #> // safeframe object #> [1] speed dist #> <0 rows> (or 0-length row.names) #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrslice","dir":"Articles","previous_headings":"Verbs operating on rows","what":"dplyr::slice() ✅","title":"Compatibility with dplyr","text":"","code":"x %>% slice(5:10) #> #> // safeframe object #> speed dist #> 1 8 16 #> 2 9 10 #> 3 10 18 #> 4 10 26 #> 5 10 34 #> 6 11 17 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles x %>% slice_head(n = 5) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles x %>% slice_tail(n = 5) #> #> // safeframe object #> speed dist #> 1 24 70 #> 2 24 92 #> 3 24 93 #> 4 24 120 #> 5 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles x %>% slice_min(speed, n = 3) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles x %>% slice_max(speed, n = 3) #> #> // safeframe object #> speed dist #> 1 25 85 #> 2 24 70 #> 3 24 92 #> 4 24 93 #> 5 24 120 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles x %>% slice_sample(n = 5) #> #> // safeframe object #> speed dist #> 1 23 54 #> 2 14 80 #> 3 12 14 #> 4 19 46 #> 5 19 68 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"verbs-operating-on-columns","dir":"Articles","previous_headings":"","what":"Verbs operating on columns","title":"Compatibility with dplyr","text":"operations columns, safeframe : stay invisible conserve labels labelled column affected operation trigger lost_labels_action() labelled columns affected operation","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrmutate-partial","dir":"Articles","previous_headings":"Verbs operating on columns","what":"dplyr::mutate() ✓ (partial)","title":"Compatibility with dplyr","text":"incomplete compatibility dplyr::mutate() simple renames without actual modification column don’t update labels. scenario, users rather use dplyr::rename() Although dplyr::mutate() able leverspeed full power safeframe labels, safeframe objects behave expected way data.frame :","code":"# In place modification doesn't lose labels x %>% mutate(speed = speed + 10) %>% head() #> #> // safeframe object #> speed dist #> 1 14 2 #> 2 14 10 #> 3 17 4 #> 4 17 22 #> 5 18 16 #> 6 19 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles # New columns don't affect existing labels x %>% mutate(ticket = speed >= 50) %>% head() #> #> // safeframe object #> speed dist ticket #> 1 4 2 FALSE #> 2 4 10 FALSE #> 3 7 4 FALSE #> 4 7 22 FALSE #> 5 8 16 FALSE #> 6 9 10 FALSE #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles # .keep = \"unused\" generate expected tag loss conditions x %>% mutate(edad = speed, .keep = \"unused\") %>% head() #> Warning: The following labelled variables are lost: #> speed - Miles per hour #> #> // safeframe object #> dist edad #> 1 2 4 #> 2 10 4 #> 3 4 7 #> 4 22 7 #> 5 16 8 #> 6 10 9 #> #> labelled variables: #> dist - Distance in miles #> edad - Miles per hour"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrpull","dir":"Articles","previous_headings":"Verbs operating on columns","what":"dplyr::pull() ✅","title":"Compatibility with dplyr","text":"dplyr::pull() returns vector, results, expected, loss safeframe class labels:","code":"x %>% pull(speed) #> [1] 4 4 7 7 8 9 10 10 10 11 11 12 12 12 12 13 13 13 13 14 14 14 14 15 15 #> [26] 15 16 16 17 17 17 18 18 18 18 19 19 19 20 20 20 20 20 22 23 24 24 24 24 25 #> attr(,\"label\") #> [1] \"Miles per hour\""},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrrelocate","dir":"Articles","previous_headings":"Verbs operating on columns","what":"dplyr::relocate() ✅","title":"Compatibility with dplyr","text":"","code":"x %>% relocate(speed, .before = 1) %>% head() #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrrename-dplyrrename_with","dir":"Articles","previous_headings":"Verbs operating on columns","what":"dplyr::rename() & dplyr::rename_with() ✅","title":"Compatibility with dplyr","text":"dplyr::rename() fully compatible ---box safeframe, meaning labels updated time columns renamed. possibly uses names<-() hood, safeframe provides custom names<-.safeframe() method :","code":"x %>% rename(edad = speed) %>% head() #> #> // safeframe object #> edad dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> edad - Miles per hour #> dist - Distance in miles x %>% rename_with(toupper) %>% head() #> #> // safeframe object #> SPEED DIST #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> SPEED - Miles per hour #> DIST - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrselect","dir":"Articles","previous_headings":"Verbs operating on columns","what":"dplyr::select() ✅","title":"Compatibility with dplyr","text":"dplyr::select() fully compatible safeframe, including columns renamed select():","code":"# Works fine x %>% select(speed, dist) %>% head() #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles # labels are updated! x %>% select(dist, edad = speed) %>% head() #> #> // safeframe object #> dist edad #> 1 2 4 #> 2 10 4 #> 3 4 7 #> 4 22 7 #> 5 16 8 #> 6 10 9 #> #> labelled variables: #> dist - Distance in miles #> edad - Miles per hour"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"verbs-operating-on-groups","dir":"Articles","previous_headings":"","what":"Verbs operating on groups ✘","title":"Compatibility with dplyr","text":"Groups yet supported. Applying verb operating group safeframe silently convert back data.frame tibble.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrbind_rows","dir":"Articles","previous_headings":"Verbs operating on data.frames","what":"dplyr::bind_rows() ✅","title":"Compatibility with dplyr","text":"","code":"dim(x) #> [1] 50 2 dim(bind_rows(x, x)) #> [1] 100 2"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrbind_cols","dir":"Articles","previous_headings":"Verbs operating on data.frames","what":"dplyr::bind_cols() ✘","title":"Compatibility with dplyr","text":"bind_cols() currently incompatible safeframe: labels second element lost Warnings produced lost labels, even labels actually lost","code":"bind_cols( suppressWarnings(select(x, speed)), suppressWarnings(select(x, dist)) ) %>% head() #> Warning: The following labelled variables are lost: #> speed - Miles per hour #> Warning: The following labelled variables are lost: #> dist - Distance in miles #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"joins","dir":"Articles","previous_headings":"Verbs operating on data.frames","what":"Joins ✘","title":"Compatibility with dplyr","text":"Joins currently compatible safeframe labels second element silently dropped.","code":"full_join( suppressWarnings(select(x, speed, dist)), suppressWarnings(select(x, dist, speed)) ) %>% head() #> Joining with `by = join_by(speed, dist)` #> Warning in full_join(suppressWarnings(select(x, speed, dist)), suppressWarnings(select(x, : Detected an unexpected many-to-many relationship between `x` and `y`. #> ℹ Row 17 of `x` matches multiple rows in `y`. #> ℹ Row 17 of `y` matches multiple rows in `x`. #> ℹ If a many-to-many relationship is expected, set `relationship = #> \"many-to-many\"` to silence this warning. #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/articles/compat-dplyr.html","id":"dplyrpick","dir":"Articles","previous_headings":"Verbs operating on multiple columns","what":"dplyr::pick() ✘","title":"Compatibility with dplyr","text":"pick() makes tidyselect functions work usually tidyselect-incompatible functions, : , expect work safeframe custom tidyselect-like function: has_label() ’s case since pick() currently strips attributes, including safeframe class labels. unclassing documented ?pick: pick() returns data frame containing selected columns current group.","code":"x %>% dplyr::arrange(dplyr::pick(ends_with(\"loc\"))) %>% head() #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/articles/design-principles.html","id":"scope","dir":"Articles","previous_headings":"","what":"Scope","title":"Design Principles for {safeframe}","text":"safeframe provides generic labelling validation tools. contrast original versions linelist (<=v1.1.4), safeframe functions variable level instead object level. validation tooling specific type checking variables providing feedback potential data loss coercion. aim complex validations time.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/design-principles.html","id":"naming-conventions","dir":"Articles","previous_headings":"","what":"Naming conventions","title":"Design Principles for {safeframe}","text":"separate functions much reasonable files R/. tests available file R/, follows convention test-.R tests/testthat/. source code respective tests. try make function names descriptive possible, keeping short. make package easy use understand.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/design-principles.html","id":"inputoutputinteroperability","dir":"Articles","previous_headings":"","what":"Input/Output/Interoperability","title":"Design Principles for {safeframe}","text":"data frame object can passed safeframe. Output safeframe remains data frame object, additional safeframe class attribute. means remains interoperable regular data frame operations one may attempt . safeframe interoperable pipes (, |> %>%). allows easy chaining functions. Note guarantees label attributes preserved piping wrangling another way. example, dplyr drops variable level attributes using dplyr::mutate().","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/design-principles.html","id":"design-decisions","dir":"Articles","previous_headings":"","what":"Design decisions","title":"Design Principles for {safeframe}","text":"Generic: package designed generic tool labelling validating data. ensure package can used wide range contexts limited specific use case. specific use cases implemented separate packages. Local: keep functions local possible. means operations precise feasible, non-destructive ensure changes one variable unexpectedly affect another. helps ensure package predictable easy use + maintain. Minimize number functions: aim keep number functions package minimum. helps usability maintainability. Base R: aim use base R functions possible. ensure package lightweight many dependencies. example use labelled labelling package. feel like uphold one design decisions, please let us know 😊","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/design-principles.html","id":"quirks","dir":"Articles","previous_headings":"Design decisions","what":"Quirks","title":"Design Principles for {safeframe}","text":"package development quirks. outline quirks aware : Currently, emptying labels leads setting \"\" (empty character strings). Preferably end setting NULL end.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/design-principles.html","id":"dependencies","dir":"Articles","previous_headings":"","what":"Dependencies","title":"Design Principles for {safeframe}","text":"checkmate - provide assertions function arguments lifecycle - help manage function lifecycle rlang - ... list parsing tidyselect - ensure can use pipes has_label()","code":""},{"path":"https://epiverse-trace.github.io/safeframe/articles/design-principles.html","id":"development-journey","dir":"Articles","previous_headings":"","what":"Development journey","title":"Design Principles for {safeframe}","text":"safeframe package major refactor linelist v1.1.4. refactor necessary make package generic make codebase maintainable. refactor completed series steps documented #37.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Chris Hartgerink. Maintainer, author. Hugo Gruson. Reviewer.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Hartgerink C (2024). safeframe: Generic Data Labelling Validating. R package version 0.0.1, https://github.com/epiverse-trace/safeframe, https://epiverse-trace.github.io/safeframe/.","code":"@Manual{, title = {safeframe: Generic Data Labelling and Validating}, author = {Chris Hartgerink}, year = {2024}, note = {R package version 0.0.1, https://github.com/epiverse-trace/safeframe}, url = {https://epiverse-trace.github.io/safeframe/}, }"},{"path":"https://epiverse-trace.github.io/safeframe/index.html","id":"safeframe-generic-data-labelling-and-validating-","dir":"","previous_headings":"","what":"Generic Data Labelling and Validating","title":"Generic Data Labelling and Validating","text":"safeframe provides functions label validate data kind. safeframe abstraction linelist, applies principles epidemiological linelist data. original proposal package can found Discussion board.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Generic Data Labelling and Validating","text":"can install development version safeframe GitHub :","code":"# install.packages(\"pak\") pak::pak(\"epiverse-trace/safeframe\")"},{"path":"https://epiverse-trace.github.io/safeframe/index.html","id":"getting-started","dir":"","previous_headings":"","what":"Getting started","title":"Generic Data Labelling and Validating","text":"","code":"library(safeframe) # Create a safeframe object x <- make_safeframe(cars, speed = 'Miles per hour', dist = 'Distance in miles') # Validate the data are of a specific type validate_safeframe(x, speed = 'numeric', # speed should be numeric # type() is a helper function of related classes dist = type('numeric') # dist should be numeric, integer )"},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/index.html","id":"lifecycle","dir":"","previous_headings":"Development","what":"Lifecycle","title":"Generic Data Labelling and Validating","text":"package currently experimental, defined RECON software lifecycle. means essential features mechanisms still developed, package ready use outside development team.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/index.html","id":"contributions","dir":"","previous_headings":"Development","what":"Contributions","title":"Generic Data Labelling and Validating","text":"Contributions welcome via pull requests. Anything bigger typo fix small documentation update discussed issue first. want report bug suggest enhancement, please open issue. 😊 See also general Epiverse TRACE contribution document. make easier us evaluate contribution, please run following commands submitting pull request ensure code consistent rest package: reduce time takes us review contribution. Thank ! 😊","code":"styler::style_pkg() devtools::document() spelling::update_wordlist(pkg = \".\", vignettes = TRUE) lintr::lint_package() devtools::test() devtools::check()"},{"path":"https://epiverse-trace.github.io/safeframe/index.html","id":"related-projects","dir":"","previous_headings":"Development","what":"Related projects","title":"Generic Data Labelling and Validating","text":"project related existing projects R languages, also differs following aspects: labelled: package labelling data R, focused labelling variables validating . linelist: package managing validating linelist data - original inspiration safeframe.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/index.html","id":"code-of-conduct","dir":"","previous_headings":"Development","what":"Code of Conduct","title":"Generic Data Labelling and Validating","text":"Please note safeframe project released Contributor Code Conduct. contributing project, agree abide terms.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/has_label.html","id":null,"dir":"Reference","previous_headings":"","what":"A selector function to use in tidyverse functions — has_label","title":"A selector function to use in tidyverse functions — has_label","text":"selector function use tidyverse functions","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/has_label.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"A selector function to use in tidyverse functions — has_label","text":"","code":"has_label(labels)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/has_label.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"A selector function to use in tidyverse functions — has_label","text":"labels character vector labels want operate ","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/has_label.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"A selector function to use in tidyverse functions — has_label","text":"numeric vector containing position columns requested labels","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/has_label.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"A selector function to use in tidyverse functions — has_label","text":"Using pipeline results 'safeframe' object, maintain variable labels time. primarily useful make pipelines human readable.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/has_label.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"A selector function to use in tidyverse functions — has_label","text":"","code":"## create safeframe x <- make_safeframe(cars, speed = \"Miles per hour\", dist = \"Distance in miles\" ) head(x) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles if (require(dplyr) && require(magrittr)) { x %>% select(has_label(c(\"Miles per hour\", \"Distance in miles\"))) %>% head() } #> Loading required package: dplyr #> #> Attaching package: ‘dplyr’ #> The following objects are masked from ‘package:stats’: #> #> filter, lag #> The following objects are masked from ‘package:base’: #> #> intersect, setdiff, setequal, union #> Loading required package: magrittr #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/reference/label_variables.html","id":null,"dir":"Reference","previous_headings":"","what":"Add labels to variables — label_variables","title":"Add labels to variables — label_variables","text":"Internal. function label pre-defined variables data.frame adding label attribute column. can used one multiple variables time.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/label_variables.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Add labels to variables — label_variables","text":"","code":"label_variables(x, labels)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/label_variables.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Add labels to variables — label_variables","text":"x data.frame tibble, least one column labels named list variable names x list names labels list values. Values set NULL remove label.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/label_variables.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Add labels to variables — label_variables","text":"function returns original object additional \"label\" attribute provided variable.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/label_variables.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Add labels to variables — label_variables","text":"used several times, previous label removed silently. accepts known variables provided data.frame.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Get the list of labels in a safeframe — labels","title":"Get the list of labels in a safeframe — labels","text":"function returns list labels identifying specific variable types safeframe object.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Get the list of labels in a safeframe — labels","text":"","code":"labels(x, show_null = FALSE)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Get the list of labels in a safeframe — labels","text":"x safeframe object show_null logical indicating complete list labels, including NULL ones, returned; FALSE, labels non-NULL value returned; defaults FALSE","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Get the list of labels in a safeframe — labels","text":"function returns named list names indicate column correspond , values indicate relevant labels.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Get the list of labels in a safeframe — labels","text":"Labels stored label attribute column variable.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Get the list of labels in a safeframe — labels","text":"","code":"## make a safeframe x <- make_safeframe(cars, speed = \"Miles per hour\") ## check non-null labels labels(x) #> $speed #> [1] \"Miles per hour\" #> ## get a list of all labels, including NULL ones labels(x, TRUE) #> $speed #> [1] \"Miles per hour\" #> #> $dist #> NULL #>"},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels_df.html","id":null,"dir":"Reference","previous_headings":"","what":"Extract a data.frame of all labelled variables — labels_df","title":"Extract a data.frame of all labelled variables — labels_df","text":"function returns data.frame, labelled variables (stored safeframe object) renamed. Note output longer safeframe, regular data.frame. Unlabeled variables unaffected.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels_df.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Extract a data.frame of all labelled variables — labels_df","text":"","code":"labels_df(x)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels_df.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Extract a data.frame of all labelled variables — labels_df","text":"x safeframe object","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels_df.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Extract a data.frame of all labelled variables — labels_df","text":"data.frame variables renamed according labels.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/labels_df.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Extract a data.frame of all labelled variables — labels_df","text":"","code":"x <- make_safeframe(cars, speed = \"Miles per hour\", dist = \"Distance in miles\" ) ## get a data.frame with variables renamed based on labels labels_df(x) #> Miles per hour Distance in miles #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85"},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Check for lost labels and throw relevant warning or error — lost_labels","title":"Check for lost labels and throw relevant warning or error — lost_labels","text":"internal function checks labels present old labels new labels. labels lost, throws warning error based specified action.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Check for lost labels and throw relevant warning or error — lost_labels","text":"","code":"lost_labels(old, new, lost_action)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Check for lost labels and throw relevant warning or error — lost_labels","text":"old named list old labels. new named list new labels. lost_action character string specifying action take labels lost. Can \"none\", \"warning\", \"error\".","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Check for lost labels and throw relevant warning or error — lost_labels","text":"None. Throws warning error labels lost.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels_action.html","id":null,"dir":"Reference","previous_headings":"","what":"Check and set behaviour for lost labels — lost_labels_action","title":"Check and set behaviour for lost labels — lost_labels_action","text":"function determines behaviour adopt labelled variables safeframe lost example subsetting. achieved using options defined safeframe package.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels_action.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Check and set behaviour for lost labels — lost_labels_action","text":"","code":"lost_labels_action(action = c(\"warning\", \"error\", \"none\"), quiet = FALSE) get_lost_labels_action()"},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels_action.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Check and set behaviour for lost labels — lost_labels_action","text":"action character indicating behaviour adopt labelled variables lost: \"error\" (default) issue error; \"warning\" issue warning; \"none\" nothing quiet logical indicating message displayed; used outside pipelines","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels_action.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Check and set behaviour for lost labels — lost_labels_action","text":"returns NULL; option set options(\"safeframe\")","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels_action.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Check and set behaviour for lost labels — lost_labels_action","text":"errors warnings generated safeframe case labelled variable loss custom class safeframe_error safeframe_warning respectively.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/lost_labels_action.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Check and set behaviour for lost labels — lost_labels_action","text":"","code":"# reset default - done automatically at package loading lost_labels_action() #> Lost labels will now issue a warning. # check current value get_lost_labels_action() #> [1] \"warning\" # change to issue errors when tags are lost lost_labels_action(\"error\") #> Lost labels will now issue an error. get_lost_labels_action() #> [1] \"error\" # change to ignore when tags are lost lost_labels_action(\"none\") #> Lost labels will now be ignored. get_lost_labels_action() #> [1] \"none\" # reset to default: warning lost_labels_action() #> Lost labels will now issue a warning."},{"path":"https://epiverse-trace.github.io/safeframe/reference/make_safeframe.html","id":null,"dir":"Reference","previous_headings":"","what":"Create a safeframe from a data.frame — make_safeframe","title":"Create a safeframe from a data.frame — make_safeframe","text":"function converts data.frame tibble safeframe object, data labelled validated. output seem data.frame, safeframe-aware packages able automatically use labelled fields data cleaning analysis.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/make_safeframe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Create a safeframe from a data.frame — make_safeframe","text":"","code":"make_safeframe(x, ...)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/make_safeframe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Create a safeframe from a data.frame — make_safeframe","text":"x data.frame tibble ... named list variable names x list names labels list values. Values set NULL remove label. specifying labels, please also see default_values.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/make_safeframe.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Create a safeframe from a data.frame — make_safeframe","text":"function returns safeframe object.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/reference/make_safeframe.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Create a safeframe from a data.frame — make_safeframe","text":"","code":"x <- make_safeframe(cars, speed = \"Miles per hour\", dist = \"Distance in miles\" ) ## print result - just first few entries head(x) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles ## check labels labels(x) #> $speed #> [1] \"Miles per hour\" #> #> $dist #> [1] \"Distance in miles\" #> ## Labels can also be passed as a list with the splice operator (!!!) my_labels <- list( speed = \"Miles per hour\", dist = \"Distance in miles\" ) new_x <- make_safeframe(cars, !!!my_labels) ## The output is strictly equivalent to the previous one identical(x, new_x) #> [1] TRUE"},{"path":"https://epiverse-trace.github.io/safeframe/reference/names-set-.safeframe.html","id":null,"dir":"Reference","previous_headings":"","what":"Rename columns of a safeframe — names<-.safeframe","title":"Rename columns of a safeframe — names<-.safeframe","text":"function can used rename columns safeframe (, adjust variable names).","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/names-set-.safeframe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Rename columns of a safeframe — names<-.safeframe","text":"","code":"# S3 method for class 'safeframe' names(x) <- value"},{"path":"https://epiverse-trace.github.io/safeframe/reference/names-set-.safeframe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Rename columns of a safeframe — names<-.safeframe","text":"x safeframe object value character vector set new names columns x","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/names-set-.safeframe.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Rename columns of a safeframe — names<-.safeframe","text":"safeframe new column names","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/names-set-.safeframe.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Rename columns of a safeframe — names<-.safeframe","text":"","code":"## create safeframe x <- make_safeframe(cars, speed = \"Miles per hour\", dist = \"Distance in miles\" ) head(x) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles ## change names names(x)[1] <- \"mph\" ## see results: columns have been updated head(x) #> #> // safeframe object #> mph dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> mph - Miles per hour #> dist - Distance in miles # This also works with using `dplyr::rename()` because it uses names<-() # under the hood if (require(dplyr) && require(magrittr)) { x <- x %>% rename(speed = \"mph\") head(x) labels(x) } #> $speed #> [1] \"Miles per hour\" #> #> $dist #> [1] \"Distance in miles\" #>"},{"path":"https://epiverse-trace.github.io/safeframe/reference/print.safeframe.html","id":null,"dir":"Reference","previous_headings":"","what":"Printing method for safeframe objects — print.safeframe","title":"Printing method for safeframe objects — print.safeframe","text":"function prints safeframe objects.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/print.safeframe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Printing method for safeframe objects — print.safeframe","text":"","code":"# S3 method for class 'safeframe' print(x, ...)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/print.safeframe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Printing method for safeframe objects — print.safeframe","text":"x safeframe object ... arguments passed 'print'","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/print.safeframe.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Printing method for safeframe objects — print.safeframe","text":"Invisibly returns object.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/print.safeframe.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Printing method for safeframe objects — print.safeframe","text":"","code":"## create safeframe x <- make_safeframe(cars, speed = \"Miles per hour\", dist = \"Distance in miles\" ) ## print object - using only the first few entries head(x) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles # version with a tibble if (require(tibble) && require(magrittr)) { cars %>% tibble() %>% make_safeframe( speed = \"Miles per hour\", dist = \"Distance in miles\" ) } #> Loading required package: tibble #> #> // safeframe object #> # A tibble: 50 × 2 #> speed dist #> #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> # ℹ 40 more rows #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/reference/safeframe-package.html","id":null,"dir":"Reference","previous_headings":"","what":"Base Tools for Labelling and Validating Data — safeframe-package","title":"Base Tools for Labelling and Validating Data — safeframe-package","text":"safeframe package provides tools help label validate data. 'safeframe' class adds column level attributes 'data.frame'. labelled, variables can seamlessly used downstream analyses, making data pipelines robust reliable.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/safeframe-package.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"Base Tools for Labelling and Validating Data — safeframe-package","text":"package aim complete integration dplyr functions. example, dplyr::mutate() dplyr::bind_rows() preserve labels. provide compatibility dplyr::rename().","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/safeframe-package.html","id":"main-functions","dir":"Reference","previous_headings":"","what":"Main functions","title":"Base Tools for Labelling and Validating Data — safeframe-package","text":"make_safeframe(): create safeframe objects data.frame tibble set_labels(): change add labelled variables safeframe labels(): get list labels safeframe labels_df(): get data.frame tagged variables lost_labels_action(): change behaviour actions labelled variables lost (e.g removing columns storing labelled variables) issue warnings, errors, nothing get_lost_labels_action(): check current behaviour actions labelled variables lost","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/safeframe-package.html","id":"dedicated-methods","dir":"Reference","previous_headings":"","what":"Dedicated methods","title":"Base Tools for Labelling and Validating Data — safeframe-package","text":"Specific methods commonly used handle data.frame provided safeframe objects, typically help flag prevent actions alter lose labelled variables (may thus break downstream data pipelines). names() <- (related functions, dplyr::rename()) rename labels needed x[...] <- x[[...]] <- (see sub_safeframe): adopt desired behaviour labelled variables lost print(): prints info safeframe addition data.frame tibble","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/reference/safeframe-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Base Tools for Labelling and Validating Data — safeframe-package","text":"Maintainer: Chris Hartgerink chris@data.org (ORCID) contributors: Hugo Gruson hugo@data.org (ORCID) [reviewer]","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/safeframe-package.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Base Tools for Labelling and Validating Data — safeframe-package","text":"","code":"# using base R style x <- make_safeframe(cars[1:50, ], speed = \"Miles per hour\", dist = \"Distance in miles\" ) x #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles ## check labelled variables labels(x) #> $speed #> [1] \"Miles per hour\" #> #> $dist #> [1] \"Distance in miles\" #> ## robust renaming names(x)[1] <- \"identifier\" x #> #> // safeframe object #> identifier dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> identifier - Miles per hour #> dist - Distance in miles ## example of dropping labels by mistake - default: warning x[, 2] #> Warning: The following labelled variables are lost: #> identifier - Miles per hour #> #> // safeframe object #> dist #> 1 2 #> 2 10 #> 3 4 #> 4 22 #> 5 16 #> 6 10 #> 7 18 #> 8 26 #> 9 34 #> 10 17 #> 11 28 #> 12 14 #> 13 20 #> 14 24 #> 15 28 #> 16 26 #> 17 34 #> 18 34 #> 19 46 #> 20 26 #> 21 36 #> 22 60 #> 23 80 #> 24 20 #> 25 26 #> 26 54 #> 27 32 #> 28 40 #> 29 32 #> 30 40 #> 31 50 #> 32 42 #> 33 56 #> 34 76 #> 35 84 #> 36 36 #> 37 46 #> 38 68 #> 39 32 #> 40 48 #> 41 52 #> 42 56 #> 43 64 #> 44 66 #> 45 54 #> 46 70 #> 47 92 #> 48 93 #> 49 120 #> 50 85 #> #> labelled variables: #> dist - Distance in miles ## to silence warnings when labels are dropped lost_labels_action(\"none\") #> Lost labels will now be ignored. x[, 2] #> #> // safeframe object #> dist #> 1 2 #> 2 10 #> 3 4 #> 4 22 #> 5 16 #> 6 10 #> 7 18 #> 8 26 #> 9 34 #> 10 17 #> 11 28 #> 12 14 #> 13 20 #> 14 24 #> 15 28 #> 16 26 #> 17 34 #> 18 34 #> 19 46 #> 20 26 #> 21 36 #> 22 60 #> 23 80 #> 24 20 #> 25 26 #> 26 54 #> 27 32 #> 28 40 #> 29 32 #> 30 40 #> 31 50 #> 32 42 #> 33 56 #> 34 76 #> 35 84 #> 36 36 #> 37 46 #> 38 68 #> 39 32 #> 40 48 #> 41 52 #> 42 56 #> 43 64 #> 44 66 #> 45 54 #> 46 70 #> 47 92 #> 48 93 #> 49 120 #> 50 85 #> #> labelled variables: #> dist - Distance in miles ## to trigger errors when labels are dropped # lost_labels_action(\"error\") # x[, 2:5] ## reset default behaviour lost_labels_action() #> Lost labels will now issue a warning. # using tidyverse style ## example of creating a safeframe, adding a new variable, and adding a label ## for it if (require(dplyr) && require(magrittr)) { x <- cars %>% tibble() %>% make_safeframe( speed = \"Miles per hour\", dist = \"Distance in miles\" ) %>% mutate(result = if_else(speed > 50, \"fast\", \"slow\")) %>% set_labels(result = \"Ticket yes/no\") head(x) ## extract labelled variables x %>% select(has_label(c(\"Ticket yes/no\"))) ## Retrieve all labels x %>% labels() ## Select based on variable name x %>% select(starts_with(\"speed\")) } #> Warning: The following labelled variables are lost: #> speed - Miles per hour #> dist - Distance in miles #> Warning: The following labelled variables are lost: #> dist - Distance in miles #> result - Ticket yes/no #> #> // safeframe object #> # A tibble: 50 × 1 #> speed #> #> 1 4 #> 2 4 #> 3 7 #> 4 7 #> 5 8 #> 6 9 #> 7 10 #> 8 10 #> 9 10 #> 10 11 #> # ℹ 40 more rows #> #> labelled variables: #> speed - Miles per hour"},{"path":"https://epiverse-trace.github.io/safeframe/reference/set_labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Change labels of a safeframe object — set_labels","title":"Change labels of a safeframe object — set_labels","text":"function changes labels safeframe object, using syntax constructor make_safeframe().","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/set_labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Change labels of a safeframe object — set_labels","text":"","code":"set_labels(x, ...)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/set_labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Change labels of a safeframe object — set_labels","text":"x data.frame tibble ... named list variable names x list names labels list values. Values set NULL remove label. specifying labels, please also see default_values.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/set_labels.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Change labels of a safeframe object — set_labels","text":"function returns safeframe object.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/reference/set_labels.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Change labels of a safeframe object — set_labels","text":"","code":"## create a safeframe x <- make_safeframe(cars, speed = \"Miles per hour\") labels(x) #> $speed #> [1] \"Miles per hour\" #> ## add new labels and fix an existing one x <- set_labels(x, dist = \"Distance\") labels(x) #> $speed #> [1] \"Miles per hour\" #> #> $dist #> [1] \"Distance\" #> ## remove labels by setting them to NULL old_labels <- labels(x) x <- set_labels(x, speed = NULL, dist = NULL) labels(x) #> $speed #> [1] \"\" #> #> $dist #> [1] \"\" #> ## setting labels providing a list (used to restore old labels here) x <- set_labels(x, !!!old_labels) labels(x) #> $speed #> [1] \"Miles per hour\" #> #> $dist #> [1] \"Distance\" #>"},{"path":"https://epiverse-trace.github.io/safeframe/reference/sub_safeframe.html","id":null,"dir":"Reference","previous_headings":"","what":"Subsetting of safeframe objects — [.safeframe","title":"Subsetting of safeframe objects — [.safeframe","text":"[] [[]] operators safeframe objects behaves like regular data.frame tibble, check labelled variables lost, takes appropriate action case (warning, error, ignore, depending general option set via lost_labels_action()) .","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/sub_safeframe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Subsetting of safeframe objects — [.safeframe","text":"","code":"# S3 method for class 'safeframe' x[i, j, drop = FALSE] # S3 method for class 'safeframe' x[i, j] <- value # S3 method for class 'safeframe' x[[i, j]] <- value # S3 method for class 'safeframe' x$name <- value"},{"path":"https://epiverse-trace.github.io/safeframe/reference/sub_safeframe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Subsetting of safeframe objects — [.safeframe","text":"x safeframe object vector integer logical subset rows safeframe j vector character, integer, logical subset columns safeframe drop logical indicating , single column selected, data.frame class dropped return simple vector, case safeframe class lost well; defaults FALSE value replacement used entries identified x name literal character string name (possibly backtick quoted). extraction, normally (see ‘Environments’) partially matched names object.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/sub_safeframe.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Subsetting of safeframe objects — [.safeframe","text":"drop happening, safeframe. Otherwise atomic vector.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/reference/sub_safeframe.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Subsetting of safeframe objects — [.safeframe","text":"","code":"if (require(dplyr) && require(magrittr)) { ## create a safeframe x <- cars %>% make_safeframe( speed = \"Miles per hour\", dist = \"Distance in miles\" ) %>% mutate(result = if_else(speed > 50, \"fast\", \"slow\")) %>% set_labels(result = \"Ticket\") x ## dangerous removal of a labelled column setting it to NULL issues warning x[, 1] <- NULL x x[[2]] <- NULL x x$age <- NULL x } #> Warning: The following labelled variables are lost: #> speed - Miles per hour #> Warning: The following labelled variables are lost: #> result - Ticket #> #> // safeframe object #> dist #> 1 2 #> 2 10 #> 3 4 #> 4 22 #> 5 16 #> 6 10 #> 7 18 #> 8 26 #> 9 34 #> 10 17 #> 11 28 #> 12 14 #> 13 20 #> 14 24 #> 15 28 #> 16 26 #> 17 34 #> 18 34 #> 19 46 #> 20 26 #> 21 36 #> 22 60 #> 23 80 #> 24 20 #> 25 26 #> 26 54 #> 27 32 #> 28 40 #> 29 32 #> 30 40 #> 31 50 #> 32 42 #> 33 56 #> 34 76 #> 35 84 #> 36 36 #> 37 46 #> 38 68 #> 39 32 #> 40 48 #> 41 52 #> 42 56 #> 43 64 #> 44 66 #> 45 54 #> 46 70 #> 47 92 #> 48 93 #> 49 120 #> 50 85 #> #> labelled variables: #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/reference/type.html","id":null,"dir":"Reference","previous_headings":"","what":"Type Selection Helper — type","title":"Type Selection Helper — type","text":"Function swiftly provide access generic categories types within R. can used provide comprehensive typesetting creating safeframe object.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/type.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Type Selection Helper — type","text":"","code":"type(x)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/type.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Type Selection Helper — type","text":"x Character indicating desired type. Options include date, category, numeric, binary time.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/type.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Type Selection Helper — type","text":"vector classes","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/type.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Type Selection Helper — type","text":"","code":"x <- make_safeframe(cars, speed = \"Miles per hour\", dist = \"Distance in miles\" ) validate_types( x, speed = type(\"numeric\"), dist = \"numeric\" ) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Checks the labels of a safeframe object — validate_labels","title":"Checks the labels of a safeframe object — validate_labels","text":"function evaluates validity labels safeframe object checking : ) labels present ii) labels list character NULL values.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Checks the labels of a safeframe object — validate_labels","text":"","code":"validate_labels(x)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Checks the labels of a safeframe object — validate_labels","text":"x safeframe object","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_labels.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Checks the labels of a safeframe object — validate_labels","text":"checks pass, safeframe object; otherwise issues error.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_labels.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Checks the labels of a safeframe object — validate_labels","text":"","code":"## create a valid safeframe x <- cars |> make_safeframe( speed = \"Miles per hour\", dist = \"Distance in miles\" ) x #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles ## the below issues an error as safeframe doesn't know any defaults ## note: tryCatch is only used to avoid a genuine error in the example tryCatch(validate_safeframe(x), error = paste) #> [1] \"Error in validate_types(x, ...): Assertion on 'types' failed: Must have length >= 1, but has length 0.\\n\" ## validation requires you to specify the types directly validate_safeframe(x, speed = c(\"integer\", \"numeric\"), dist = \"numeric\" ) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_safeframe.html","id":null,"dir":"Reference","previous_headings":"","what":"Checks the content of a safeframe object — validate_safeframe","title":"Checks the content of a safeframe object — validate_safeframe","text":"function evaluates validity safeframe object checking object class, labels, types variables. combines validation checks made validate_types() validate_labels(). See 'Details' section information checks performed.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_safeframe.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Checks the content of a safeframe object — validate_safeframe","text":"","code":"validate_safeframe(x, ...)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_safeframe.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Checks the content of a safeframe object — validate_safeframe","text":"x safeframe object ... named list variable names x list names related types list values.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_safeframe.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Checks the content of a safeframe object — validate_safeframe","text":"checks pass, safeframe object; otherwise issues error.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_safeframe.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Checks the content of a safeframe object — validate_safeframe","text":"following checks performed: x safeframe object variables x well-formed label attribute variables correspond specified types","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_safeframe.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Checks the content of a safeframe object — validate_safeframe","text":"","code":"## create a valid safeframe x <- cars |> make_safeframe( speed = \"Miles per hour\", dist = \"Distance in miles\" ) x #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles ## validation validate_safeframe(x, speed = c(\"numeric\", \"factor\"), dist = \"numeric\" ) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles ## the below issues an error ## note: tryCatch is only used to avoid a genuine error in the example tryCatch(validate_safeframe(x, speed = c(\"numeric\", \"factor\"), dist = \"factor\" ), error = paste) #> [1] \"Error: Some labels have the wrong class:\\n - dist: Must inherit from class 'factor', but has class 'numeric'\\n\\n\""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_types.html","id":null,"dir":"Reference","previous_headings":"","what":"Type check variables — validate_types","title":"Type check variables — validate_types","text":"function checks type variables safeframe accepted classes. checks type provided variables ignores provided.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_types.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Type check variables — validate_types","text":"","code":"validate_types(x, ...)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_types.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Type check variables — validate_types","text":"x safeframe object ... named list variable names x list names related types list values.","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_types.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Type check variables — validate_types","text":"named list.","code":""},{"path":[]},{"path":"https://epiverse-trace.github.io/safeframe/reference/validate_types.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Type check variables — validate_types","text":"","code":"x <- make_safeframe(cars, speed = \"Miles per hour\", dist = \"Distance in miles\" ) x #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles ## the below would issue an error ## note: tryCatch is only used to avoid a genuine error in the example tryCatch(validate_types(x), error = paste) #> [1] \"Error in validate_types(x): Assertion on 'types' failed: Must have length >= 1, but has length 0.\\n\" ## to allow other types, e.g. gender to be integer, character or factor validate_types(x, speed = \"numeric\", dist = c( \"integer\", \"character\", \"numeric\" )) #> #> // safeframe object #> speed dist #> 1 4 2 #> 2 4 10 #> 3 7 4 #> 4 7 22 #> 5 8 16 #> 6 9 10 #> 7 10 18 #> 8 10 26 #> 9 10 34 #> 10 11 17 #> 11 11 28 #> 12 12 14 #> 13 12 20 #> 14 12 24 #> 15 12 28 #> 16 13 26 #> 17 13 34 #> 18 13 34 #> 19 13 46 #> 20 14 26 #> 21 14 36 #> 22 14 60 #> 23 14 80 #> 24 15 20 #> 25 15 26 #> 26 15 54 #> 27 16 32 #> 28 16 40 #> 29 17 32 #> 30 17 40 #> 31 17 50 #> 32 18 42 #> 33 18 56 #> 34 18 76 #> 35 18 84 #> 36 19 36 #> 37 19 46 #> 38 19 68 #> 39 20 32 #> 40 20 48 #> 41 20 52 #> 42 20 56 #> 43 20 64 #> 44 22 66 #> 45 23 54 #> 46 24 70 #> 47 24 92 #> 48 24 93 #> 49 24 120 #> 50 25 85 #> #> labelled variables: #> speed - Miles per hour #> dist - Distance in miles"},{"path":"https://epiverse-trace.github.io/safeframe/reference/vars_labels.html","id":null,"dir":"Reference","previous_headings":"","what":"Internal printing function for variables and labels — vars_labels","title":"Internal printing function for variables and labels — vars_labels","text":"Internal printing function variables labels","code":""},{"path":"https://epiverse-trace.github.io/safeframe/reference/vars_labels.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Internal printing function for variables and labels — vars_labels","text":"","code":"vars_labels(vars, labels)"},{"path":"https://epiverse-trace.github.io/safeframe/reference/vars_labels.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Internal printing function for variables and labels — vars_labels","text":"vars character vector variable names labels character vector labels","code":""}] diff --git a/sitemap.xml b/sitemap.xml index 6bcd54a..01de46f 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -10,6 +10,7 @@ https://epiverse-trace.github.io/safeframe/news/index.html https://epiverse-trace.github.io/safeframe/reference/has_label.html https://epiverse-trace.github.io/safeframe/reference/index.html +https://epiverse-trace.github.io/safeframe/reference/label_variables.html https://epiverse-trace.github.io/safeframe/reference/labels.html https://epiverse-trace.github.io/safeframe/reference/labels_df.html https://epiverse-trace.github.io/safeframe/reference/lost_labels.html