Contributing

Overview

Thanks for showing interest in contributing to pyfixest! We appreciate all contributions and constructive feedback, whether that be reporting bugs, requesting new features, or suggesting improvements to documentation.

If you’d like to get involved, but are not yet sure how, please feel free to send us an email. Some familiarity with either Python or econometrics will help, but you really don’t need to be a numpy core developer or have published in Econometrica =) We’d be more than happy to invest time to help you get started!

Reporting bugs

We use GitHub issues to track bugs. You can report a bug by opening a new issue or contribute to an existing issue if related to the bug you are reporting.

Before creating a bug report, please check that your bug has not already been reported, and that your bug exists on the latest version of pyfixest. If you find a closed issue that seems to report the same bug you’re experiencing, open a new issue and include a link to the original issue in your issue description.

Please include as many details as possible in your bug report. The information helps the maintainers resolve the issue faster.

Suggesting enhancements

We use GitHub issues to track bugs and suggested enhancements. You can suggest an enhancement by opening a new feature request. Before creating an enhancement suggestion, please check that a similar issue does not already exist.

Please describe the behavior you want and why, and provide examples of how pyfixest would be used if your feature were added.

Contributing to the codebase

Setting up your local environment

pyfixest development flow relies on Python. Testing statistical and econometric models is implement using Python and R. Documents are written with Quarto and Jupyter.

Start by forking the pyfixest GitHub repository, then clone your forked repository using git:

git clone https://github.com/<username>/pyfixest.git
cd pyfixest

In order to work of pyfixest, you will need Python and R installed. If working on documentation, you will need Quarto installed.

There are multiple ways of installing Python and R, but if you need to install them prior to development the following are potential options:

Installing Python

On Mac/Linux via Hombrew:

brew install python@3.11 # specify the version of python you prefer

On Windows via Winget:

winget install -e --id Python.Python.3.11

Installing R

Note that installing R and the R packages listed below is only necessary if you want to test against R in your local installation. You can also test against R by using github actions.

On Mac/Linux:

brew install r

Depending on your local set up, you may need to install additional libraries, for example:

sudo apt install gcc-11 cmake

On Windows using Winget:

winget install -e --id RProject.R

Tests run with R require the following packages:

base
broom
clubSandwich
did2s
fixest
stats
wildrwolf
ritest

Rscript -e 'install.packages(c("broom", "clubSandwich", "did2s", "fixest", "wildrwolf"), repos="https://cran.rstudio.com"); install.packages('ritest', repos = c('https://grantmcdermott.r-universe.dev', 'https://cloud.r-project.org'))'

Documentation for pyfixest is written, compiled, and published using Quarto.

To install Quarto, run:

On MacOS via Homebrew:

brew install --cask quarto

On Linux (Ubuntu using gdebi):

sudo curl -o quarto-linux-amd64.deb -L <https://github.com/quarto-dev/quarto-cli/releases/download/v${QUARTO_VERSION}/quarto-${QUARTO_VERSION}-linux-amd64.deb>
sudo gdebi quarto-linux-amd64.deb

On Windows:

scoop bucket add extras
scoop install extras/quarto

Package Management

PyFixest is using poetry.

Please follow the installation instructions from the poetry documentation.

Afterwards, you can initiate the project environment and install all dependencies by running

cd path-to-pyfixest
poetry install

If you type

poetry shell

you will see that you have activated a custom poetry environment for pyfixest.

Code Style

We use ruff and pre-commit to ensure a consistent code style.

You can install pre-commit from pip by running

pip install pre-commit

To install the required hooks, run

pre-commit install

and you’re ready to go!

Justfile

There are several command line targets that assist with development included in the justfile. Just can be installed to help run these command line targets. Installing just is only recommended and not needed for development of pyfixest.

On Mac/Linux via Homebrew:

brew install just

On Windows:

scoop bucket add main
scoop install main/just

The justfile includes multiple helpful shorthands to help with development. Note that if you are not using windows/powershell, you will have to uncomment the first line of the justfile set shell := ["powershell.exe", "-c"].

# install all development dependencies
just install-dev
# install all R development dependencies
just install-r
# run all tests via pytest
just tests

To rebuild the documentation locally, you can run

# Build documentation and website
just docs-build
# render the docs
just render
# preview the docs
just preview

To re-create the csv files in tests/data that contain results from R packages for testing, you can run just update-tests-data.