Movatterモバイル変換

command: Process command line arguments

Description

Process arguments passed at the command line,as part of data analysis workflow.

Details

• cmd_assign() Process command line arguments

• extract_shell() Turn acmd_assign() call into a shell command

• extract_make() Turn acmd_assign() call into a Makefile rule

• shell_script() Create a shell script

• makefile() Create a Makefile

• Quick StartHow to usecmd_assign()

• Modular Workflows for Data AnalysisSafe, flexible data analysis workflows

Author(s)

Maintainer: John Bryantjohn@bayesiandemography.com

Other contributors:

• Bayesian Demography Limited [copyright holder]

See Also

Useful links:

• https://bayesiandemography.github.io/command/

• https://github.com/bayesiandemography/command

• Report bugs athttps://github.com/bayesiandemography/command/issues

Assign Values Passed at the Command Line or Interactively

Description

Assign values to names in the working environment.The values are typically supplied through the command line,but can be supplied interactively.

Specifying the inputs and outputs of scripts through thecommand line can contribute to safter, more modularworkflows.

cmd_assign_quiet() is identical tocmd_assign(),but does not print progress messages to the console.

Usage

cmd_assign(...)cmd_assign_quiet(...)

Arguments

Value

cmd_assign() is calledfor its side effect, which is to create objectsin the global environment. However,cmd_assign()also invisibly returns a named list of objects.

Types of session

cmd_assign() behaves differently dependingon how it whether it is called

1. interactively, or

2. inside an R script that is run from the command line.

For instance, if the code

cmd_assign(use_log = TRUE)

is run interactively, it creates an objectcalleduse_log with valueTRUE.

But if the same code is run inside ascript via the command

⁠Rscript tidy_data.R --use_log=FALSE⁠

it creates an object calleduse_logwith valueFALSE.

cmd_assign() is typically called interactivelywhen a workflow is being developed,and through the command line when theworkflow has matured.

Matching names and values

When used in a script called from thecommand line,cmd_assign()first matches named command line arguments,and then matches unnamed command line arguments,in the order in which they are supplied.

If, for instance, the scriptperson.R containsthe lines

cmd_assign(.data = "raw_data.csv",           max_age = 85,           .out = "person.rds")

and ifperson.R is run from the command line using

Rscript person.R raw_data.csv person.rds --max_age=100

thencmd_assign() first matches namedcommand line argument--max_age=100 to⁠cmd_assign() argument ⁠max_age⁠, and then matches unnamed command line arguments ⁠raw_data.csvandperson.rdstocmd_assign()arugments.dataand.out'.

Coercing values passed at the command line

Values passed at the command line start out astext strings.cmd_assign() coerces these text stringsto have the same class as the corresponding valuesin the call tocmd_assign(). For instance,if a script calledfit.R containsthe lines

cmd_assign(.data = "cleaned.rds",           impute = TRUE,           date = as.Date("2026-01-01"),           .out = "fit.rds")

and iffitted.R is run from the command line using

Rscript fitted.R cleaned.rds fit.rds --impute=TRUE --date=2025-01-01

thencmd_assign() will create

• a character vector called.data with value "cleaned.rds",

• a logical vector calledimpute with valueTRUE,

• a date vector calleddate with value"2025-01-01", and

• a character vector called.out with value '"fit.rds".

References

• Command-Line ProgramsIntroduction to Rscript

See Also

• extract_shell() Turn acmd_assign() call into a shell command

• extract_make() Turn acmd_assign() call into a Makefile rule

• shell_script() Create a shell script

• makefile() Create a Makefile

• Quick StartHow to usecmd_assign()

• Modular Workflows for Data AnalysisSafe, flexible data analysis workflows.

• Base R functioncommandArgs() uses a more general,lower-level approach to processing command line arguments.(commandArgs() is called internally bycmd_assign().)

• littler Alternative to Rscript

Examples

if (interactive()) {  cmd_assign(.data = "mydata.csv",             n_iter = 2000,             .out = "results.rds")}

Turn a 'cmd_assign' Call Into a Makefile Rule

Description

Extract a call tocmd_assign() from anR script, and turn it into a Makefile rule.

Usage

extract_make(path_file, dir_make = NULL)

Arguments

Value

extract_make() is typically calledfor its side effect, which is to print aMakefile rule. However,extract_make()invisibly returns a text string with the rule.

The components of a Makefile rule

A Makefile rule produced byextract_make()normally looks something like this:

out/model.rds: src/model.R \  data/cleaned.rds       Rscript $^ $@ --use_log=TRUE

In this rule

• out/model.rds is the "target", i.e. the file that the rule creates;

