From 9d85509caa32f75d424c34b69632bd37fb5af549 Mon Sep 17 00:00:00 2001 From: Patrick Anker Date: Mon, 29 Apr 2024 23:11:31 -0400 Subject: [PATCH] docs: update README --- README.Rmd | 51 +++++++++++++++++++-------------- README.md | 82 ++++++++++++++++++++++++++---------------------------- 2 files changed, 69 insertions(+), 64 deletions(-) diff --git a/README.Rmd b/README.Rmd index 90ba383..b7db16e 100644 --- a/README.Rmd +++ b/README.Rmd @@ -13,9 +13,9 @@ knitr::opts_chunk$set( ) ``` -# blueprintr +# blueprintr -> blueprintr is a plugin to [drake](https://github.com/ropensci/drake) that adds automated steps for tabular dataset documentation and testing. Designed for social science research projects, this package creates a framework to build trust in your data and to prevent programming issues from affecting your analysis results. +> blueprintr is a companion to [targets](https://github.com/ropensci/targets) that adds automated steps for tabular dataset documentation and testing. Designed for social science research projects, this package creates a framework to build trust in your data and to prevent programming issues from affecting your analysis results. [![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental) @@ -25,12 +25,11 @@ knitr::opts_chunk$set( ## Usage -Define blueprints of your data using `blueprint()`. Blueprints combine drake target commands with some extra metadata about the output tabular dataset, including the name and description of the data. +Define blueprints of your data using `blueprint()`. Blueprints combine dataset creation code with some extra metadata about the output tabular dataset, including the name and description of the data. By convention, these blueprint calls are stored in scripts in the "blueprints" folder of your project: -```{r} -library(blueprintr) - -blueprint1 <- blueprint( +```{r, eval=FALSE} +# blueprints/blueprint1.R +blueprint( "blueprint1", description = "My first blueprint", command = { @@ -38,46 +37,56 @@ blueprint1 <- blueprint( mtcars } ) - -blueprint1 ``` -Refer to other datasets using `.TARGET()` to guarantee that parent datasets are also tested and documented. Run checks on the dataset entirely with the `checks` parameter and define variable tests in the metadata files. +Refer to other datasets using `.TARGET()` to guarantee that parent datasets are also tested and documented. Run checks on the dataset entirely with the `checks` parameter and define variable tests in the metadata files. You can store these tests in the conventional "R" folder: ```{r, eval=FALSE} +# R/checks.R no_missing_cyl <- function(df) { all(!is.na(df$cyl)) } +``` +```{r, eval=FALSE} +# blueprints/blueprint2.R blueprint2 <- blueprint( "blueprint2", description = "My second blueprint that depends on another", checks = check_list( no_missing_cyl() ), - command = - .TARGET("blueprint1") %>% - filter(cyl == 4) + command = .TARGET("blueprint1") %>% + filter(cyl == 4) ) ``` -Once all blueprints are defined, attach them to a plan using `attach_blueprint()` or `attach_blueprints()` so drake can run the needed tasks. +Once all blueprints are defined, add them to your `_targets.R` pipeline file: ```{r, eval=FALSE} -library(magrittr) -library(drake) +# _targets.R +library(targts) +library(blueprintr) -plan_from_blueprint(blueprint1) %>% - attach_blueprint(blueprint2) +list( + # ... Other steps ... + tar_blueprints() +) ``` -drake handles the code execution based on the targets generated by blueprintr. +targets handles the code execution based on the steps generated by blueprintr. ## Installation -As blueprintr is not yet on CRAN, you must install the package from this repository: +Stable versions of blueprintr can be installed from Global TIES' r-universe: + +```r +install.packages("blueprintr", repos = "https://nyuglobalties.r-universe.dev") +``` + +Development versions can be installed from this repository: -``` r +```r install.packages("remotes") remotes::install_github("nyuglobalties/blueprintr") ``` diff --git a/README.md b/README.md index 66b56b9..eb4a566 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,14 @@ -# blueprintr +# blueprintr -> blueprintr is a plugin to [drake](https://github.com/ropensci/drake) -> that adds automated steps for tabular dataset documentation and -> testing. Designed for social science research projects, this package -> creates a framework to build trust in your data and to prevent -> programming issues from affecting your analysis results. +> blueprintr is a companion to +> [targets](https://github.com/ropensci/targets) that adds automated +> steps for tabular dataset documentation and testing. Designed for +> social science research projects, this package creates a framework to +> build trust in your data and to prevent programming issues from +> affecting your analysis results. @@ -21,13 +22,14 @@ status](https://www.r-pkg.org/badges/version/blueprintr)](https://CRAN.R-project ## Usage Define blueprints of your data using `blueprint()`. Blueprints combine -drake target commands with some extra metadata about the output tabular -dataset, including the name and description of the data. +dataset creation code with some extra metadata about the output tabular +dataset, including the name and description of the data. By convention, +these blueprint calls are stored in scripts in the “blueprints” folder +of your project: ``` r -library(blueprintr) - -blueprint1 <- blueprint( +# blueprints/blueprint1.R +blueprint( "blueprint1", description = "My first blueprint", command = { @@ -35,67 +37,61 @@ blueprint1 <- blueprint( mtcars } ) - -blueprint1 -#> -#> -#> Description: My first blueprint -#> Annotations: DISABLED -#> Metadata location: '/Users/patrickanker/dev/blueprintr/blueprints/blueprint1.csv' -#> -#> -- Command -- -#> Workflow command: -#> { -#> mtcars -#> } -#> -#> Raw command: -#> { -#> mtcars -#> } ``` Refer to other datasets using `.TARGET()` to guarantee that parent datasets are also tested and documented. Run checks on the dataset entirely with the `checks` parameter and define variable tests in the -metadata files. +metadata files. You can store these tests in the conventional “R” +folder: ``` r +# R/checks.R no_missing_cyl <- function(df) { all(!is.na(df$cyl)) } +``` +``` r +# blueprints/blueprint2.R blueprint2 <- blueprint( "blueprint2", description = "My second blueprint that depends on another", checks = check_list( no_missing_cyl() ), - command = - .TARGET("blueprint1") %>% - filter(cyl == 4) + command = .TARGET("blueprint1") %>% + filter(cyl == 4) ) ``` -Once all blueprints are defined, attach them to a plan using -`attach_blueprint()` or `attach_blueprints()` so drake can run the -needed tasks. +Once all blueprints are defined, add them to your `_targets.R` pipeline +file: ``` r -library(magrittr) -library(drake) +# _targets.R +library(targts) +library(blueprintr) -plan_from_blueprint(blueprint1) %>% - attach_blueprint(blueprint2) +list( + # ... Other steps ... + tar_blueprints() +) ``` -drake handles the code execution based on the targets generated by +targets handles the code execution based on the steps generated by blueprintr. ## Installation -As blueprintr is not yet on CRAN, you must install the package from this -repository: +Stable versions of blueprintr can be installed from Global TIES’ +r-universe: + +``` r +install.packages("blueprintr", repos = "https://nyuglobalties.r-universe.dev") +``` + +Development versions can be installed from this repository: ``` r install.packages("remotes")