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:

Once you are set up in this fashion, you may want to read up on some additional information in the Background section. 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 and getting the template#

Programme installation#

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

Validating the installation paths#

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 Python obtained via Miniforge, 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, pixi (this contains the required 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:

    $ pixi run 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 conda-forge. Here is an example output obtained on Linux:

    Python 3.13.2 | packaged by conda-forge | (main, Feb 17 2025, 14:10:22) [GCC 13.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.

    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.

Installing the template#

To install the template repository, first go to the econ-project-templates repo.

Now follow the official instructions on how to create a new repository from a template repository.

Customising the template for your needs#

Once you’ve created a new repository from the template, you can begin customising it to meet your specific needs.

First step: Rename the project#

Open the entire directory in VS Code. Search for template_project in the entire codebase and replace it with new_project_name, i.e., a concise version of your project’s name (often called a “slug”). Rename the folder src/template_project to src/<new_project_name>!

Warning

Your project slug new_project_name must be a valid Python identifier, i.e., it must consist of letters, numbers, and underscores only. Do not start with a number. There must not be any spaces, hyphens, or the like in the slug.

Running the project#

Prior to modifying anything but the slug, confirm that the template can be executed on your system. This step is essential to ensure that any subsequent issues can be attributed to changes you make rather than the original template.

  1. Open a terminal and navigate to the project root

    $ cd /to/root/of/template_project

  2. Install the pre-commit hooks

    $ pixi global install pre-commit
$ pre-commit install

    Note

    Installation of pre-commit hooks is mandatory for their functionality. Repeat this step on each new machine where you work on the project.

  3. Run the project

    $ pixi run pytask

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

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

Customising the template#

Removing auxiliary files#

Before proceeding, delete the following items as they correspond to the meta project and not the template itself.

  • docs_template folder

  • .github folder

  • CHANGES_template.md file

  • tests/test_template.py file

Find and replace placeholders#

Now, search for and replace the following placeholders in the entire codebase.

Placeholder

Replacement

JANE DOE

Your full name

EXAMPLE PROJECT

Your project’s name

EXAMPLE UNIVERSITY

Your university’s name

DOE2024

Your project’s citation identifier

https://github.com/OpenSourceEconomics/econ-project-templates

The GitHub repo URL corresponding to your project

Review and update project details#

Once you are done with the replacement of placeholders, you can update the contents of the following files.

File

What to do

README.md

Remove the entire content and replace it with a README for your project

pyproject.toml

Update the project description and add any dependencies you will need

LICENSE

Update the year and name with the current year and your name

.gitignore

1. Remove the part that is not relevant to your project, that includes all lines that start with docs_template
2. Add any files you need to be ignored by git.

Changing tool options#

Finally, you can update options of the included tools. The pre-commit hooks (specified in .pre-commit-config.yaml) may require adjustments to align with your project’s needs. Refer to the Pre-Commit Hooks section for more details.

Next steps#

Depending on what your needs are, move on with the section on Starting a new 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 create the template repository again.

On the second machine prepare the system and open a terminal on Mac/Linux or the Powershell on Windows. Then type

$ git clone <url_of_your_repository>
$ cd <name_of_your_project>
$ pixi global install pre-commit
$ pre-commit install

Now your’re all set!