initialize_project() initializes a new R project. It sets up folder
locations and sources code files. It creates a standardized project
structure with separate locations for code, results, and data. It organizes
results by date automatically, and it can source code from the directories
you specify.
Usage
initialize_project(
env = new.env(),
home = NULL,
results = NULL,
folders_to_be_sourced = "R",
max_loc_per_file = Inf,
install_missing_packages = FALSE,
source_folders_absolute = FALSE,
encode_from = "UTF-8",
encode_to = "latin1",
results_subfolder = NULL,
...
)Arguments
- env
The environment that
initialize_project()sources the code into. Use.GlobalEnvto source code into the global environment. If you provide a different environment, all functions are sourced into that environment.- home
The folder containing 'Run.R' and 'R/'. This is the main project directory. A relative path, for example
"."or"./analysis", is relative to the working directory.- results
The base folder for storing results.
initialize_project()creates a subfolder with today's date, or the subfolder thatresults_subfoldernames. You reach it atorg::project$results_today.- folders_to_be_sourced
Character vector of folder names inside
home. These folders hold the .R files to source into the environment.- max_loc_per_file
The maximum number of code lines a single .R file in
folders_to_be_sourcedmay hold.initialize_project()stops with an error naming every file above the limit, before it sources any of them. A code line is a physical line that is neither blank nor entirely a comment, as counted byloc_per_file(). Default isInf, which checks nothing.- install_missing_packages
If
TRUE,initialize_project()scansfolders_to_be_sourcedfor package dependencies. It looks forlibrary(),require(), andpkg::usage. It then installs any missing package withpakbefore it sources the code. Ifpakis not available, it falls back toinstall.packages(). Default isFALSE.- source_folders_absolute
If
TRUE,initialize_project()treatsfolders_to_be_sourcedas absolute paths. IfFALSE, the paths are relative tohome.- encode_from
Source encoding for file paths (only used on Windows).
- encode_to
Target encoding for file paths (only used on Windows).
- results_subfolder
NULL, or one relative path insideresults, for example"v01"or"null/sim_0003". If you give it,initialize_project()creates<results>/<results_subfolder>/and setsresults_todayto that folder. It then creates no folder with today's date. The path MUST NOT be absolute and MUST NOT contain.., andresultsMUST also be given. The default,NULL, gives the folder with today's date.- ...
Additional named arguments for other project folders (e.g., data, raw, etc.).
Value
An environment containing:
All folder locations as named elements.
$env: The environment that the code was sourced into.$results_today: Path to today's results folder, or to the folder thatresults_subfoldernames.
Details
initialize_project() performs the seven operations below, in this order.
Creates necessary directories if they do not exist.
Sets up date-based results organization, or the named folder that
results_subfoldergives. It deletes each empty folder inresultswhose name holds aYYYY-MM-DDdate. It keeps today's folder and the folder of the current run.Handles path encoding for cross-platform compatibility.
Stops if any file holds more code lines than
max_loc_per_file.Stops if a package the code needs is missing, or installs it when
install_missing_packagesisTRUE.Sources all .R files from the specified directories, in the order that the section "Sourcing order" gives.
Maintains a mirror of settings in
org::project.
Sourcing order
initialize_project() sources the folders in the order of
folders_to_be_sourced. In each folder, it sources the .R files in the
order of their file names. The locale does not change this order.
The rule compares two names character by character, and it ignores case:
The space and the ASCII punctuation come first, in this order: the space, then
_-,;:!?.'"()[]{}@*/\&#%`^+<=>|~$.The digits come next, from
0to9.The letters come next, from
atoz.A character that is not ASCII comes last, in the order of its UTF-8 bytes.
If two names are equal when case is ignored, the name with a lower case
letter at the first difference comes first. A name that is the start of a
longer name comes first. For example, _cfg.R, 01_data.R, get_data.R,
get.R, Get.R and plot.R are sourced in that order.
For names of ASCII characters, the rule gives the order that R 4.6.0 with
ICU gives under the en_US.UTF-8 locale.
See also
vignette("org") for the recommended project layout. Its "Team
collaboration" section shows how to give one folder several possible
paths.
Other project setup:
project,
set_results(),
sort_for_sourcing()
Examples
# A minimal project: a home folder holding an R/ folder of functions
home <- file.path(tempdir(), "org_init_example", "analysis3")
dir.create(file.path(home, "R"), recursive = TRUE, showWarnings = FALSE)
writeLines("greet <- function() 'hello'", file.path(home, "R", "greet.R"))
proj <- org::initialize_project(
home = home,
results = file.path(tempdir(), "org_init_example", "results"),
raw = file.path(tempdir(), "org_init_example", "raw")
)
#> You are NOT sourcing into .GlobalEnv. All functions will be sourced into an environment that is returned from this function.
#> Sourcing all code inside /tmp/RtmpGLbeQp/org_init_example/analysis3/R into
# Folder locations, both on the returned environment and on org::project
proj$results_today # Today's results folder
#> [1] "/tmp/RtmpGLbeQp/org_init_example/results/2026-11-17/"
proj$raw # Raw data folder
#> [1] "/tmp/RtmpGLbeQp/org_init_example/raw/"
org::project$results_today
#> [1] "/tmp/RtmpGLbeQp/org_init_example/results/2026-11-17/"
# Everything in home/R/ has been sourced into `env`
proj$env$greet()
#> [1] "hello"
# A named results folder instead of a dated one
proj <- org::initialize_project(
home = home,
results = file.path(tempdir(), "org_init_example", "results"),
results_subfolder = "v01"
)
#> You are NOT sourcing into .GlobalEnv. All functions will be sourced into an environment that is returned from this function.
#> Sourcing all code inside /tmp/RtmpGLbeQp/org_init_example/analysis3/R into
proj$results_today
#> [1] "/tmp/RtmpGLbeQp/org_init_example/results/v01/"
unlink(file.path(tempdir(), "org_init_example"), recursive = TRUE)
