دفاتر Jupyter

الكود والنتائج والملاحظات في مستند واحد

دفتر Jupyter مستند يتكوّن من خلايا. خلية الكود تحوي بايثون يمكنك تشغيله، وتظهر مخرجاته (أرقام وجداول ورسوم) تحتها مباشرة. وخلية markdown تحوي نصًا منسّقًا للشرح والمعادلات والعناوين. وتشغّل عملية خلفية تسمى النواة (kernel) الكود وتتذكر كل متغير بين الخلايا. الدفاتر مثالية لاستكشاف البيانات وشرح التحليل، ولهذا تنتشر في البحث الكمي.

# Inside your project's virtual environment
python -m pip install jupyterlab

# Start it; a browser tab opens
jupyter lab

# Keyboard shortcuts you will use all day
#   Shift+Enter   run the cell and move on
#   Esc then A/B  insert a cell above/below
#   Esc then M/Y  turn a cell into markdown/code

النواة تتذكر، وهنا الخطر

يمكن تشغيل الخلايا بأي ترتيب وأي عدد من المرات، وتحتفظ النواة بآخر قيمة لكل متغير. لذلك قد يبدو الدفتر صحيحًا على الشاشة بينما يعتمد على خلية حذفتها أو على تشغيل الخلايا بغير ترتيبها، ولا يستطيع أحد غيرك (ولا أنت غدًا) إعادة إنتاجه. ويُظهر عدّاد التنفيذ بجانب كل خلية كود ([3] و[7]) الترتيب الفعلي. قبل أن تثق بدفتر أو تشاركه استخدم إعادة تشغيل النواة وتشغيل كل الخلايا: فإن فشل أو تغيّرت الأرقام فالدفتر لم يكن قابلًا لإعادة الإنتاج.

# Cell [1]
fee = 0.001

# Cell [2]
cost = 10000 * fee
print(cost)          # 10.0

# Cell [3]: you edit this to fee = 0.002 but never re-run cell [2]
fee = 0.002
print(cost)          # still 10.0: the notebook now says fee=0.002 but shows the old cost

الدفتر مجرد JSON

ملف .ipynb مستند JSON فيه قائمة cells. لكل خلية cell_type ("code" أو "markdown" أو "raw") وsource (قائمة أسطر أو نص واحد)؛ وتخزّن خلايا الكود أيضًا outputs وexecution_count. وبما أنه JSON عادي يمكنك قراءة الدفاتر وتعديلها بالوحدة json، وبهذا تحوّلها الأدوات إلى سكربتات أو تزيل مخرجاتها. وهذا يفسّر أيضًا لماذا تُنتج الدفاتر فروقات Git مزعجة: فالمخرجات والعدّادات تتغير مع كل تشغيل.

import json

notebook = {
    "nbformat": 4, "nbformat_minor": 5, "metadata": {},
    "cells": [
        {"cell_type": "markdown", "metadata": {}, "source": ["# Fee study\n", "Does the fee matter?"]},
        {"cell_type": "code", "metadata": {}, "execution_count": 2,
         "source": ["fee = 0.001\n", "print(10000 * fee)"],
         "outputs": [{"output_type": "stream", "name": "stdout", "text": ["10.0\n"]}]},
    ],
}

# What the file looks like, and how to walk it
print(len(json.dumps(notebook, indent=1).splitlines()) > 10)     # True
for cell in notebook["cells"]:
    print(cell["cell_type"], "".join(cell["source"]).splitlines()[0])
# markdown # Fee study
# code fee = 0.001

عادات لدفاتر مرتبة وموثوقة

أبقِ الدفاتر قصيرة وخطية: من الأعلى إلى الأسفل، والاستيرادات والإعدادات في الخلية الأولى، وفكرة واحدة في كل قسم بعنوان markdown. انقل المنطق القابل لإعادة الاستخدام إلى دوال في وحدة .py عادية (انظر الحزم) واستوردها ليمكن اختبارها؛ فيكتفي الدفتر بالاستدعاء والرسم. أعد التشغيل وشغّل الكل قبل كل إيداع. وتحت Git امسح المخرجات أولًا (أداة مثل nbstripout تفعل ذلك تلقائيًا) وإلا أودعت ميغابايتات من الرسوم وفروقات غير مقروءة. ولا تترك مفاتيح الواجهات البرمجية في خلية أو مخرجات.

# Keep notebooks tidy under Git
python -m pip install nbstripout
nbstripout --install           # strips outputs automatically on every commit

# Run a notebook top to bottom from the terminal (a reproducibility check)
jupyter nbconvert --to notebook --execute study.ipynb --output checked.ipynb

# Turn a notebook into a plain script
jupyter nbconvert --to script study.ipynb

• تُشغَّل الخلايا بأي ترتيب والنواة تتذكر: أعد التشغيل وشغّل الكل قبل أن تثق أو تشارك.
• ملف .ipynb هو JSON: cells لكل منها cell_type وsource، وللكود outputs وexecution_count.
• أبقِ المنطق في وحدات، وامسح المخرجات قبل الإيداع، وأبعد الأسرار.

التالي: سير عمل البحث القابل لإعادة الإنتاج، بجمع البذور والبيئات والإصدارات وفحوص البيانات ليتمكن أي شخص من إعادة بناء النتيجة.

المختبر: ما الذي يُقيَّم

• استخرج الكود من دفتر باستخدام code_cells25 نقطة
• عُدّ أنواع الخلايا باستخدام count_cells25 نقطة
• امسح المخرجات قبل الإيداع باستخدام clear_outputs25 نقطة
• حوّل دفترًا إلى سكربت باستخدام to_script25 نقطة