Getting Started#

How to get started depends on what your system looks like. Depending on that, you may want to jump to any of the sections in this part of the documentation:

  • In Preparing your system, we describe what needs to be installed on your computer so that you can use the templates.

  • Should you have done that already for a different project, you can directly go to Customising the template for your needs, which describes the options you have when moving from the template to your specific research project.

  • In case a project has been set up by you or a collaborator and you want to use it on a different machine as well, you will find the explanations on how to do so in How to get started on a second machine.

Once you are set up in this fashion, you may want to read up on the background of the Background. In case you know those already, have a look in Guides and Explanations for guides on starting new projects or porting existing ones.

Preparing your system#

Program installation#

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

Validating the installation paths#

  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, R, Julia, Stata) 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 on 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 (R, Julia, Stata). 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.9.9 | packaged by conda-forge | (main, Dec 20 2021, 02:40:17)
[GCC 9.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.

    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

    If a Git repository is present, delete it or go to another directory before starting cookiecutter below.

    To start and exit pdflatex.

    $ pdflatex
$ X

    An editor window should open after typing:

    $ code

    If required, do the same for R, Julia, or Stata.

Validating Git#

  1. 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 Cyrillic 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

Installing cookiecutter#

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

    Warning

    If you are using conda environments, make sure that you are in the base environment before installing cookiecutter (conda deactivate, possibly multiple times). Else you may get a nested environment later on, this can be annoying.

    $ pip install cookiecutter

    All additional dependencies will be installed into a newly created conda environment 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.

Customising the template for your needs#

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

    1. Navigate to the parent folder of your future project.

    2. If you are using conda environments, make sure that you are in the base environment before proceeding. If in doubt, type conda deactivate, possibly multiple times.

    3. Type (i.e., copy & paste):

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

  2. 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). Note that if you don’t know how to answer a question, it’s usually best to accept the default.

    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_description – Briefly describe your project.

    github_username – Your GitHub username (only relevant for your local machine, will be different for coauthors / other group members).

    github_email – The email linked to your GitHub account (only relevant for your local machine, will be different for coauthors / other group members).

    git_remote_url – Paste your remote URL here if applicable.

    make_initial_commit – Whether we should make the first commit for you.

    version – The version of your project.

    python_version – The python version, min 3.10, tested with 3.10 - 3.11.

    conda_environment_name – Name of your conda environment. This should not be too long, since you need to type it often. Typically just the same as project_slug.

    create_conda_environment_at_finish – You can do so for convenience, but often it is useful to add packages to the environment file first so that it will serve your needs.

    add_python_example – Whether to set up the example project in the Python programming language.

    add_r_example – Whether to set up the example project in the R programming language.

    Warning

    The R example project is a very recent addition and has not been battle-tested. Feedback is greatly appreciated!

    add_julia_example – Whether to set up the example project in the Julia programming language.

    Warning

    The Julia example project is not implemented yet. Help is appreciated, see Issue #123! Selecting this option only installs pytask-Julia to the environment.

    add_stata_example – Whether to set up the example project in the Stata programming language.

    Warning

    The Stata example project is not implemented yet. Help is appreciated, see Issue #124! Selecting this option only installs pytask-Stata to the environment.

    add_linters – Whether to add tools to pre-commit hook that check your code quality, but cannot fix your code automatically. Not recommended for inexperienced programmers.

    add_github_actions – Whether to add GitHub actions configuration files.

    create_changelog – Whether to create a CHANGES file where contributors note their changes made to the project.

    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

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

    $ conda activate <conda_environment_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.

  4. Pre-commit hooks 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

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

    $ pytask

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

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

Depending on what your needs are, move on with the section on starting a project from scratch or on porting an existing project.

How to get started on a second machine#

If you already have the templates running on your computer and hosted on GitHub, it is very easy to invite a collaborator or to use a second machine. Importantly you do not need to go through the cookiecutter dialogue etc.

On the second machine prepare the system and open a terminal on Max/Linux or the Anaconda prompt on Windows. Then type

$ git clone <url_of_your_repository>
$ cd <name_of_your_project>
$ conda env create -f environment.yml
$ conda activate <conda_environment_name>
$ pre-commit install

Now your’re all set!