Jupyter Notebook科研笔记：版本控制与环境隔离实践指南 (Version 2024.03.15)
TL;DR
本文档旨在提供Jupyter Notebook在科研工作流中实现高效版本控制和环境隔离的实用指南。核心内容包括使用Git进行代码和数据版本管理，以及通过Conda或venv创建独立Python环境以确保可复现性。所有操作均以命令行示例驱动，确保精确性和可操作性。
前置条件 (Prerequisites)
在开始之前，请确保您的系统已安装以下软件：
- Git 2.30.0 或更高版本。
- Miniconda3 4.10.3 或 Anaconda3 2021.11 或更高版本。
- Python 3.8 或更高版本。
1. Jupyter Notebook 版本控制实践
科研笔记的版本控制对于确保研究的可追溯性和可复现性至关重要。我们推荐使用Git。
1.1 初始化Git仓库并忽略非必要文件
在您的项目根目录下初始化Git仓库，并配置.gitignore文件以排除大型数据集、虚拟环境目录和编译文件。这将避免不必要的版本膨胀，并专注于核心代码和结果。
1.1.1 初始化仓库
git init
Expected Output:
Initialized empty Git repository in /path/to/your/project/.git/
1.1.2 创建 .gitignore 文件
编辑 .gitignore 文件，添加常见忽略项。以下是一个推荐的配置，可用于Jupyter Notebook科研项目。您可能需要查找“Python项目gitignore怎么写”以获取更全面的模板。
touch .gitignore
cat << EOF > .gitignore
# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
# Jupyter Notebook
.ipynb_checkpoints
venv/
env/
# IDE specific files
.idea/
.vscode/
# Data
*.csv
*.hdf5
*.parquet
*.pkl
# Logs
*.log
EOF
1.1.3 首次提交
添加并提交您的初始文件。
git add .
git commit -m "Initial project setup and .gitignore"
Expected Output:
[master (root-commit) d1e2f3g] Initial project setup and .gitignore
X files changed, Y insertions(+), Z deletions(-)
create mode 100644 .gitignore
create mode 100644 your_notebook.ipynb
Note: 对于大型数据集，请考虑使用Git LFS (Large File Storage) 进行管理，以避免Git仓库臃肿。搜索“Git LFS教程”以获取详细使用方法。
2. Conda 环境隔离与可复现性
为每个科研项目创建独立的环境是保证可复现性的关键。Conda是管理Python环境和包的强大工具。
2.1 创建并激活独立环境
为您的项目创建一个新的Conda环境，并指定Python版本。然后激活该环境。
conda create --name my_research_env python=3.9 -y
Expected Output (truncated):
... Proceed ([y]/n)? y
... Done
#
# To activate this environment, use
#
# $ conda activate my_research_env
#
# To deactivate an active environment, use
#
# $ conda deactivate
conda activate my_research_env
Expected Output:
(my_research_env) user@host:~/your_project$
2.2 安装所需包与导出环境配置
在激活的环境中安装Jupyter以及其他必要的科学计算包，如NumPy、Pandas、Matplotlib等。安装完成后，导出环境配置到environment.yml文件。
pip install jupyter numpy pandas matplotlib scikit-learn
conda env export > environment.yml
Expected Output: (environment.yml文件内容示例)
name: my_research_env
channels:
- defaults
dependencies:
- python=3.9
- numpy=1.23.5
- pandas=1.5.3
- matplotlib=3.7.1
- scikit-learn=1.2.2
- pip:
- jupyter==1.0.0
- ipykernel==6.21.3
prefix: /path/to/miniconda3/envs/my_research_env
Warning: 确保 environment.yml 文件被纳入Git版本控制。这样其他团队成员或您自己将来可以准确复现当前环境。
2.3 从 environment.yml 复现环境
当需要在另一台机器或未来复现实验环境时，可以使用导出的environment.yml文件。
conda env create -f environment.yml
Expected Output: (类似创建环境时的输出，最终提示激活环境)
... Downloading and installing packages ...
#
# To activate this environment, use
#
# $ conda activate my_research_env
#
# To deactivate an active environment, use
#
# $ conda deactivate
Note: 如果目标机器上已经存在同名环境，Conda会提示冲突。建议在复现前删除或使用新名称。