Getting Started

Here, we first describe in Preparing your system how you need to set up your computer so that everything plays well together. In dialogue, you will find detailed explanations on what you may want to choose when configuring the templates for your needs. Once you are done with that, you may want to check the Tips and tricks for starting a new project or Suggestions for porting an existing project.

So, …

Preparing your system

  1. Make sure you have the following programs installed and that these can be found on your path. This template requires

  1. If you are on Windows, please open the Windows Powershell. On Mac or Linux, open a terminal. As everything will be started from the Powershell/Terminal, you need to make sure that all programmes you need in your project (for sure Anaconda Python, Git, and LaTeX; potentially VS Code, Stata, R, Matlab) can be found on your PATH. That is, these need to be accessible from your shell. This often requires a bit of manual work, in particular on Windows.

    • To see which programmes can be found in your path, type (leave out the leading dollar sign, this is just standard notation for a command line prompt):

      Windows

      $ echo $env:path

      Mac/Linux

      $ echo $PATH

      This gives you a list of directories that are available on your PATH.

    • Check that this list contains the path to the programs you want to use in your project, in particular, Anaconda (this contains your Python distribution), a LaTeX distribution, the text editor VS Code, Git, and any other program that you need for your project (Stata, R, Matlab). Otherwise add them by looking up their paths on your computer and follow the steps described here PATH environmental variable in Windows or Adding directories to the PATH: MacOS and Linux.

    • If you added any directory to PATH, you need to close and reopen your shell, so that this change is implemented.

    • To be on the safe side regarding your paths, you can check directly whether you can launch the programmes. For Python, type:

      $ python
$ exit()

      This starts python in your shell and exits from it again. The top line should indicate that you are using a Python distribution provided by Anaconda. Here is an example output obtained using Windows PowerShell:

      Python 3.7.4 (default, Aug  9 2019, 18:34:1) [MSC v.1915 64 bit (AMD64)] :: Anaconda, Inc. on win32

    For Git, type:

    $ git status

    Unless you are in a location where you expect a Git repository, this should yield the output:

    fatal: not a git repository (or any of the parent directories): .git

    To start and exit pdflatex.

    $ pdflatex
$ X

    An editor window should open after typing:

    $ code

    If required, do the same for Stata, R, or Matlab — see here for the precise commands you may need.

  2. In the Powershell/Terminal, navigate to the parent folder of your future project.

    Now type pwd, which prints the absolute path to your present working directory. There must not be any spaces or special characters in the path (for instance ä, ü, é, Chinese or Kyrillic characters).

    If you have any spaces or special characters on your path, change to a folder that does not have these special characters (e.g., on Windows, create a directory C:\projects. Do not rename your home directory).

    Type git status, this should yield the output:

    fatal: not a git repository (or any of the parent directories): .git

  3. The template uses cookiecutter to enable personalized installations. Before you start, install cookiecutter on your system.

$ pip install cookiecutter

All additional dependencies will be installed into a newly created conda environment which is installed upon project creation.

Warning

If you do not opt for the conda environment later on, you need to take care of these dependencies by yourself. A list of additional dependencies can be found under dependencies.

  1. If you intend to use a remote Git repository, create it if necessary and hold the URL ready.

Configuring your new project

  1. If you are on Windows, please open the Windows Powershell. On Mac or Linux, open a terminal.

    Navigate to the parent folder of your future project and type (i.e., copy & paste):

$ cookiecutter https://github.com/OpenSourceEconomics/econ-project-templates/archive/v0.5.1.zip

  1. The dialogue will move you through the installation. Make sure to keep this page side-by-side during the process because if something is invalid, the whole process will break off (see When cookiecutter exits with an error on how to recover from there, but no need to push it).

author – Separate multiple authors by commas

email – Just use one in case of multiple authors

affiliation – Separate by commas for multiple authors with different affiliations

project_name – The title of your project as it should appear in papers / presentations. Must not contain underscores or anything that would be an invalid LaTeX title.

