Science notebook template

🧪 A simple, elegant template for repositories supporting publications. Scientific companion to the much more sophisticated code template Tyrannosaurus 🦖 No cookiecutter. Just click Use this Template above.

👋 Citing

Just tell people how to cite your work.

Please reference the manuscript with this BibTeX:

@misc{sciencenotebooktemplate,
  doi = {10.5281/zenodo.4495745},
  url = {https://zenodo.org/record/4485186},
  author = {Myers-Turnbull, Douglas},
  title = {dmyersturnbull/science-notebook-template: v0.1.0},
  publisher = {Zenodo},
  year = {2021},
  copyright = {Open Access}
}

Or APA format:

Myers-Turnbull, D. (2021). dmyersturnbull/science-notebook-template (v0.1.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.4495745

🎁 About this repository

What’s in this repo?

• Automatic linting of Python, Markdown, config files, etc. using pre-commit, Ruff, and Prettier.
• IDE hints via EditorConfig with good defaults for most languages
• Recommended readme organization, CITATION.cff, etc.
• Nice gitignore, dockerignore, pull request and issue templates, etc.

📜 Steps to reproduce

How to download needed data, run the code, etc.

1. Click Use this Template and create your repo.
2. Clone your repo, and run pip install pre-commit and pre-commit install.
3. Add your scripts or notebooks, write your readme, and modify anything as you see fit. Note: When you run git commit, pre-commit will error if it made changes. That’s normal. Just re-run to finish the commit.
4. In your repo settings, disable Discussions and Wiki. Also disable Projects, if not needed.
5. Enable Vulnerability reporting under Code security.
6. Add a Branch protection rule for main. Check these boxes:
   • Require a pull request before merging
   • Require status checks to pass before merging
   • Require branches to be up to date before merging
   • Require linear history
7. Set up Binder, and Get a DOI.

Development workflow

Use pull requests (PRs) instead of committing directly into main. Give PRs useful titles and descriptions. Use GitHub Releases to mark stable versions, and include release notes that document the changes. Follow a consistent versioning scheme, such as semantic versioning.

🌳 Layout

Describe the layout of this repo.

├── src/                     ⟵ project source code
├── data
│   ├── temp-output/         ⟵ files generated per-run
│   │   ├── figures/         ⟵ raw charts and graphs
│   │   ├── ...files
│   │   ├── csv/             ⟵ raw tables
│   │   └── ...files
│   ├── living/              ⟵ files we are actively curating
│   │   ├── figures/
│   │   ├── tables/
│   │   ├── manuscript/
│   │   └── ...files
│   └── frozen/              ⟵ non-modifiable files
│       ├── raw/             ⟵ experimental or downloaded data
│       └── ref/             ⟵ frozen analyses and outputs
└── README.md

Some of or all your data might live somewhere external (as documented below) rather than data/frozen/. See research projects guide for more info.

🔌 External resources

Describe any external resources needed (e.g., API keys).

🍁 Contributing

Tell people how to report problems and ask questions.

The source code in this repository is licensed under the terms of the Apache License 2.0. Contributions and questions are welcome via issues. For reference, refer to the contributing guide and security policy.

Note: The source code headers (i.e., SPDX) are to protect you, the user. I don’t expect you to retain them. Remove them or replace them with your own when you modify them.