# scribe

    library(scribe)

The `{scribe}` package provides a means of defining command line argument inputs for use with the Rscript utility. Users will primarily use the `command_args()` function to capture the command line arguments and initialize a `scribeCommandArgs` object. A `scribeCommandArgs` is a Reference Class object with methods to configure how to parse these arguments for use within R.

Let’s look at to use the `{scribe}` class first. Our goal is to wrap a simple function to generate a sequence of integers or letters. Here we build out a `scribeCommandArgs` object, add a couple of arguments with the `$add_argument()` method, then parse into a named list with `$parse()`.

    ca <- command_args(c("-n", "5", "--method", "numbers"))
    ca$add_argument("-n", default = 1L)
    ca$add_argument("--method", default = "letters")
    args <- ca$parse()

    out <- seq_len(args$n)

    method <- match.arg(args$method, c("letters", "numbers"))
    if (method == "letters") {
      out <- letters[out]
    }

    out
    #> [1] 1 2 3 4 5

In the example above we specify what the command line arguments are within `command_args()`. The intended utility of this is to capture these arguments when passe within an `Rscript` file. Below is the same structure, but as we would expect from within a script intended to be called from a command line. `command_args()` will grab whatever command line arguments are passed to the script.

    #!/usr/bin/env Rscript
    # filename: seq_len.R

    library(scribe)
    ca <- command_args()
    ca$add_argument("-n", default = 1L)
    ca$add_argument("--method", default = "letters")
    args <- ca$parse()

    out <- seq_len(args$n)

    method <- match.arg(args$method, c("letters", "numbers"))
    if (method == "letters") {
      out <- letters[out]
    }

    out

    seq_len.R -n 3
    #> [1] "a" "b" "c"

    seq_len.R -n 3 --method numbers
    #> [1] 1 2 3

One way I like to use `{scribe}` is by passing the values directly to another function via `do.call()`.

Two examples provided that find a specified dataset and then perform something to it. Were I to use this personally, I would probably pass a file path and use a read function first, rather than the `get()` function.

    my_summary <- function(data, levels = 7, sig_figs = 3, q_type = 7) {
      data <- get(data, mode = "list")
      stopifnot(is.data.frame(data))
      summary(data, maxsum = levels, digits = sig_figs, quantile.type = q_type)
    }

    my_model <- function(data, correlation = FALSE) {
      data <- get(data, mode = "list")
      stopifnot(is.data.frame(data))
      form <- stats::DF2formula(data)
      mod <- stats::lm(form, data)
      summary(mod, correlation = correlation)
    }

    ca <- command_args(string = "CO2 --levels 3 --sig-figs 2 --q-type 3")
    ca$add_description("Summarise a dataset")
    ca$add_argument(
      "data",
      info = "Name of the dataset to find"
    )
    ca$add_argument(
      "--levels",
      default = 7L,
      info = "Maximum number of levels shown for factors"
    )
    ca$add_argument(
      "--sig-figs",
      default = 3L,
      info = "Number of significant figures"
    )
    ca$add_argument(
      "--q-type",
      default = 7L,
      info = "Quantile type"
    )
    args <- ca$parse()
    do.call(my_summary, args)
    #>      Plant             Type         Treatment       conc          uptake
    #>  Qn1    : 7   Quebec     :42   nonchilled:42   Min.   :  95   Min.   : 7.7
    #>  Qn2    : 7   Mississippi:42   chilled   :42   1st Qu.: 175   1st Qu.:17.9
    #>  (Other):70                                    Median : 350   Median :28.1
    #>                                                Mean   : 435   Mean   :27.2
    #>                                                3rd Qu.: 675   3rd Qu.:37.1
    #>                                                Max.   :1000   Max.   :45.5

    ca <- command_args(string = "attitude --correlation")
    ca$add_argument(
      "data",
      info = "Name of the dataset to find"
    )
    ca$add_argument(
      "--correlation",
      action = "flag",
      info = "When set, prints the correlation matrix of estimated parameters"
    )
    args <- ca$parse()
    do.call(my_model, args)
    #>
    #> Call:
    #> stats::lm(formula = form, data = data)
    #>
    #> Residuals:
    #>      Min       1Q   Median       3Q      Max
    #> -10.9418  -4.3555   0.3158   5.5425  11.5990
    #>
    #> Coefficients:
    #>             Estimate Std. Error t value Pr(>|t|)
    #> (Intercept) 10.78708   11.58926   0.931 0.361634
    #> complaints   0.61319    0.16098   3.809 0.000903 ***
    #> privileges  -0.07305    0.13572  -0.538 0.595594
    #> learning     0.32033    0.16852   1.901 0.069925 .
    #> raises       0.08173    0.22148   0.369 0.715480
    #> critical     0.03838    0.14700   0.261 0.796334
    #> advance     -0.21706    0.17821  -1.218 0.235577
    #> ---
    #> Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
    #>
    #> Residual standard error: 7.068 on 23 degrees of freedom
    #> Multiple R-squared:  0.7326, Adjusted R-squared:  0.6628
    #> F-statistic:  10.5 on 6 and 23 DF,  p-value: 1.24e-05
    #>
    #> Correlation of Coefficients:
    #>            (Intercept) complaints privileges learning raises critical
    #> complaints -0.07
    #> privileges -0.12       -0.37
    #> learning   -0.16       -0.30      -0.14
    #> raises     -0.08       -0.52       0.08      -0.21
    #> critical   -0.66        0.00      -0.02       0.20    -0.28
    #> advance     0.02        0.40      -0.18      -0.35    -0.43  -0.13