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 container images). If your replication package requires multiple applications, you will need to configure separate steps. However, your package itself can include the code for multiple applications, and you can chain them together in a highly simplified workflow system at submission, see instructions in Step 2.
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¶
While SIVACOR does not publish data or replication packages, and deletes completed jobs after a short period of time, it is not a designated secure computing system.[1] You should not upload controlled data, and all uploads should be compatible with any data use agreement you signed.
If you have data that you are allowed to upload, but not publish, see “Excluding files” on how to exclude files from the final replication package.
Excluding files from final package¶
The final digitally signed replication package contains all data as originally uploaded. If you need to remove files because you do not have redistribution rights, or large intermediate files, include a file named .sivacorignore (note the leading dot!) at the root of your project to exclude files or directories before package is finalized. This will be logged as part of the TRO.
Example file and usage
The .sivacorignore file follows the same pattern rules as .gitignore, so you can use glob patterns, negations, and directory-specific rules.
For example, to exclude a data/raw/ directory and all .tmp files, the .sivacorignore file would look like this:
data/raw/
*.tmpYour replication package then should look somewhat like this:
data/raw/
file1.csv
code/
main.R
...
.sivacorignorebefore it is run, and might look like this
code/
main.R
output/
figure.png
...
.sivacorignoreafter the run (note removal of data/raw).
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.[2] 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.
Guidance for portable dependencies for Stata is provided at Step 3 of the AEA Data Editor’s guidance. See also the World Bank’s repado.
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/dynarecontainer).Sample code for Julia (any version): https://
github .com /SIVACOR /sivacor -test -julia
Package must be able to fit on the SIVACOR workers¶
The size available to run your code depends on the software being used, and how you manage files within your replication package. A complete run of your code needs room:
the operating system
the statistical software you use
multiple copies of your replication package:
the ZIP file you upload
the workspace it is extracted into
anything your code writes
Current SIVACOR nodes have between 23 and 44 GiB free, depending on the software being used.
Additional information
This instance of SIVACOR launches a virtual machine for each run. Its disk is advertised as 60 GB; once formatted the filesystem measures 58 GiB, which is the figure every number below is in. Of that, about 12.7 GiB is the operating system, Docker and the SIVACOR harness. Roughly 45 GiB are available before the analysis software is added. Software sizes differ a great deal, and the software is unpacked onto the same disk your package lives on.
The table below lists what is left for your package after each one. See Available Software for the full, curated list.
* Estimated from the compressed download size.[3]
For more information on the system itself, see Hardware capabilities.
A run is stopped if the worker runs out of disk space, see the FAQ.
If your package cannot be made to fit the free space in the table above, you may be able to ask for extra scratch disk.
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.
SIVACOR runs on Jetstream2 infrastructure. The JS2 Acceptable Use and Data Policy apply. SIVACOR’s privacy policy can be found at https://
submit .sivacor .org /privacy. The container is kept both compressed and unpacked on the worker’s disk, so it occupies roughly 3.5x what it downloads.