Initialise an orderly store. This is a helper function that automates getting started with using orderly for a new project. It is not required to use - you can create the orderly structure yourself (all that is compulsory is the orderly_config.yml file).

orderly_init(root, doc = TRUE, quiet = FALSE)

Arguments

root

The root of the store; this must be an empty directory or the path of a directory to create

doc

Logical, indicating if documentation should be added to the directories. This also has the (potentially useful) effect of making these directories noticeable by git.

quiet

Logical, indicating if informational messages should be suppressed.

Value

The path to the newly created archive

Details

This function creates a minimal orderly structure, containing:

  • orderly_config.yml: The orderly configuration. Minimally, this can be empty, but it must exist.

  • src: The path where report sources live. This should be placed under version control, and contain a number of reports, each in their own directory with an orderly.yml describing their inputs and outputs (artefacts). The orderly_new() function can be used to accelerate creation of new reports.

  • draft: A directory where reports will be run using orderly_run(). This directory should be excluded from version control. orderly will create it as needed if it does not exist when a report is run.

  • archive: A directory where successfully run reports will be moved to after being committed with orderly_commit(). This directory should be excluded from version control. orderly will create it as needed if it does not exist when a report is committed.

  • data: A directory where data extracted from the database (if used) will be stored. This directory should be excluded from version control. orderly will create it as needed if it does not exist when a report is run.

See also

orderly_new() for creating new reports within a configured orderly repository.

Examples

# Initialise a new orderly repository in an temporary directory:
path <- orderly::orderly_init(tempfile())
#> Now, edit the file 'orderly_config.yml' within '/tmp/RtmpP7mCov/file463630ce29'

# This has created the directory skeleton that you need to get
# started using orderly:
fs::dir_tree(path)
#> /tmp/RtmpP7mCov/file463630ce29
#> ├── README.md
#> ├── archive
#> │   └── README.md
#> ├── data
#> │   └── README.md
#> ├── draft
#> │   └── README.md
#> ├── orderly_config.yml
#> └── src
#>     └── README.md

# As instructed, the next thing to do is to edit the
# orderly_config.yml file to match your needs:
readLines(file.path(path, "orderly_config.yml"))
#>  [1] "# To use external databases, this file must contain the field"          
#>  [2] "# 'database', which contains database configurations, each of which"    
#>  [3] "# must contain a field 'driver' that will be one of RSQLite::SQLite or" 
#>  [4] "# RPostgres::Postgres (other drivers may work too in future, but not"   
#>  [5] "# yet)."                                                                
#>  [6] "#"                                                                      
#>  [7] "# For example, a configuration to use Postgres as the source database"  
#>  [8] "# might look like:"                                                     
#>  [9] "#"                                                                      
#> [10] "#   database:"                                                          
#> [11] "#     source:"                                                          
#> [12] "#       driver: RPostgres::Postgres"                                    
#> [13] "#       args:"                                                          
#> [14] "#         host: localhost"                                              
#> [15] "#         port: 5432"                                                   
#> [16] "#         user: myuser"                                                 
#> [17] "#         dbname: databasename"                                         
#> [18] "#         password: p4ssw0rd"                                           
#> [19] "#"                                                                      
#> [20] "# All arguments in the \"args\" block will be passed through during the"
#> [21] "# 'DBI::dbConnect()' call."                                             
#> [22] "#"                                                                      
#> [23] "# If using SQLite, then the \"dbname\" argument will be interpreted"    
#> [24] "# relative to the orderly root if not absolute .  Be sure to exclude"   
#> [25] "# this path using .gitignore"                                           
#> [26] "#"                                                                      
#> [27] "# Other options accepted by RSQLite are allowed but are much less"      
#> [28] "# commonly useful (as of RSQLite v1.1-2, loadable.extensions,"          
#> [29] "# cache_size, synchronous, flags, vfs)"                                 
#> [30] "database: ~"                                                            
#> [31] ""                                                                       
#> [32] "# It is not necessary to configure a destination driver explicitly"     
#> [33] "# unless you want to change the default (which is into a SQLite"        
#> [34] "# database called \"orderly.sqlite\" at the orderly root.  If you do"   
#> [35] "# specify it, the options are the same as for \"source\", e.g.:"        
#> [36] "#"                                                                      
#> [37] "#   destination:"                                                       
#> [38] "#     driver: RSQLite::SQLite"                                          
#> [39] "#     args:"                                                            
#> [40] "#       dbname: different.sqlite"                                       
#> [41] ""                                                                       
#> [42] "# In addition, it may contain a 'fields' section defining custom"       
#> [43] "# fields, for example:"                                                 
#> [44] "#"                                                                      
#> [45] "#   fields:"                                                            
#> [46] "#     comment:"                                                         
#> [47] "#       required: true"                                                 
#> [48] "#       type: character"                                                
#> [49] "#"                                                                      
#> [50] "# Each field is named, and has two required entries; 'required'"        
#> [51] "# (either false or true) and 'type' (either 'character' or 'numeric')." 
#> [52] "#"                                                                      
#> [53] "# The fields must not clash with built-in field names."                 
#> [54] "fields: ~"