• src/model.R anddata/timeseries.rds are "prerequisites",i.e. files that are used to create the target;

• ⁠\⁠ is a "line continuation character";

• ⁠ ⁠ at the start of the third line is a tab,tellingmake that the recipe for creating the target fromthe starts here;

• Rscript is a call toutils::Rscript();

• ⁠$^⁠ is anautomatic variablemeaning "all the prerequisites"and⁠$@⁠ is an automatic variable meaning "the target",so that⁠Rscript $^ $@⁠ expands to⁠Rscript src/model.R data/cleaned.rds out/model.rds⁠; and

• --use_log=TRUE is a named argument thatRscript passes tosrc/model.R

Usingextract_make() to build a data analysis workflow

• Step 1. Write the R file that carries outthe step in analysis (eg tidying data, fittinga model, making a graph.) This filewill contain a call tocmd_assign(),and will appear in the first line of theMakefile rule. When writing and testing the file,usecmd_assign() interactively.

• Step 2. Once the R file is working correctly,callextract_make(), and add the ruleto your Makefile.

When usingextract_make(), it is a good idea toset the current working directory to the projectdirectory (something that will happen automaticallyif you are using RStudio projects.)

Location of the Makefile

The Makefile normally sets at the top ofthe project, so that theproject folder looks something like this:

Makefile- data/- src/- out/report.qmd

Identifying file arguments

To construct the Makefile rule,extract_make() needs tobe able to pick out arguments that refer tofile names. To do so, it uses the following heuristic:

• if the call includes arguments whose names start witha dot, then these arguments are assumed torefer to file names;

• otherwise, find arguments whose valuesactually are file names(as determined byfile.exists()), or that looklike they could be.

References

• Project Management with MakeMakefiles in data analysis workflows

• GNU makeDefinitive guide

• Command-Line ProgramsIntroduction to Rscript

See Also

• extract_shell() Shell script equivalent ofextract_make()

• makefile() Create a Makefilefrom calls tocmd_assign()

• cmd_assign() Process command line arguments

• Quick StartHow to usecmd_assign()

• Modular Workflows for Data AnalysisSafe, flexible data analysis workflows

• littler Alternative to Rscript

Examples

