{{cookiecutter.project_name}}

[]([ ) {% if cookiecutter.project_license != "No License" %}  {% endif %}

{{ cookiecutter.project_description}}

Table of Contents

• Preparation
  • Cloning the project to your local machine
  • Setup
  • Make data available
• Project Structure
• Dummy files
• Maintainer
• Contact & Issues

Preparation

Cloning the project to your local machine

To reproduce the project, clone this repository on your machine

git clone https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}

Setup

For getting started in the fastest way possible, there are Make targets provided. So, to set up the project, simply run the following commands from the main directory:

First, run

make conda-env
# or alternatively
make install-requirements

to install the required packages either via conda or pip.

![!NOTE] I recommend that you use Conda (or, for higher performance, Mamba) as a package manager.

Then, — make sure you have activated the virtual environment — run

make src-available

to make the project's routines (located in src) available for import.

Finally, you can run

make tests
make documentation

to run the tests via pytest and build the documentation located in docs. The latter will create an HTML-rendered version of the documentation in docs/_build/html/.

Note

If you experience that something is not working (e.g. creating the documentation via make documentation) try to perform an update via mamba update --all. This might solve the problem.

Make data available

Next, make the data available or accessible under data/ (see project structure below and details in the documentation). If the project is dealing with large amounts of data that reside somewhere outside your home directory, I would suggest that you link the respective subdirectories inside data/. The Python scripts should be able to follow symlinks.

A recommendation for long-running tasks:
Some tasks like data processing will need a long time. It is highly recommended that you use a detachable terminal environment like screen or tmux. This way you can detach from the session (even close your terminal) without losing or ending the process. Alternatively, if you work on a high-performance computer, make use of the queuing system to submit jobs.

Project Structure

├── assets             <- A place for assets like shapefiles or config files
│
├── data               <- Contains all data used for the analyses in this project.
│   │                     The sub-directories can be links to the actual location of your data.
│   │                     However, they should never be under version control! (-> .gitignore)
│   ├── interim        <- Intermediate data that have been transformed from the raw data
│   ├── processed      <- The final, processed data used for the actual analyses
│   └── raw            <- The original, immutable(!) data
│
├── docs               <- The technical documentation (default engine: Jupyter-Book; but feel free to use 
│                         MkDocs, Sphinx, or anything similar).
│                         This should contain only documentation of the code and the assets.
│                         A report of the actual project should be placed in `reports/book`.
│
├── logs               <- Storage location for the log files being generated by scripts (tip: use `lnav` to view)
│
├── notebooks          <- Jupyter notebooks. Naming convention is a number (for ordering),
│   │                     and a short `-` or `_` delimited description, e.g. `01-initial-analyses`
│   ├── _paired        <- Optional location for your paired Jupyter notebook files
│   ├── exploratory    <- Notebooks for exploratory tasks
│   └── reports        <- Notebooks generating reports and figures
│
├── references         <- Data descriptions, manuals, and all other explanatory materials
│
├── reports            <- Generated reports (e.g. HTML, PDF, LaTeX, etc.)
│   ├── book           <- A Jupyter-Book describing the project
│   └── figures        <- Generated graphics and figures to be used in reporting
│
├── setup.py           <- makes project pip installable (pip install -e .) so src can be imported
├── scripts            <- High-level scripts that use (low-level) source code from `src/`
├── src                <- Source code (and only source code!) for use in this project
│   ├── tests          <- Contains tests for the code in `src/`
│   └── __init__.py    <- Makes src a Python module and provides some standard variables
│
├── .env               <- In this file, specify all your custom environment variables
│                         Keep this out of version control!
├── CHANGELOG.md       <- All major changes should go in there
├── LICENSE            <- The license used for this project
├── Makefile           <- A self-documenting Makefile for standard CLI tasks
├── pyproject.toml      <- Configuration file for the Python project
├── README.md          <- The top-level README of this project
└── requirements.txt   <- The requirements file for reproducing the analysis environment, e.g.
                          generated with `pip freeze > requirements.txt`

Dummy files

The following files are for demonstration purposes only and can be safely deleted if not needed:

├── notebooks/01-minimal-example.ipynb
├── docs/*
├── reports/book/*
├── scripts/01-test.py
└── src
    ├── tests/*
    └── submodule.py

Maintainer

• [{{ cookiecutter.github_username }}](https://github.com/{{ cookiecutter.github_username }})

Contact & Issues

For any questions or issues, please contact me via {{ cookiecutter.email }} or open an [issue](https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/issues).

---

© [{{ cookiecutter.project_author }}](https://github.com/{{ cookiecutter.github_username }}), {% now 'utc', '%Y' %}