Requirements

The following are required :

  • Stata 16.0 or later

  • Python 3.6 or later (3.8 required for some advanced options)

  • SCons 4.3 or later (SCons 4.5 or later requires statacons 3.0.1 or later)

Step 1: Python Setup

We provide the basic steps for installing Python and configuring Stata for use with Python. For more details, we recommend a series of posts by Chuck Huber on the Stata Blog. See especially post 1 and post 3.

Python commands are issued at a command prompt in a terminal window. Exactly which terminal will depend on your operating system and implementation of Python. Some popular examples include

  • Windows

    • Python: Windows Command Prompt ("cmd.exe") or Powershell

    • Anaconda: Anaconda Powershell Prompt or Anaconda Prompt

  • macOS: Terminal

  • Unix-like (e.g., Linux): terminal

Step 1.1: Install Python

Install Python 3.6 or later (3.8 or later recommended).

Step 1.2: Configure Stata to work with Python

Step 1.2.1: Locate Python executable

In Stata, enter

python search

to locate the Python executable. If your system has both Python 2 and Python 3 installed, be sure to use the Python 3 executable.

Step 1.2.2: Set path to Python executable in Stata

Stata will use the default Python, unless configured before first use. To do so, in Stata, enter

python set exec [pyexecutable], permanently

where [pyexecutable] is a path found in Step 1.2.1.

If Stata is started in a specific Anaconda environment, we provide a simple Stata command set_python_exec_env to query the environment and set the Python path accordingly.

Step 1.2.3: check setup

In Stata, check your setup by entering

python query

Step 1.3: Install Python packages scons and pystatacons

pip is the standard way to install Python packages. In the terminal, enter

    pip install scons
    pip install pystatacons
    pip install pywin32

You can confirm in the terminal that these are successfully installed as follows:

    pip show scons
    pip show pystatacons
    pip show pywin32

To check that SCons and pystatacons are recognized by Stata, open Stata and enter

    python which SCons // case-sensitive
    python which pystatacons

Step 2: statacons installation and setup

Step 2.1: Install Stata package

First, check your adopath. By default statacons will be installed to your PLUS directory. Users working in collaboration with others may wish to change the PLUS and PERSONAL directories to be local to the project to ensure that all users are using the same version of statacons and other user-written commands. See profile_template.do included in our project files for what we recommend.

Second, statacons requires both the core program files and a key set of project files. You may wish to install these separately. To install the main program use:

net install statacons, from(https://raw.github.com/bquistorff/statacons/main/)

The core program files are:

    complete_datasignature.ado
    statacons.ado
    stataconsign.ado
    runscons.py
    sconsign-script.py
    sconstruct_fns.py

To check that statacons is installed, enter which statacons in Stata.

Step 2.2: Install project files

To install the project files, navigate to the root of your project directory and then run

// Change to project's root directory
cd path/to/your/project
// set other to the current directory, i.e. project's root directory
net set other .
// get project files
net get statacons, from(https://raw.github.com/bquistorff/statacons/main/)
unzipfile project_files
rm project_files.zip

The project files packages in project_files.zip are

    SConstruct
    config_project.ini
    utils/config_local_template.ini
    utils/profile_template.do
    utils/debugging-checklist_template.do
    utils/.gitignore_template

The only project file required is SConstruct. You may also wish to use the template files; if so, copy them into the main project folder (removing the _template suffix).

Step 2.3: Configuration

statacons is intended to work without additional user configuration, for example by automatically detecting the location of the Stata executable. However, some configuration may be required. For example, if you have more than one version of Stata installed, statacons may not find your preferred version first.

Our default is to use two configuration files, config_project.ini, which sets parameters that are common to all users working on a given project, and config_local.ini, which sets parameters specific to the local user. The files config_project.ini and config_local_template.ini provided with the Stata project files give several examples of how to set commonly-used parameters. See the paper for more information on these configuration files and how to read from them in SConstructs.

The default is that these configuration files, if used, will be stored in the same directory as the SConstruct. The command line option config_file() can instruct SCons to use a custom location or filename instead.

To check the configuration of statacons, enter statacons, show_config in Stata. The do-file debugging-checklist.do included in the utils folder may also be useful in checking that components are in the right places.

Step 2.4 (optional): Setup for Version Control

If you are using version control software such as git, here are a few recommendations:

  • set your ado-path so that statacons and other packages are installed in the project folder. This will ensure that all users have the same version of all ado-files. See profile_template.do in the utils folder

  • files to keep under version control: SConstruct, config_project.ini

  • files to exclude from version control: config_local.ini, all generated files, including SConsign files (e.g., .sconsign.dblite) and batch-generated .log-files. See .gitignore_template in the utils folder for what we recommend.

See the Online Appendix Section B for more details on working with version control.

Step 3: Test run with Introductory Example

Replication code and data for our Introductory Example as well as the extensions to that example are provided in https://github.com/bquistorff/statacons/raw/main/examples/stataconsIntro.zip, posted to our repository. To run the example, unpack the zip archive and follow the steps in Section 2 of the paper.

Updating statacons

To update the statacons Stata package to the latest version, enter the following in Stata:

    net install statacons, from(https://raw.github.com/bquistorff/statacons/main/) force replace

To update the pystatacons Python package to the latest version, enter the following at the appropriate Python prompt:

    pip install --upgrade pystatacons