project_slug – This will become your project identifier (i.e., the directory will be called this way). The project slug must be a valid Python identifier, i.e., no spaces, hyphens, or the like. Just letters, numbers, underscores. Do not start with a number. There must not be a directory of this name in your current location.

project_short_description* – Briefly describe your project.

python_version – Default is 3.9. Please use python 3.7 or higher.

create_conda_environment_with_name – Just accept the default. If you don’t, the same caveat applies as for the project_slug. If you really do not want a conda environment, type “x”.

set_up_git – Set up a fresh Git repository.

git_remote_url – Paste your remote URL here if applicable.

make_initial_commit – Usually yes.

add_basic_pre_commit_hooks – Choose yes if you are using python. This implements black and some basic checks as pre-commit hooks. Pre-commit hooks run before every commit and prohibit committing before they are resolved. For a full list of pre-commit hooks implemented here take a look at the Pre-Commit Hooks.

add_intrusive_pre_commit – adds flake8 to the pre-commit hooks. flake8 is a python code linting tool. It checks your code for style guide (PEP8) adherence.

example_to_install – This should be the dominant language you will use in your project. A working example will be installed in the language you choose; the easiest way to get going is simply to adjust the examples for your needs.

configure_running_matlab – Select “y” if and only if you intend to use Matlab in your project and the Matlab executable may be found on your path.

configure_running_r – Select “y” if and only if you intend to use R in your project and the R executable may be found on your path.

configure_running_stata – Select “y” if and only if you intend to use Stata in your project and the Stata executable may be found on your path.

python_version – Usually accept the default. Must be a valid Python version 3.6 or higher.

use_biber_biblatex_for_tex_bibliographies – This is a modern replacement for bibtex, but often this does not seem to be stable in MikTeX distributions. Choose yes only if you know what you are doing.

open_source_license – Whatever you prefer.

After successfully answering all the prompts, a folder named according to your project_slug will be created in your current directory. If you run into trouble, please follow the steps explained When cookiecutter exits with an error

  1. Skip this step if you did not opt for the conda environment. Type:

$ conda activate <env_name>

This will activate the newly created conda environment. You have to repeat the last step anytime you want to run your project from a new terminal window.

  1. Skip this step if you did not opt for the pre-commit hooks. Pre-commit have to be installed in order for them to have an effect. This step has to be repeated every time you work on your project on a new machine. To install the pre-commit hooks, navigate to the project’s folder in the shell and type:

$ pre-commit install

  1. Navigate to the folder in the shell and type the following commands into your command line to see whether the examples are working:

$ conda develop .
$ pytask

All programs used within this project template need to be found on your path, see above (Preparing your system and the Frequently Answered Questions / Troubleshooting).

If all went well, you are now ready to adapt the template to your project.

Tips and tricks for starting a new project

Your general strategy should be one of divide and conquer. If you are not used to thinking in computer science / software engineering terms, it will be hard to wrap your head around a lot of the things going on. So write one bit of code at a time, understand what is going on, and move on.

  1. Install the template for the language of your choice as described in dialogue

  2. I suggest you leave the examples in place.

  3. Now add your own data and code bit by bit, append the task_xxx files as necessary. To see what is happening, it might be useful to comment out some steps

  4. Once you got the hang of how things work, remove the examples (both the files and the code in the task_xxx files)

Suggestions for porting an existing project

Your general strategy should be one of divide and conquer. If you are not used to thinking in computer science / software engineering terms, it will be hard to wrap your head around a lot of the things going on. So move one bit of code at a time to the template, understand what is going on, and move on.

  1. Assuming that you use Git, first move all the code in the existing project to a subdirectory called old_code. Commit.

  2. Now set up the templates.

  3. Start with the data management code and move your data files to the spot where they belong under the new structure.

  4. Move (the first steps of) your data management code to the folder under the templates. Modify the task_xxx files accordingly or create new ones.

  5. Run pytask, adjusting the code for the errors you’ll likely see.

  6. Move on step-by-step like this.

  7. Delete the example files and the corresponding sections of the task_xxx files / the entire files in case you created new ones.