library(fs)library(withr)with_tempdir({  ## create 'src'  directory  dir_create("src")  ## put an R script containing a call to  ## 'cmd_assign' in the 'src' directory  writeLines(c("cmd_assign(x = 1, .out = 'out/results.rds')",               "results <- x + 1",               "saveRDS(results, file = .out)"),             con = "src/results.R")  ## call 'extract_make()'  extract_make(path_file = "src/results.R",               dir_make = ".")})

Turn a 'cmd_assign' Call Into a Shell Command

Description

Extract a call tocmd_assign() from anR script, and turn it into a shell command.

Usage

extract_shell(path_file, dir_shell = NULL)

Arguments

Value

extract_shell() is typically calledfor its side effect, which is to print ashell command. However,extract_shell()invisibly returns a text string with the command.

The components of a shell command

The shell command produced byextract_shell()normally looks something like this:

Rscript src/model.R \  data/cleaned.rds \  out/model.rds \  --use_log=TRUE

In this command

• Rscript is a call toutils::Rscript();

• ⁠\⁠ is a "line continuation character";

• data/cleaned.rds andout/model.rds are unnamedarguments that Rscript passes tosrc/model.R; and

• --use_log=TRUE is a named argument thatRscript passes tosrc/model.R

Usingextract_shell() to build a data analysis workflow

• Step 1. Write an R script that carries outa step in analysis (eg tidying data, fittinga model, making a graph.) This scriptwill contain a call tocmd_assign(),and will be the first argument passed toRscript in the shell command.When writing and testing the script,usecmd_assign() interactively.

• Step 2. Once the R script is working correctly,callextract_shell(), and add the commandto your shell script.

Location of the shell script

The shell script normally sits at thetop level of the project, so that theproject folder looks something like this:

workflow.sh- data/- src/- out/report.qmd

Identifying file arguments

To construct the rule,extract_shell() needs tobe able to identify arguments that refer to afile name. To do so, it uses the following heuristic:

• if the call includes arguments whose names start witha dot, then these arguments are assumed torefer to file names;

• otherwise, find arguments whose valuesactually are file names(as determined byfile.exists()) or that looklike they could be.

References

• Episodes 1–3 ofThe Unix ShellIntroduction to the command line

• Command-Line ProgramsIntroduction to Rscript

• littler Alternative to Rscript

See Also

• extract_make() Makefile equivalent ofextract_shell()

• shell_script() Create a shell scriptfrom calls tocmd_assign()

• cmd_assign() Process command line arguments

• Quick StartHow to usecmd_assign()

• Modular Workflows for Data AnalysisSafe, flexible data analysis workflows

Examples

library(fs)library(withr)with_tempdir({  ## create 'src' directory  dir_create("src")  ## add an R script containing a call to 'cmd_assign'  writeLines(c("cmd_assign(x = 1, .out = 'out/results.rds')",               "results <- x + 1",               "saveRDS(results, file = .out)"),             con = "src/results.R")  ## call 'extract_shell()'  extract_shell(path_file = "src/results.R",                dir_shell = ".")})

Create a Makefile

Description

Create a Makefile for a data analysis workflow.The Makefile can includerules extracted from existing R files.

Usage

makefile(  path_files = NULL,  dir_make = NULL,  name_make = "Makefile",  overwrite = FALSE,  quiet = FALSE)

Arguments

Details

To create a Makefile in thefilesdirectory, setfiles to".".

To obtain the contents of the Makefilewithout creating a file on disk,creating the file on disk, setname_make toNULL.

Supplying a value forfiles isoptional formakefile(),but compulsory forshell_script().The output frommakefile()includes some general-purpose Makefilecommands, while the output fromshell_script() is generated entirelyfromfiles.

Value

makefile() is called for itsside effect, which is to create afile. However,makefile() alsoreturns a string with the contents of theMakefile.

References

• Project Management with MakeMakefiles in data analysis workflows

• GNU makeDefinitive guide

• Command-Line ProgramsIntroduction to Rscript

See Also

• Creating a MakefileMore onmakefile()

• extract_make() Turn acmd_assign() call into a Makefile rule

• shell_script() Shell script equivalent ofmakefile()

• cmd_assign() Process command line arguments

• Modular Workflows for Data AnalysisSafe, flexible data analysis workflows

• littler Alternative to Rscript

Examples

library(fs)library(withr)with_tempdir({  ## create 'src'  directory  dir_create("src")  ## put R scripts containing calls to  ## 'cmd_assign' in the 'src' directory  writeLines(c("cmd_assign(x = 1, .out = 'out/results.rds')",               "results <- x + 1",               "saveRDS(results, file = .out)"),             con = "src/results.R")  writeLines(c("cmd_assign(x = 1, .out = 'out/more_results.rds')",               "more_results <- x + 2",               "saveRDS(more_results, file = .out)"),             con = "src/more_results.R")  ## call 'makefile()'  makefile(path_files = "src",           dir_make = ".")  ## Makefile has been created  dir_tree()  ## print contents of Makefile  cat(readLines("Makefile"), sep = "\n")})

Create a Shell Script

Description

Create a shell script for a data analysis workflowconsisting of commandsextracted from existing R files.

Usage

shell_script(  path_files,  dir_shell = NULL,  name_shell = "workflow.sh",  overwrite = FALSE,  quiet = FALSE)

Arguments

Details

To create a shell script in thefilesdirectory, setfiles to".".

To obtain the contents of the shell scriptwithout creating a file on disk,creating the file on disk, setname_shell toNULL.

Supplying a value forfiles iscompulsory forshell_script(),but optional formakefile().The output fromshell_script()is generated entirely fromfileswhile the output frommakefile()also includes some general-purpose Makefilecommands.

Value

shell_script() is called for itsside effect, which is to create afile. However,shell_script() alsoreturns a string with the contents of theshell script.

References

• Episodes 1–3 ofThe Unix ShellIntroduction to the command line

• Command-Line ProgramsIntroduction to Rscript

See Also

• Creating a Shell Script More onshell_script()

• extract_shell() Turn acmd_assign() call into a shell command

• makefile() Makefile equivalent ofshell_script()

• cmd_assign() Process command line arguments

• Modular Workflows for Data AnalysisSafe, flexible data analysis workflows

• littler Alternative to Rscript

Examples

library(fs)library(withr)with_tempdir({  ## create 'src'  directory  dir_create("src")  ## put R scripts containing calls to  ## 'cmd_assign' in the 'src' directory  writeLines(c("cmd_assign(x = 1, .out = 'out/results.rds')",               "results <- x + 1",               "saveRDS(results, file = .out)"),             con = "src/results.R")  writeLines(c("cmd_assign(x = 1, .out = 'out/more_results.rds')",               "more_results <- x + 2",               "saveRDS(more_results, file = .out)"),             con = "src/more_results.R")  ## call 'shell_script()'  shell_script(path_files = "src",               dir_shell = ".")  ## shell script has been created  dir_tree()  ## print contents of shell script  cat(readLines("workflow.sh"), sep = "\n")})