Create new report, starting from a template. Orderly comes with a set of templates, but projects can bring their own templates; see Details below for how these are configured and discovered by orderly.
Arguments
- name
Name of the new report (will be a directory name).
- root
The path to an orderly root directory, or
NULL(the default) to search for one from the current working directory iflocateisTRUE.- locate
Logical, indicating if the configuration should be searched for. If
TRUEandconfigis not given, then orderly looks in the working directory and up through its parents until it finds anorderly_config.ymlfile.- quiet
Logical, indicating if informational messages should be suppressed.
- template
The name of a template. If
NULLorderly will search for a template (see Details). If given it must be the name of a directory within a directorytemplatein your project root. The special label "orderly" will use orderly's builtin template.
Details
To create a custom template, create a directory template
within your orderly root. Within that directory create
directories containing all the files that you would like a report
to contain. This must contain a file
orderly.yml but may contain further files (for example, you
might want a default script and Rmd file).
If template is not given (i.e., is NULL) then we
look for a template called default (i.e., stored at
template/default), then fall back on the system orderly
template.
We first look for a file orderly/template.yml within the
orderly root. If that is not found, then a copy from the orderly
package is used. This can always be used by using template = "system".
See also
orderly_init() for initialising a new orderly
repository.
Examples
path <- orderly::orderly_example("minimal")
# Create a new report with the name "myreport" in this orderly
# repository:
orderly::orderly_new("myreport", root = path)
#> Created report at '/tmp/RtmpGRuIRx/file4747b2deef/src/myreport'
#> Edit the file 'orderly.yml' within this directory
# The directory will be initialised with a orderly.yml file
# containing documentation
dir(file.path(path, "src", "myreport"))
#> [1] "orderly.yml"
readLines(file.path(path, "src", "myreport", "orderly.yml"))
#> [1] "# This is an example orderly configuration file - edit it to suit your"
#> [2] "# needs. The fields \"script\" and \"artefacts\" are the only"
#> [3] "# ones required (plus whatever your project lists in the root"
#> [4] "# configuration) so they are listed first here. After that optional"
#> [5] "# fields are listed. The order does not matter so reorder to suit"
#> [6] "# yourself."
#> [7] "#"
#> [8] "# The \"data\" section will typically contain one or more fields with"
#> [9] "# the name corresponding to an R object you want and the value"
#> [10] "# corresponding to the SQL query to pull that data from the database."
#> [11] "# You can use a filename instead of an inline query. Run queries to"
#> [12] "# multiple lines using the `>-` yaml syntax."
#> [13] "#"
#> [14] "# data:"
#> [15] "# dat: SELECT field1, field2 FROM table"
#> [16] "# more: >-"
#> [17] "# SELECT field1, field2"
#> [18] "# FROM table1 JOIN table2"
#> [19] "# ON table1.id = table2.fk"
#> [20] "# another: from_file.sql"
#> [21] "#"
#> [22] "# If you are writing a report that uses only artefacts from other"
#> [23] "# reports, you can omit this field."
#> [24] ""
#> [25] "# You must have a script that does something with the data. This"
#> [26] "# will be a single string and the filename must exist when orderly is"
#> [27] "# run"
#> [28] "script: ~"
#> [29] ""
#> [30] "# You must list at least one artefact that your report will generate."
#> [31] "# Each artefact consists of one or more files. The format is to list"
#> [32] "# the \"type\" of an artefact (staticgraph, interactivegraph, data,"
#> [33] "# report), then below that a description (free text) and then a"
#> [34] "# filename as either a single file or an array of files"
#> [35] "#"
#> [36] "# artefacts:"
#> [37] "# - staticgraph:"
#> [38] "# description: A graph of things"
#> [39] "# filenames: mygraph.png"
#> [40] "# - report:"
#> [41] "# description: A complex report"
#> [42] "# filenames:"
#> [43] "# - report.html"
#> [44] "# - figures/fig1.png"
#> [45] "# - figures/fig2.png"
#> [46] "artefacts: ~"
#> [47] ""
#> [48] "# An optional name to describe the report in more detail than its"
#> [49] "# directory name (which must be short) but less detail than"
#> [50] "# \"description\" (which can be as long as you want). Must be a string."
#> [51] "#"
#> [52] "# displayname:"
#> [53] ""
#> [54] "# An optional free-text description to decsribe the report in as much"
#> [55] "# detail as you want. Must be a string. The yaml `>-` or `|` syntax"
#> [56] "# might be useful for long descriptions."
#> [57] "#"
#> [58] "# description:"
#> [59] ""
#> [60] "# Optional parameters to the report. These will be substituted into"
#> [61] "# the SQL queries. For example:"
#> [62] "#"
#> [63] "# parameters:"
#> [64] "# a:"
#> [65] "# default: 1"
#> [66] "# b: ~"
#> [67] "#"
#> [68] "# would declare a parameter called 'a' with a default value of 1, and"
#> [69] "# a parameter of b with no default."
#> [70] "#"
#> [71] "# parameters:"
#> [72] ""
#> [73] "# Similar to \"data\" but sets of temporary views before the data are"
#> [74] "# extracted. Can be embedded SQL strings or filenames to actual"
#> [75] "# queries. Use this to simplify the extraction."
#> [76] "#"
#> [77] "# views:"
#> [78] ""
#> [79] "# Packages that should be loaded before the script is run. Use this"
#> [80] "# in preference to explicit library() calls in your script because it"
#> [81] "# will make it easier to provision containers to run the orderly"
#> [82] "# reports."
#> [83] "#"
#> [84] "# packages:"
#> [85] ""
#> [86] "# Source files, in addition to the script. Typically these will"
#> [87] "# contain function definitions. These will be sourced after loading"
#> [88] "# any packages, and before running your script. Use this in"
#> [89] "# preference to explicit source() calls in your script because"
#> [90] "# otherwise you will have to add them to \"resources\" (see below)"
#> [91] "#"
#> [92] "# sources:"
#> [93] ""
#> [94] "# Resources that the script needs to run; this is an array of strings"
#> [95] "# representing filenames *relative to, and below, this directory*."
#> [96] "# These will be copied into place when the script is run, and again"
#> [97] "# when commiting the report. If you require a file and do not list it"
#> [98] "# here, your script will fail! (That's a good thing because we find"
#> [99] "# out what your script actually needed immediately). You do not need"
#> [100] "# to list files already listed in \"sources\" here, or any .sql files"
#> [101] "# referenced in \"views\" or \"data\""
#> [102] "#"
#> [103] "# resources:"
#> [104] ""
#> [105] "# Optional name of a variable to make the SQL connection available to"
#> [106] "# the script. Use this with care and avoid using any queries that"
#> [107] "# modify the database (i.e., use DBI::dbGetQuery with \"SELECT\" queries"
#> [108] "# *only*. Must be a string."
#> [109] "#"
#> [110] "# connection:"
#> [111] ""
#> [112] "# Indicate which reports your report depends on. You can use this to"
#> [113] "# pull in artefacts from previous reports. You can depend in multiple"
#> [114] "# reports. The format looks like this:"
#> [115] "#"
#> [116] "# depends:"
#> [117] "# other_report_name:"
#> [118] "# id: (identifier, possibly \"latest\")"
#> [119] "# use: (mapping of filenames in the format dest: from)"
#> [120] ""
#> [121] "# For example, to depend on the latest version of report"
#> [122] "# 'other-report', pulling in 'data.csv' as 'other-data.csv' you might"
#> [123] "# use:"
#> [124] "#"
#> [125] "# depends:"
#> [126] "# other-report:"
#> [127] "# id: latest"
#> [128] "# use:"
#> [129] "# other-data.csv: data.csv"
#> [130] "#"
#> [131] "# depends:"