*! version 1.0.0 20aug2023

Title

setroot -- Find the root path of a project and set it as a global variable.

Syntax

setroot,
[global
local
more
search(files_or_folders)
add(filename)
verbose]

global save root folder as global variable $root (default)

local save root folder as local variable `root'

more save additional variables such as $code, $data, etc.

search(...) specify alternative files or folder that will be searched

add(filename) create a file in a working directory

verbose show information of all the files searched.

Description

Use setroot to improve the reproductibility of your research,
by ensuring that all code and files are accessed with respect to
the top-level directory of your project, instead of using hardcoded or relative paths.

setroot first finds the root or top-level folder of your project by searching for common filenames in the working directory.
It then saves this name to the global variable $root, so it can be used to build file paths.
setroot first searches the working directory for a set of filenames,
and then searches any subsequent parent directories until a matching file is found,
stopping with an error if not.

Using this package has two advantages:

1. It ensures your code is portable across computers and coauthors, as it avoids hardcoded paths.
So instead of "C:/Users/John/MyPaper/data/xyz.dta",
you just need to use the string "$root/data/xyz.dta".

2. It makes code less fragile, as it can be moved to subdirectories without the need to change all any relative paths.

findroot is heavily inspired by the here R package and
the Stata package of the same name.

Options

Main

more Will create additional variables, including $code, $data, $input, $output, $log, and $temp in the root folder, and $figures and $tables as subfolders of $output.
These names are based on the suggested folder structure by Data Analysis Using Stata.

local Saves local variables instead of global variables.

search(files_or_folders) Allows you to customize the files or folders that will be searched within the working directory.
By default, the files searched are:
.here .project .git DESCRIPTION LICENSE README.md project.toml manifest.toml pyproject.toml

add(file) Creates an empty filename in the working directory that can be used as a reference in the future..
Recommended usage is setroot, add(.here).

Examples

Template for starting a do-file:

clear all

setroot

To view debug information:

setroot, verbose

Stored results

setroot stores the following in r():

Macros
r(root) root path

Author

Sergio Correia

Board of Governors of the Federal Reserve

Email: sergio.correia@gmail.com

Support and updates

Links to online documentation & code:

- Github page: code repository, issues, etc.

Acknowledgements

This work is heavily based on R's here package, as well as on Miklós Koren's Stata port.
Thank you in advance for bug-spotting and feature suggestions.