FAQ

What kind of files can I upload?¶

Currently, anything that the Python zipfile or Python tarfile functions can handle. Generically, this means

ZIP files (.zip)
TAR files (.tar, .tar.gz, .tgz, .tar.bz2, .tar.xz)

If you need a particular format, feel free to reach out to us.

How does this run my code?¶

Stata

MATLAB

For R, the system first tries to identify the working directory that R should be run from. The system searches for renv.lock, and uses that directory as the working directory. Failing that, it defines the path to (MAIN_FILE) as the working directory. It then runs

cd (WORKING_DIRECTORY)
/usr/local/bin/R --no-save --no-restore -f (MAIN_FILE)

For MATLAB, the system always assumes that the directory containing the (MAIN_FILE) is the working directory. It then runs

cd (WORKING_DIRECTORY)
/usr/local/bin/matlab -batch "(MAIN_FILE_WITHOUT_.M_EXTENSION)"

Stripping .m is done automatically, you should not omit it from your main file name.

How do I know a job failed?¶

When a job fails to run, you will see a notice in the job status page:

You should inspect the Run output log and Run error log files to see what went wrong. When a job fails, no Replicated Package is produced.

What are all these output files?¶

SIVACOR produces six output files:

A replicated package as a ZIP file. This contains all the original files, and the output files generated by SIVACOR.
A run output log and a run error log. Ideally the latter is an empty file, but it contains all the error messages the software may have produced. For packages like Stata, these are more likely included in the run output log.

A few TRACE-related files are produced that can be used by others to verify that the files (figures, tables) were truly produced by this system.

A TRO Declaration file. It describes the various states of the process, and describes the files present at each step. On SIVACOR, this is relatively straightforward, but it can grow more complicated.
A TRS Signature file. This is a text file that contains a cryptographic signature of the results, which can be used to verify that the results have not been altered.
A trusted timestamp file. This file contains a timestamp that is certified by a trusted time server, used in the signing process.

These three files are also included in the tro folder inside the replication package.

What can I do with the TRO files? How can I check the package?¶

There are two levels of verification possible:

whether the TRO Declaration has been modified.
whether some or all of the arrangements correspond to the files you downloaded.

Both of these checks can be done with the Python tro-utils package.

Installing tro-utils

You can install tro-utils via pip:

pip install tro-utils

pipx install tro-utils

Verifying the integrity of the TRO Declaration

You can verify that the TRO Declaration has not been modified since it was signed by running:

tro-utils verify-timestamp /path/to/tro/(UUID).jsonld

which might yield something like this:

> tro-utils verify-timestamp tro/tro-696d3b46adffb76fef0d83bc.jsonld 
Using configuration from /etc/ssl/openssl.cnf
Warning: certificate from '/tmp/tmpuw0g59lb' with subject '/O=Free TSA/OU=TSA/description=This certificate digitally signs documents and time stamp requests made using the freetsa.org online services/CN=www.freetsa.org/emailAddress=busilezas@gmail.com/L=Wuerzburg/C=DE/ST=Bayern' is not a CA cert
Verification: OK

It is OK to ignore the warning, the important part is the Verification: OK line.

Verifying the arrangements

You can verify that the arrangements in the TRO Declaration correspond to the files you downloaded by running:

tro-utils verify-package path/to/tro/(UUID).jsonld path/to/files

For instance, in the standard SIVACOR download, the following will generically work

> tro-utils verify-package tro/tro-\*.jsonld project/

yielding

Verifying that arrangement 'arrangement/0' matches package contents of 'project/' ✗
Verifying that arrangement 'arrangement/1' matches package contents of 'project/' ✓

This indicates that there are two arrangements (0 and 1) recorded in the package, but only arrangement 1 matches the files in the project/ folder, presumably because some files were either modified, added, or deleted from arrangement 0. In the context of SIVACOR, arrangement 0 are the files you uploaded.

It’s failing on a file, but the file is there!¶

Actually, the file may not be called exactly the same thing. The containers used by SIVACOR are based on Linux, and Linux uses a case-sensitive file system. So if your main file is called Main.do, or Main.DO, that is not the same as main.do. The same applies for any files written or read by Stata or R: Reading from data/raw/gs4.csv is not the same as reading from data/Raw/GS4.csv.

What do I set my working directory to for this to work?¶

We often hear from authors

The person who wants to replicate our files has to set their own path.

and see code like

cd "C:\Users\username\Documents\project"

setwd("C:/Users/username/Documents/project")

You must avoid this for SIVACOR to work. You should use relative paths throughout, and if setting a path, do it once, dynamically.

Stata

You can set the working directory to the directory of the main do-file by including this code at the top of your main do-file:

global rootdir : pwd

and then either

cd "$rootdir"
use "data/mydata.dta", clear
save "output/results.dta", replace

or (better) use fully-qualified full paths that use $rootdir, e.g.,

use "$rootdir/data/mydata.dta", clear
save "$rootdir/output/results.dta", replace

References

https://larsvilhuber.github.io/self-checking-reproducibility/02-hands_off_running.html#creating-a-main-or-master-script

In R, you should use one of several options to set the working directory dynamically. For instance, you can use the here package:

library(here)
setwd(here::here())

which will look for certain files (like .here) to determine the project root. Alternatively, you can use the rprojroot package:

library(rprojroot)
setwd(rprojroot::find_root(rprojroot::is_rstudio_project))

Better: use fully qualified paths downstream from the definition of a rootdir variable:

rootdir <- here::here()
# alternatively:
# rootdir <- rprojroot::find_root(rprojroot::is_rstudio_project())
data <- read.csv(file.path(rootdir, "data", "mydata.csv"))
write.csv(results, file.path(rootdir, "output", "results.csv"))

References

Stata errors¶

`r(601)`¶

This is a file-not found error. There are two reasons for this:

you did not include the file in your uploaded package
you included a file that is similarly named, but has different capitalization. Ensure that your code uses naming that matches exactly the files you included, including upper/lower case.

R errors¶

`rJava`¶

Due to the way the containers are set up, it is currently not possible to use Java-related packages. The typical error message will be

Error: package or namespace load failed for ‘rJava’:
 .onLoad failed in loadNamespace() for 'rJava', details:
  call: dyn.load(file, DLLpath = DLLpath, ...)
  error: unable to load shared object '/tmp/workspace-6964fac0d696fbdb1d66ce2c/R/library/rJava/libs/rJava.so':
  libjvm.so: cannot open shared object file: No such file or directory

Issue: SIVACOR/sivacor-repo-choice#3

What do I do with the replicated package that I can download?¶

You can upload it directly to the journal submission system! For instance, in the case of the American Economic Association, simply import the ZIP file into the AEA’s Data and Code Repository (see instructions).

The system appears to be down.¶

SIVACOR runs on Jetstream 2. If Jetstream 2 is down for maintenance, SIVACOR will be down as well. You can check the Jetstream 2 status page for any ongoing maintenance or issues.

If JetStream 2 is operational, but SIVACOR appears down, please contact us via the email at the bottom of this page.