# 🧪 Cookiecutter Scientific Research
<p align="center">
<strong>A standardized, flexible template for scientific research projects</strong>
</p>
<p align="center">
<a href="#project-overview">Project Overview</a> •
<a href="#features">Features</a> •
<a href="#quick-start">Quick Start</a> •
<a href="#project-structure">Project Structure</a> •
<a href="#development-guide">Development Guide</a> •
<a href="#acknowledgements">Acknowledgements</a> •
<a href="#license">License</a>
</p>
## 📋 Project Overview
Cookiecutter Scientific Research is a project template generator designed for scientific research projects, aimed at providing a standardized structure and tool configuration to help researchers focus on scientific discovery rather than project setup. Through predefined best practices, this template supports high-quality scientific computing and data analysis workflows, ensuring the reproducibility and reliability of the research process.
## ✨ Features
- **Standardized Project Structure** - Conforms to best practices for modern scientific computing projects
- **Reproducible Experimental Environment** - Built-in environment management and dependency locking mechanisms
- **Integrated Documentation System** - Preconfigured MkDocs documentation for showcasing research results
- **Testing and Quality Control** - Built-in testing frameworks and code quality tools
- **Modern Package Management** - Simplifies dependency management using modern tools like uv/pip
## 🚀 Quick Start
### Prerequisites
- Python 3.9 or higher
- [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/stable/) (recommended for tool installation)
### Installation
This project is available on PyPI. As a cross-project tool, we recommend using uv or pipx for installation:
```bash
# Install using uv (recommended)
uv tool install cookiecutter-scientific-research
# Or install using pipx
pipx install cookiecutter-scientific-research
```
### Creating a New Project
After installation, simply run the following command and follow the prompts:
```bash
ccsr
```
### Initializing the Project Environment
After creating the project, navigate to the project directory and initialize the environment:
```bash
cd your-project-name
# Use uv to manage dependencies (recommended)
uv lock
uv sync
```
## 📂 Project Structure
The generated project follows the directory structure below, with each section having a clear responsibility:
```
├── LICENSE <- Project license
├── Makefile <- Makefile with common commands
├── README.md <- Project documentation
├── pyproject.toml <- Project configuration and dependency management
│
├── data <- Data directory
│ ├── external <- Third-party data
│ ├── interim <- Intermediate processed data
│ ├── processed <- Final analysis datasets
│ └── raw <- Original data (read-only)
│
├── {{ cookiecutter.module_name }} <- Project source code
│ ├── __init__.py <- Package initialization file
│ ├── config.py <- Configuration parameter management
│ ├── dataset.py <- Data acquisition and loading
│ ├── plots.py <- Data visualization functions
│ │
│ ├── analyze <- Data analysis module
│ │ └── analysis.py
│ │
│ ├── modeling <- Model training and prediction
│ │ ├── __init__.py
│ │ ├── predict.py <- Model prediction
│ │ └── train.py <- Model training
│ │
│ ├── models <- Model definitions
│ │ ├── __init__.py
│ │ └── model.py <- Model architecture
│ │
│ ├── process <- Data processing
│ │ └── features.py <- Feature engineering
│ │
│ └── utils <- Utility functions
│ ├── __init__.py
│ └── tools.py <- General utilities
│
├── notebooks <- Jupyter/Marimo notebooks
│ (Naming convention: number-creator-description)
│
├── docs <- Project documentation (MkDocs)
│
├── references <- Reference materials and literature
│
├── reports <- Analysis reports and results
│ ├── figures <- Generated charts
│ └── logs <- Experiment logs
│
└── tests <- Test directory
```
## 🔧 Development Guide
### Package Management and Building
This project uses `flit_core` as the build backend, supporting modern Python package management. To build distribution packages:
```bash
# Install build dependencies
uv lock
# Install all optional dependencies
uv sync --all-extras
# Or install specific dependency groups
uv sync -e dev # Development dependencies
uv sync -e test # Testing dependencies
uv sync -e docs # Documentation dependencies
# Build distribution packages
uv build
```
The built wheel files and source distribution packages will be saved in the `dist/` directory.
### Project Customization
During the template generation process, you can customize various aspects of the project according to prompts:
- Project name and module name
- Author information
- License type
- Dependency management method
- Test framework selection
- And more
## 🙏 Acknowledgements
This project is modified from [cookiecutter-data-science](https://github.com/drivendataorg/cookiecutter-data-science), special thanks to the DrivenData team for providing the excellent template and inspiration. The project has been customized for scientific research scenarios on the original basis, including tool chain optimization, workflow adjustments, and documentation structure optimization.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "cookiecutter-scientific-research",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "cookiecutter, template, science, research, reproducible-research, project-structure",
"author": null,
"author_email": "Wenjie Xu <wenjie.xu.cn@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/e6/2b/7ee3fd0244a93a2c44bbddb15e659d8c06e69c7f1c09979ec0d0631c88e3/cookiecutter_scientific_research-1.0.4.tar.gz",
"platform": null,
"description": "# \ud83e\uddea Cookiecutter Scientific Research\n\n<p align=\"center\">\n <strong>A standardized, flexible template for scientific research projects</strong>\n</p>\n\n<p align=\"center\">\n <a href=\"#project-overview\">Project Overview</a> \u2022\n <a href=\"#features\">Features</a> \u2022\n <a href=\"#quick-start\">Quick Start</a> \u2022\n <a href=\"#project-structure\">Project Structure</a> \u2022\n <a href=\"#development-guide\">Development Guide</a> \u2022\n <a href=\"#acknowledgements\">Acknowledgements</a> \u2022\n <a href=\"#license\">License</a>\n</p>\n\n## \ud83d\udccb Project Overview\n\nCookiecutter Scientific Research is a project template generator designed for scientific research projects, aimed at providing a standardized structure and tool configuration to help researchers focus on scientific discovery rather than project setup. Through predefined best practices, this template supports high-quality scientific computing and data analysis workflows, ensuring the reproducibility and reliability of the research process.\n\n## \u2728 Features\n\n- **Standardized Project Structure** - Conforms to best practices for modern scientific computing projects\n\n- **Reproducible Experimental Environment** - Built-in environment management and dependency locking mechanisms\n- **Integrated Documentation System** - Preconfigured MkDocs documentation for showcasing research results\n- **Testing and Quality Control** - Built-in testing frameworks and code quality tools\n- **Modern Package Management** - Simplifies dependency management using modern tools like uv/pip\n\n## \ud83d\ude80 Quick Start\n\n### Prerequisites\n\n- Python 3.9 or higher\n- [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/stable/) (recommended for tool installation)\n\n### Installation\n\nThis project is available on PyPI. As a cross-project tool, we recommend using uv or pipx for installation:\n\n```bash\n# Install using uv (recommended)\nuv tool install cookiecutter-scientific-research\n\n# Or install using pipx\npipx install cookiecutter-scientific-research\n```\n\n### Creating a New Project\n\nAfter installation, simply run the following command and follow the prompts:\n\n```bash\nccsr\n```\n\n### Initializing the Project Environment\n\nAfter creating the project, navigate to the project directory and initialize the environment:\n\n```bash\ncd your-project-name\n\n# Use uv to manage dependencies (recommended)\nuv lock\nuv sync\n```\n\n## \ud83d\udcc2 Project Structure\n\nThe generated project follows the directory structure below, with each section having a clear responsibility:\n\n```\n\u251c\u2500\u2500 LICENSE <- Project license\n\u251c\u2500\u2500 Makefile <- Makefile with common commands\n\u251c\u2500\u2500 README.md <- Project documentation\n\u251c\u2500\u2500 pyproject.toml <- Project configuration and dependency management\n\u2502\n\u251c\u2500\u2500 data <- Data directory\n\u2502 \u251c\u2500\u2500 external <- Third-party data\n\u2502 \u251c\u2500\u2500 interim <- Intermediate processed data\n\u2502 \u251c\u2500\u2500 processed <- Final analysis datasets\n\u2502 \u2514\u2500\u2500 raw <- Original data (read-only)\n\u2502\n\u251c\u2500\u2500 {{ cookiecutter.module_name }} <- Project source code\n\u2502 \u251c\u2500\u2500 __init__.py <- Package initialization file\n\u2502 \u251c\u2500\u2500 config.py <- Configuration parameter management\n\u2502 \u251c\u2500\u2500 dataset.py <- Data acquisition and loading\n\u2502 \u251c\u2500\u2500 plots.py <- Data visualization functions\n\u2502 \u2502\n\u2502 \u251c\u2500\u2500 analyze <- Data analysis module\n\u2502 \u2502 \u2514\u2500\u2500 analysis.py\n\u2502 \u2502\n\u2502 \u251c\u2500\u2500 modeling <- Model training and prediction\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 predict.py <- Model prediction\n\u2502 \u2502 \u2514\u2500\u2500 train.py <- Model training\n\u2502 \u2502\n\u2502 \u251c\u2500\u2500 models <- Model definitions\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2514\u2500\u2500 model.py <- Model architecture\n\u2502 \u2502\n\u2502 \u251c\u2500\u2500 process <- Data processing\n\u2502 \u2502 \u2514\u2500\u2500 features.py <- Feature engineering\n\u2502 \u2502\n\u2502 \u2514\u2500\u2500 utils <- Utility functions\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 tools.py <- General utilities\n\u2502\n\u251c\u2500\u2500 notebooks <- Jupyter/Marimo notebooks\n\u2502 (Naming convention: number-creator-description)\n\u2502\n\u251c\u2500\u2500 docs <- Project documentation (MkDocs)\n\u2502\n\u251c\u2500\u2500 references <- Reference materials and literature\n\u2502\n\u251c\u2500\u2500 reports <- Analysis reports and results\n\u2502 \u251c\u2500\u2500 figures <- Generated charts\n\u2502 \u2514\u2500\u2500 logs <- Experiment logs\n\u2502\n\u2514\u2500\u2500 tests <- Test directory\n```\n\n## \ud83d\udd27 Development Guide\n\n### Package Management and Building\n\nThis project uses `flit_core` as the build backend, supporting modern Python package management. To build distribution packages:\n\n```bash\n# Install build dependencies\nuv lock\n# Install all optional dependencies\nuv sync --all-extras\n# Or install specific dependency groups\nuv sync -e dev # Development dependencies\nuv sync -e test # Testing dependencies\nuv sync -e docs # Documentation dependencies\n\n# Build distribution packages\nuv build\n```\n\nThe built wheel files and source distribution packages will be saved in the `dist/` directory.\n\n### Project Customization\n\nDuring the template generation process, you can customize various aspects of the project according to prompts:\n\n- Project name and module name\n- Author information\n- License type\n- Dependency management method\n- Test framework selection\n- And more\n\n## \ud83d\ude4f Acknowledgements\n\nThis project is modified from [cookiecutter-data-science](https://github.com/drivendataorg/cookiecutter-data-science), special thanks to the DrivenData team for providing the excellent template and inspiration. The project has been customized for scientific research scenarios on the original basis, including tool chain optimization, workflow adjustments, and documentation structure optimization.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A logical, reasonably standardized but flexible project structure for doing and sharing scientific research.",
"version": "1.0.4",
"project_urls": {
"Documentation": "https://github.com/waynexucn/cookiecutter-scientific-research/blob/master/README.md",
"Issues": "https://github.com/waynexucn/cookiecutter-scientific-research/issues",
"Source Code": "https://github.com/waynexucn/cookiecutter-scientific-research/"
},
"split_keywords": [
"cookiecutter",
" template",
" science",
" research",
" reproducible-research",
" project-structure"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5a0b643b161ff98016c91de009de03984bec8bf7be368788fd7e2874a9e6df92",
"md5": "9912ac0aa8c1f915daf65cdd25378c33",
"sha256": "f5c2d92384c51c12570eb0d611bcc1525efe820f9c4b6992f0f3f4e0f420c363"
},
"downloads": -1,
"filename": "cookiecutter_scientific_research-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9912ac0aa8c1f915daf65cdd25378c33",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 9435,
"upload_time": "2025-07-25T07:31:01",
"upload_time_iso_8601": "2025-07-25T07:31:01.760416Z",
"url": "https://files.pythonhosted.org/packages/5a/0b/643b161ff98016c91de009de03984bec8bf7be368788fd7e2874a9e6df92/cookiecutter_scientific_research-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e62b7ee3fd0244a93a2c44bbddb15e659d8c06e69c7f1c09979ec0d0631c88e3",
"md5": "3dfeb9b05d6691542368cf415b0ead1a",
"sha256": "440eab200d86127bc191230f28e49820db00c25285fcc3dabfa2cce96b1970cc"
},
"downloads": -1,
"filename": "cookiecutter_scientific_research-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "3dfeb9b05d6691542368cf415b0ead1a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 9545,
"upload_time": "2025-07-25T07:31:03",
"upload_time_iso_8601": "2025-07-25T07:31:03.893479Z",
"url": "https://files.pythonhosted.org/packages/e6/2b/7ee3fd0244a93a2c44bbddb15e659d8c06e69c7f1c09979ec0d0631c88e3/cookiecutter_scientific_research-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 07:31:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "waynexucn",
"github_project": "cookiecutter-scientific-research",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cookiecutter-scientific-research"
}
JSON
