The purpose of this template is to be a foundation for creating a new research project, specifically for data/network science research in the NERDS research group - but feel free to use it in any way. The template comes with a basic folder structure and a workflow adapted for programming using Python. This should work for most cases, but if you need a richer template, consider using Cookiecutter. For information about packaging, see the packaging tutorial.
Read this file to know what to do after cloning the template.
Put a license inside your repository before doing anything else. There are many licenses, but for research we recommend one of the following three:
- If you are writing code, AGPLv3 is best to encourage open science as it forces public availability and thus reproducibility.
- If you want a license that permits development of a closed version of the code (usually relevant for a business), use the MIT License.
- If you want to share educational resources or text, use CC BY-SA 4.0.
Go to the cloned folder and create a new virtual environment. You can either create a new virtual environment then install the necessary dependencies with pip
using the requirements.txt
file:
pip install -r requirements.txt
Or create a new environment with the dependencies with conda
or mamba
using the environment.yml
file. In that case, you should rename your virtual environment as you like in the file by replacing ENVNAME
in environment.yml
. You can then use:
mamba env create -f environment.yml
This will install the latest versions of pre-commit
and pytest
. If you need a specific version, modify the files.
You then install the pre-commit hooks that are specified in the .pre-commit-config.yaml
. You can remove or add the ones that you like. Notable hooks are:
- Ruff linting and formatting as a pre-commit hook.
- Prettier for formatting multiple formats of files such as YML or JSON.
- Out-of-the-box basic hooks for a list of basic hooks.
You install the ones specified in
.pre-commit-config.yaml
by running:
pre-commit install
Git can't track empty folders so we placed a README.txt
into each one that gives information about a folder's contents. Once you have put files in your folders such as scripts
, you can remove or update a folder's README.txt
.
Based on your preferences, you can update the .gitignore
file. This one is created by combining Windows, MacOS, Python, and Visual Studio Code on gitignore.io.
You should add folders or files that you don't want to track, either because they are large, private, temporary...
When you add packages to your installation, you should update the requirements.txt
and environment.yml
files so that your environment is reproducible. For pip:
pip freeze > requirements.txt
See here for more details. This will only save packages installed with pip.
For conda/mamba:
mamba env export > environment.yml
See here for more details.
The readme has many placeholders, like PROJECTNAME or ENVNAME. Update those to fit your concrete project.
Once you are done adapting this template to your use, remove this file.
When you make the code public or publish a paper, update the citation file template in your repo: CITATION.cff
As best practice, place your code/data on zenodo. Follow the tutorial to connect your github repo with zenodo.
If you have problems committing due to the linter complaining, try removing the following lines from .pre-commit-config.yaml
:
# Run the linter.
- id: ruff
types_or: [python, pyi, jupyter]
args: [--fix]