{"id":"l-pda-5-4","courseId":"python-data-analysis","lang":"ar","kind":"wrapup","summary":"حوّل تحليلًا لمرة واحدة إلى تحليل قابل لإعادة الإنتاج باستخدام المُعامِلات والدوال والـ assertions والمخرجات المحفوظة و notebook نظيف يعمل من الأعلى إلى الأسفل، واعرف إلى أين تتجه بعد هذه الدورة.","html":"

إجابة الربع الرابع مكتوبة. بعد ثلاثة أشهر سيسأل رئيس النمو السؤال نفسه عن الربع الأول، وقد يكون من يجيب أنت، أو زميل، أو أنت وقد نسيت كل التفاصيل. التحليل الذي لا يعمل إلا في الـ notebook الذي وُلد فيه عمل لمرة واحدة. أما التحليل الذي يستطيع أيّ شخص إعادة تشغيله من الملفات الخام والحصول على الأرقام نفسها فهو أصل ذو قيمة. والفرق حفنة من العادات.

\n

شكل التحليل القابل لإعادة التشغيل

\n
Python
import pandas as pd\n\n# Parameters: everything that changes between runs lives here.\nORDERS_FILE = \"orders.csv\"\nITEMS_FILE = \"order_items.csv\"\nQUARTER = \"2025Q4\"\nEXCLUDE_STATUSES = [\"cancelled\"]\n\ndef load_orders(orders_file, items_file):\n    \"\"\"One row per order with revenue (after discounts, no shipping).\"\"\"\n    items = pd.read_csv(items_file)\n    orders = pd.read_csv(orders_file, parse_dates=[\"order_date\"])\n    items[\"revenue\"] = items[\"quantity\"] * items[\"unit_price\"] * (1 - items[\"discount\"])\n    revenue = items.groupby(\"order_id\", as_index=False)[\"revenue\"].sum()\n    df = orders.merge(revenue, on=\"order_id\", how=\"left\", validate=\"one_to_one\")\n    assert df[\"order_id\"].is_unique, \"duplicate orders\"\n    assert df[\"revenue\"].notna().all(), \"orders without items\"\n    return df\n\ndef quarter_summary(df, quarter, exclude):\n    kept = df[~df[\"status\"].isin(exclude)]\n    in_q = kept[kept[\"order_date\"].dt.to_period(\"Q\") == quarter]\n    assert len(in_q) > 0, f\"no orders in {quarter}\"\n    return {\n        \"quarter\": quarter,\n        \"revenue\": round(in_q[\"revenue\"].sum(), 2),\n        \"orders\": len(in_q),\n        \"customers\": in_q[\"customer_id\"].nunique(),\n        \"aov\": round(in_q[\"revenue\"].mean(), 2),\n    }\n\ndf = load_orders(ORDERS_FILE, ITEMS_FILE)\nsummary = pd.DataFrame([quarter_summary(df, q, EXCLUDE_STATUSES) for q in [\"2025Q3\", QUARTER]])\nprint(summary)\nprint(f\"pandas {pd.__version__}\")
\n

أربع أفكار تحمل هذا الكود. المُعامِلات (parameters) في الأعلى تسمّي كل مُدخل وكل قرار، ومنها تعريف الإيراد، فيغيّر تشغيل الربع القادم سطرًا واحدًا. والدوال تحمل الخطوات، وتأخذ مُدخلاتها كوسائط وتعيد النتائج، فلا تعتمد أبدًا على متغيّر متبقٍّ من مكان آخر. والـ assertions تحدّد ما يجب أن يكون صحيحًا في البيانات قبل حساب أي شيء منها، كما فعلت في الدرس 3.5. وطباعة الإصدار تسجّل أيّ إصدار من pandas أنتج الأرقام، لأن القيم الافتراضية تتغيّر فعلًا بين الإصدارات الرئيسية.

\n

نظافة الـ notebook

\n

الـ notebooks ممتازة للاستكشاف وخطيرة لإعداد التقارير، لأن الخلايا يمكن أن تُشغَّل بأي ترتيب، والمتغيّرات تبقى بعد زوال الخلايا التي صنعتها. قبل أن تشارك واحدًا:

\n\n\n

ما تستطيع فعله الآن

\n

بدأت هذه الدورة وأنت لا تستطيع كتابة سطر Python واحد. أنت الآن تستطيع تحميل أي ملف CSV وفحصه، وتنظيف فوضى العالم الحقيقي (الخانات الفارغة، والأخطاء الكتابية، والمبالغ المكتوبة كنصوص، والتواريخ الملتبسة، والمكرّرات)، وربط الجداول وإعادة تشكيلها، وتلخيصها بحسب المجموعة وعبر الزمن، ووصف التوزيعات بصدق، وتحويل كل ذلك إلى إجابة مدعومة بالأدلة والتحفّظات. هذا هو العمل اليومي لمحلل البيانات.

\n

أين تتجه بعد ذلك يعتمد على الأسئلة التي تريد الإجابة عنها. تستخدم دورة SQL للمحلّلين بيانات Cartwheel نفسها داخل قاعدة بيانات، وهناك توجد معظم بيانات الشركات فعلًا. وتلتقط الدورة المكثّفة في تعلّم الآلة الملف churn.csv وتطرح السؤال التالي: أيّ العملاء على وشك الرحيل؟ أيًّا كان اختيارك، احتفظ بعادات هذه الدورة: افحص قبل أن تثق، واكتب التعريف، واجعل عملك قابلًا لإعادة التشغيل.

\n","toc":[{"id":"sec-1","text":"شكل التحليل القابل لإعادة التشغيل","level":2},{"id":"sec-2","text":"نظافة الـ notebook","level":2},{"id":"sec-3","text":"ما تستطيع فعله الآن","level":2}],"takeaways":["التحليل القابل لإعادة الإنتاج (reproducible) يعطي النتيجة نفسها حين يشغّله شخص آخر من الملفات الخام، من الأعلى إلى الأسفل، دون خطوات يدوية.","ضع المُدخلات والاختيارات في مُعامِلات مسمّاة في الأعلى (مسارات الملفات، والربع، وتعريف الإيراد)، كي تعني إعادة التشغيل لفترة جديدة تغيير سطر واحد.","الدوال تحمل الخطوات التي تكرّرها؛ والـ assertions تحدّد ما يجب أن تبدو عليه البيانات قبل الثقة بالنتائج.","استخدم Restart and Run All قبل مشاركة أي notebook، واحفظ النتائج بـ to_csv(..., index=False) بدلًا من نسخ الأرقام بيدك."],"further":[{"title":"pandas.DataFrame.to_csv","url":"https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_csv.html"},{"title":"Python Tutorial - Modules","url":"https://docs.python.org/3/tutorial/modules.html"},{"title":"pandas.DataFrame.pipe","url":"https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.pipe.html"}],"quiz":[{"q":"

يعطي notebook رقم الربع الرابع الصحيح على حاسوبك، لكن زميلك يحصل على رقم مختلف من الملف نفسه. ما السبب الأرجح؟

","options":[{"text":"تعطي pandas إجابات مختلفة قليلًا على الحواسيب المختلفة.","why":"pandas حتمية؛ الكود نفسه على البيانات نفسها يعطي النتيجة نفسها، باستثناء ضوضاء ضئيلة في الأعداد العشرية."},{"text":"يعتمد الـ notebook على خلايا شُغّلت بغير ترتيبها أو على متغيّر أُنشئ في خلية حُذفت لاحقًا.","why":"صحيح. الحالة المخفية في الـ notebook هي السبب الكلاسيكي. وتشغيل Restart and Run All قبل المشاركة يلتقطه."},{"text":"شاشة الزميل تقرّب الأرقام بشكل مختلف.","why":"تقريب العرض يغيّر شكل الرقم، لا الرقم الذي يُحسب."},{"text":"تتغيّر ملفات CSV حين تُنسخ.","why":"النسخ لا يغيّر محتوى الملف؛ النتيجة المختلفة تأتي من مسارات كود مختلفة أو ملفات مختلفة."}],"answer":1},{"q":"

في الربع القادم تحتاج التقرير نفسه للربع 2026Q1. في تحليل حسن البناء، ما الذي يجب أن تغيّره؟

","options":[{"text":"كل خلية تذكر 2025Q4","why":"البحث في الخلايا عن قيم مكتوبة يدويًا هو بالضبط ما وُجدت المُعامِلات لتجنّبه، وستفوتك واحدة."},{"text":"دوال التنظيف","why":"قواعد التنظيف لا تعتمد على الربع؛ وتغييرها لكل تقرير سيجعل النتائج غير قابلة للمقارنة."},{"text":"مُعامِل واحد في الأعلى، مثل QUARTER = "2026Q1"، ومسار ملف المُدخلات إذا تغيّر","why":"صحيح. كل ما يليه يقرأ تلك الأسماء، فيتبعها التحليل كله."}],"answer":2},{"q":"

ماذا يضيف assertion مثل assert df["order_id"].is_unique إلى تحليل قابل لإعادة الإنتاج؟

","options":[{"text":"يجعل التحليل يتوقّف برسالة واضحة حين تكسر بيانات جديدة افتراضًا تعتمد عليه النتائج.","why":"صحيح. بدونه، سيضخّم ملف مُصدَّر مكرّر الإيراد بهدوء في تقرير الربع القادم."},{"text":"يحذف معرّفات الطلبات المكرّرة تلقائيًا.","why":"الـ assertions تفحص فقط؛ والتنظيف يقوم به كود مثل drop_duplicates()."},{"text":"يسرّع الـ groupby التي تليه.","why":"تضيف الـ assertions قدرًا صغيرًا من العمل؛ قيمتها في الأمان لا في السرعة."}],"answer":0}],"exercise":{"kind":"python","files":["order_items.csv","orders.csv"],"starter":"import pandas as pd\n\nORDERS_FILE = \"orders.csv\"\nITEMS_FILE = \"order_items.csv\"\nQUARTERS = [\"2024Q4\", \"2025Q3\", \"2025Q4\"]\n\n\ndef load_orders(orders_file, items_file):\n items = pd.read_csv(items_file)\n orders = pd.read_csv(orders_file, parse_dates=[\"order_date\"])\n items[\"revenue\"] = items[\"quantity\"] * items[\"unit_price\"] * (1 - items[\"discount\"])\n revenue = items.groupby(\"order_id\", as_index=False)[\"revenue\"].sum()\n return orders.merge(revenue, on=\"order_id\", how=\"left\", validate=\"one_to_one\")\n\n\ndef quarter_summary(df, quarter):\n \"\"\"Return a dict with keys quarter, revenue, orders, aov for one quarter\n (non-cancelled orders only), revenue and aov rounded to 2 decimals.\n Assert that the quarter has at least one order.\"\"\"\n return {}\n\n\ndf = load_orders(ORDERS_FILE, ITEMS_FILE)\n\n# summary: a DataFrame with one row per quarter in QUARTERS, built with quarter_summary\nsummary = None\n\n# Save summary to \"quarter_summary.csv\" without the index\n","solution":"import pandas as pd\n\nORDERS_FILE = \"orders.csv\"\nITEMS_FILE = \"order_items.csv\"\nQUARTERS = [\"2024Q4\", \"2025Q3\", \"2025Q4\"]\n\n\ndef load_orders(orders_file, items_file):\n items = pd.read_csv(items_file)\n orders = pd.read_csv(orders_file, parse_dates=[\"order_date\"])\n items[\"revenue\"] = items[\"quantity\"] * items[\"unit_price\"] * (1 - items[\"discount\"])\n revenue = items.groupby(\"order_id\", as_index=False)[\"revenue\"].sum()\n return orders.merge(revenue, on=\"order_id\", how=\"left\", validate=\"one_to_one\")\n\n\ndef quarter_summary(df, quarter):\n \"\"\"Return a dict with keys quarter, revenue, orders, aov for one quarter\n (non-cancelled orders only), revenue and aov rounded to 2 decimals.\n Assert that the quarter has at least one order.\"\"\"\n kept = df[df[\"status\"] != \"cancelled\"]\n in_q = kept[kept[\"order_date\"].dt.to_period(\"Q\") == quarter]\n assert len(in_q) > 0, f\"no orders in {quarter}\"\n return {\n \"quarter\": quarter,\n \"revenue\": round(in_q[\"revenue\"].sum(), 2),\n \"orders\": len(in_q),\n \"aov\": round(in_q[\"revenue\"].mean(), 2),\n }\n\n\ndf = load_orders(ORDERS_FILE, ITEMS_FILE)\n\nsummary = pd.DataFrame([quarter_summary(df, q) for q in QUARTERS])\nsummary.to_csv(\"quarter_summary.csv\", index=False)\nprint(summary)\n","checks":[{"id":"q4","test":"(lambda r: r['quarter'] == '2025Q4' and abs(float(r['revenue']) - 146825.44) < 0.01 and int(r['orders']) == 642 and abs(float(r['aov']) - 228.70) < 0.01)(quarter_summary(df, '2025Q4'))"},{"id":"other-quarter","test":"(lambda r: int(r['orders']) == 228 and abs(float(r['revenue']) - 52537.10) < 0.01)(quarter_summary(df, '2024Q4'))"},{"id":"uses-argument","test":"int(quarter_summary(df[df['order_date'] < '2025-12-01'], '2025Q4')['orders']) == 457"},{"id":"summary","test":"isinstance(summary, pd.DataFrame) and list(summary['quarter']) == QUARTERS and {'revenue', 'orders', 'aov'} <= set(summary.columns)"},{"id":"saved","test":"__import__('os').path.exists('quarter_summary.csv') and len(pd.read_csv('quarter_summary.csv')) == 3 and 'Unnamed: 0' not in pd.read_csv('quarter_summary.csv').columns"}],"title":"اجعل التقرير الفصلي قابلًا لإعادة التشغيل","prompt":"

أكمل quarter_summary(df, quarter) بحيث تعيد قاموسًا بالمفاتيح quarter وrevenue وorders وaov للربع المعطى (نص مثل "2025Q4")، باستخدام الطلبات غير الملغاة فقط، مع تقريب revenue وaov إلى منزلتين عشريتين. يجب أن تستخدم الوسيط df، لا متغيّرًا عامًا (global)، وأن تتأكّد بـ assert من أن في الربع طلبًا واحدًا على الأقل. ثم ابنِ summary، جدولًا (DataFrame) فيه صف لكل ربع في QUARTERS، واحفظه في quarter_summary.csv دون الفهرس.

\n","hints":["صفِّ مرتين داخل الدالة: احذف الطلبات الملغاة، ثم احتفظ بالصفوف التي يكون فيها df["order_date"].dt.to_period("Q") == quarter.","أعِد قاموسًا: {"quarter": quarter, "revenue": round(in_q["revenue"].sum(), 2), "orders": len(in_q), "aov": round(in_q["revenue"].mean(), 2)}.","تحوّل pd.DataFrame([quarter_summary(df, q) for q in QUARTERS]) قائمة من القواميس إلى جدول (شكل قائمة القواميس من الدرس 1.3). واحفظ بـ summary.to_csv("quarter_summary.csv", index=False)."],"explanation":"

تأخذ الدالة كل ما تحتاجه كوسائط، فيحصل الفحص الذي يمرّر لها جدولًا مُصفّى (طلبات ما قبل ديسمبر فقط) على إجابة مختلفة وصحيحة: 457 طلبًا لربع رابع جزئي. وهذا ما يجعل الدالة آمنة لإعادة الاستخدام. مقارنة عمود من نوع Period بنص مثل "2025Q4" تعمل لأن pandas تحوّل النص إلى فترة. وقائمة القواميس تصبح DataFrame مباشرة، صف لكل قاموس، وهذا يغلق الدائرة مع أول بنية بيانات قابلتها في هذه الدورة. وتُبقي index=False الملف نظيفًا: بدونها يحصل ملف CSV على عمود إضافي بلا اسم فيه أرقام الصفوف.

\n","checkLabels":{"q4":"تعيد quarter_summary(df, "2025Q4") إيرادًا قدره 146,825.44 و642 طلبًا ومتوسط قيمة طلب 228.70","other-quarter":"تعمل مع أرباع أخرى أيضًا، مثل 2024Q4","uses-argument":"تستخدم df المعطى لها، لا جدولًا عامًا","summary":"في summary صف لكل ربع في QUARTERS","saved":"حُفظ quarter_summary.csv بثلاثة صفوف ودون عمود فهرس"}},"words":423,"readMinutes":3}