About

Hello world! Are you a researcher working primarily using Stata? Have you ever:

Gotten a headache working with cross-platform (e.g. Windows vs Mac OS)?
Tried to reproduce a code published by other researchers but it doesn't work out on your machine?
Overwritten your codes and data (after years of sweat and blood!) using another platform (e.g. Dropbox, Onedrive)?
All of the above?

Imagine that you can avoid all of that. And that's what this repository is aiming for!

Potential use cases

In addition to solving the problems above, you can benefit from this repository in some of the following ways:

Producing regression tables on LaTeX without having to install the distribution on your local machine—which can be pain in the neck
Running unit tests if you're building a Stata package. This is something that I find lacking compared to other open source statistical packages (Julia/R/Python)

Workflows

You need to have a do-file named main.do in your root directory. This file will trigger all of your workflows, e.g. from data cleaning, data analysis, data visualizations, to creating regression tables to LaTeX. For the latter part, we can also compile the tex file into pdf using GitHub Actions, which is totally cool!

Since Stata has user-written packages that users may have not installed on their machine, it sometimes can be a cause of an error. Hence, it may be a good practice to run the following code in the beginning of your main.do file:

clear

// list packages that we may want to install
local packages = "unique reghdfe ritest estout ivreghdfe ftools ivreg2" // just for example

foreach i of local packages {
	capture which `i'
	if _rc != 0 {
		display _rc
		ssc install `i', replace
	}
}

Does it really work to your paper?

Yes! Check out this paper from Charlie Rafkin, Advik Shreekumar, and Pierre-Luc Vautrey, where I clone their repository and run the corresponding Stata do-files (not the R code since it's about Stata workflow) in my main.do (see lines 20-50)

What you need

I hope that you are using a legitimate Stata license code because in order to run Stata do-file using GitHub Actions you need:

Serial number
Code
Authorization

How to run?

You can download the source code from here. Make sure to choose the latest version available. Then, you can create your own repository on GitHub. Before going any further, you need to add GitHub Secrets on Settings -> Secrets tab inside your repository. Note that only you can see these environment variables unless you make them public (but don't!). Though I make this package, I can not see them either. What you need are the following:

ACCESS_TOKEN: you need a token that authorizes GitHub to make any git commit on behalf your account. Read here for details
AUTHORIZATION: given by Stata
CODE: given by Stata
EMAIL: your GitHub email for git configuration (git config --global user.email). See here
FIRST_NAME: your Stata first name
LAST_NAME: your Stata last name
SERIAL_NUMBER: given by Stata
STATA_EDITION: your Stata edition (BE/IC, SE, or MP). The choices that you can fill are either stata, stata-se, or stata-mp. Using different edition than your purchase will cause an error to the program
URL: the URL to download Stata file. Choose Linux installer from Stata. Then save it on other place. I'm using Dropbox because the file size is too big to be stored inside this repository. Also, I don't want to pirate a proprietary software which can bring me into a problem
USERNAME: your GitHub username for git configuration (git config --global user.name). See here
VERSION: your Stata version (I use 15)

That's it! Then you can go to Actions tab and just click Run workflow and voila! You've just run a Stata do-file using GitHub's owned machine. 😀

Considerations

You may need to modify the workflow configurations if:

Your data exceeds file size limit set by GitHub (50 MB) and hence you store your data on Dropbox. Possible solution: modify the configuration to download your data by adding wget [FILE_URL] line before running the do-file
Your data is inside a database (e.g. SQL database like MySQL or PostgreSQL), then you may want to install the database on the command line
There's a possibility that your runner will be stopped automatically by GitHub Actions if it runs out of memory. In one of my private repositories, I had encountered the following error message: ##[warning]You are running out of disk space. The runner will stop working when the machine runs out of disk space. Free space left: 0 MB. Case in point: it's a GIS-related program
You have complex do-files that require more configurations in the LaTeX files (e.g. installing packages, font set-up, etc)

Awesome Stata practices

Resources for us to learn (and me particularly) for Stata best practices.

Blog

American Economic Association's Data Editor
Asjad Naqvi's The Stata Guide
Julian Reif's Stata Coding Guide

Twitter thread

AEA Data Editor on file path

Limitations

This is not a perfect solution to your Stata workflow for several reasons:

If you have an older Stata version, you may face issues running other people's codes from newer Stata version. Case in point: I tried to replicate Scott Cunningham's Mixtape book, but one of his do-files contains a package named parmest. I'm using Stata 15, and it resulted to the following error: this is version 15.1 of Stata; it cannot run version 16.0 programs
If you have Stata IC (which I'm using) not MP, then you may face several difficulties that you can see here when running other people's codes

P.S.

Don't hesitate to reach me out for further questions or send issues here. Read GitHub Actions Documentation for further details.

ledwindra/continuous-integration-stata