Use a single software application per step¶
Each step of a SIVACOR submission only supports a single software application (Stata, R, MATLAB/Dynare or Julia — see Available Software). For each such step, you need a separate controller script, and configure separate steps, which you chain together in a highly simplified workflow system at submission, see instructions in Step 2. Your package should include the complete code for multiple applications.
Additional information
The single-application requirement means you cannot call one application from another (e.g., call R from Stata). If your code iterates frequently between applications, for instance in a loop, it is also not recommended to use this system. It can, however, be used when a small number of actions are needed in one software application, with the bulk in a main application. For instance, if you use Stata for data preparation, but R for all remaining analysis.
Do not include any data that you are not allowed to upload to third-party systems¶
As a reminder, do not include data that you are not allowed to process on SIVACOR.
Excluding files from final package¶
Identify the files that you cannot publish, due to legal, ethical, or practical reasons. Prepare the .sivacorignore (note the leading dot!) file. It must be at the root of your project. This will be logged as part of the TRO, so it will be clear which files were removed.
Pruning happens after your code has run.
The last step before the package is signed removes the identified files. An ignored file is present while your code runs. This allows you to read restricted input data during the run, but keep it out of the package you publish.
You should limit removal to files that you are not allowed to publish.
A data editor or future reader might not accept the package if you remove files that should and could have been included.
Example file and usage
See the tutorial on removing data with .sivacorignore for an example file and usage.
Your replication package should be portable.¶
Code must run without manual intervention, use a single controller script (e.g., main.do or master.R) per step, and omit hard-coded absolute paths. File and directory paths are case-sensitive, and should use OS-neutral path separators (/, not \).
All dependencies must either be included or installed automatically.¶
If your code uses libraries or packages, you must ensure that they are installed automatically (for Stata, we suggest you include them). We strongly encourage packages that use “environments”, and packages to manage dependencies.
Details
Possible approaches include renv or packrat.[1] You can also include code at the top of your main R script to install any required packages that are not already installed. All code necessary to manage dependencies must be part of the replication package, and must run unattended. For instance, if using renv, include the .Rprofile and ensure that renv::restore() is called at the start of your main R script.
Do not use a hard-coded CRAN mirror
Do not define a CRAN archive (e.g., https://cloud.r-project.org) in your replication package.
While on your computer, R installations may balk when you don’t interactively select a CRAN mirror, the SIVACOR R environments have a pre-defined CRAN mirror. See renv documentation for details.
Example code
install.packages("renv") # only once
renv::init() # only once per project
renv::snapshot() # only once per project, after all packages are installed. You should choose to install all packages detected, then snapshotting.
renv::status() # to check statusThis will create a file renv.lock in the top-level directory of your project.
Adding to replication package
The following files should be included in your replication package:
.Rprofile
renv.lock
renv/activate.R
renv/settings.jsonSee the Tutorial for Stata Packages for instructions on how you can include Stata packages reproducibly. Other guidance can be found at the AEA Data Editor’s site, the World Bank’s repado, the Self Checking Reproducibility tutorial and Julian Reif’s Stata Coding Guide.
Note that even when you include Stata packages, you should provide the script that originally installed them, to demonstrate provenance.
Include a Project.toml and Manifest.toml.
Declare your dependencies in a Project.toml.
The Manifest.toml, if present, will ensure that the code will install and use the same versions. Without it, Project.toml will install latest versions of the dependencies.
Both can be generated by “activating” your project, and then interactively adding your dependencies:
julia --project=.
julia> ] # enter the package REPL
(YourProject) pkg> add DataFrames CSV GLMWhen running, include a setup.jl as your first workflow step (suggested), or include it in your main file:
using Pkg
Pkg.instantiate()Alternatively, use an install.jl to programmatically install your dependencies.
julia --project=.
julia> include("install.jl")where
# Install project dependencies
using Pkg
Pkg.add("DataFrames")
Pkg.add("CSV")
Pkg.add("GLM")Include Project.toml and Manifest.toml, as well as setup.jl or install.jl if present, next to your main file, or at the top of your package.
Minimal sample code
Sample code for Stata (any version), Scenario B: https://
github .com /SIVACOR /sivacor -test -stata Sample code for Stata (any version), Scenario A (
main.doin a non-root directory): https://github .com /SIVACOR /sivacor -test -stata /tree /scenario-A Sample code for R (set up for R 4.3.1, tested on R 4.5.1): https://
github .com /SIVACOR /sivacor -test-r Sample code for MATLAB with and without use of Dynare: https://
github .com /SIVACOR /sivacor -test -matlab (both use the same dynare/dynaresoftware environment).Sample code for Julia (any version): https://
github .com /SIVACOR /sivacor -test -julia
Package fits on the SIVACOR workers¶
You have verified that the replication package fits within the resource constraints of SIVACOR. A run is stopped if the worker runs out of disk space, see the FAQ.
Prepare a ZIP or tar.gz file¶
Your replication package must be a single ZIP file or tar.gz file.
The next step is to upload your package to SIVACOR.
ℹ️ FAQ¶
See the FAQ.