ArcGIS Notebooks تشغل بيئة دفتر ملاحظات Jupyter التي توفر مساحة عمل مبسطة مبنية على الخلية. يصف هذا الموضوع الأوامر الأساسية وجوانب العمل في Notebooks، بما في ذلك الاختصارات وأفضل الممارسات.
تحديد نوع الخلية
توجد ثلاثة أنواع من الخلايا التي يمكنك استخدامها في أي دفتر ملاحظات. عندما تحدد خلية باستخدام المؤشر، يمكنك تغيير نوع الخلية باستخدام القائمة المنسدلة على شريط الأدوات.
فيما يلي الأنواع الثلاثة المتوفرة:
- تعليمة برمجية- سوف يفسر دفتر الملاحظات جميع المحتويات في خلية التعليمة البرمجية بلغة Python. عند كتابة تعليمة برمجية بلغة Python، أو كتابة سلاسل محددة، مثل from أو علامة التساوي (=)، ستتم مطالبة دفتر الملاحظات بإعادة تلوينها تلقائيًا أو تمييزها لتوضيحها. أي سطر من التعليمة البرمجية يبدأ بعلامة رقم (#)، سيتم تفسيره في صورة تعليق، ملون بالأخضر ومائل، ولن يتم تنفيذه في صورة تعليمة برمجية بواسطة دفتر الملاحظات.
- Markdown- سيفسر دفتر الملاحظات كل المحتويات في خلية Markdown بلغة Markdown. هذه لغة بسيطة لتنسيق النص المنسق، وتستخدم عبر الإنترنت من قبل العملاء مثل GitHub. راجع دليل Markdown عبر الإنترنت للحصول على مرجع لاستخدام Markdown. يؤدي تشغيل خلية Markdown إلى تحويل محتواها إلى نص منسق. سيتم تنسيق أي سطر يبدأ بعلامة أو أكثر من علامات الأرقام (#) في صورة عناوين. يمكنك أيضًا إضافة تعليمات HTML البرمجية الأولية إلى خلايا Markdown.
- Raw NBConvert- لن يقوم دفتر الملاحظات بمعالجة المحتوى في خلية Raw NBConvert. ونادرًا ما يُستخدم هذا النوع من الخلايا.
ملاحظة:
يتوفر أيضًا نوع الخلية عنوان في القائمة المنسدلة. ومع ذلك، لم يعد يُستخدم هذا النوع من الخلايا في بيئات دفتر الملاحظات Jupyter. يؤدي النقر فوق نوع الخلية هذا إلى تحويل الخلية إلى خلية Markdown وإلحاق علامة الرقم (#)، مما يشير إلى عنوان المستوى العلوي في Markdown.
سيؤدي استخدام تعليقات النص المنسق والتعليمة البرمجية إلى جعل دفاتر الملاحظات أكثر قابلية للقراءة وقيمة للمستخدمين الذين تتم مشاركتها معهم.
العمل مع الخلايا
بالنسبة لدفتر الملاحظات، لتنفيذ التعليمة البرمجية، يجب احتواء التعليمة البرمجية في خلية. تسمح لك التعليمة البرمجية الموجودة في الخلايا بتحديد المتغيرات وتشغيل الدوال الموجودة في مكتبات Python.
لتحديد متغير، قم بتشغيل خلية تحتوي على عبارة متغير، بما في ذلك علامة تساوي (=). على سبيل المثال، يبدأ قالب دفتر الملاحظات الافتراضي بتعريف متغير gis. إذا قمت بتشغيل خلية تحتوي على اسم المتغير فقط، gis، فسيُرجع دفتر الملاحظات عنوان URL الخاص ببوابة ArcGIS Enterprise الإلكترونية في صورة إخراج.
ملاحظة:
لن تعمل أوامر iPython التي تستخدم علامات التعجب، مثل !cd <directory>، لتغيير الدلائل من سطر الأوامر في ArcGIS Notebooks. بدلاً من ذلك، استخدم الأوامر بدون علامات التعجب، مثل cd <directory>.
ملاحظة:
عند تأليف دفاتر الملاحظات، استخدم المسارات الكاملة للدلائل والملفات في دليل مساحة العمل.
على سبيل المثال، استخدم /arcgis/home/test.gdb بدلاً من home/test.gdb.
لتشغيل دالة Python، قم بتوفير بناء جملة الدالة وأية وسيطات تتطلبها الدالة أو تقبلها. راجع قسم استخدام الدوال في خلية أدناه لمعرفة المزيد.
يمكنك إنشاء خلية بالضغط على Shift+Enter، أو بالنقر فوق الزر إدراج على شريط القائمة، الذي يمنحك خيار إدراج خلية جديدة فوق أي خلية حالية أو أسفلها.
خيارات شريط أدوات الخلية
يمكنك تضمين معلومات إضافية حول الخلايا الفردية في دفتر ملاحظات باستخدام الخيارات الموجودة في شريط أدوات الخلية:
- لا شيء - عدم إظهار أشرطة أدوات الخلية.
- تحرير البيانات التعريفية-إدخال البيانات التعريفية لكل خلية باستخدام JSON.
- تنسيق خلية أولية - تسمح لك الخلايا الأولية بكتابة الناتج مباشرةً؛ لا يتم تقييم محتوى هذه الخلايا بواسطة دفتر الملاحظات.
- عرض الشرائح—تحديد كيفية عرض كل خلية في عرض الشرائح. مفيد عند عرض كود.
- المرفقات-إدارة المرفقات ذات الصلة داخل كل خلية في مساحة عمل دفتر الملاحظات.
- العلامات-إنشاء العلامات وإدارتها لكل خلية داخل مساحة عمل دفتر الملاحظات.
عند تشغيل أي من هذه الخيارات، يظهر شريط أعلى كل خلية في دفتر الملاحظات. يمكن تشغيل خيار واحد فقط في كل مرة، ولكن تظل أي معلومات تضيفها إلى شريط الأدوات حتى عند إيقاف التشغيل. يمكنك تغيير خيارات شريط أدوات الخلية بالنقر فوق عرض > شريط أدوات الخلية.
يمكن استخدام خيار العلامات عند تحضير دفتر ملاحظات ليتم جدولته أو تنفيذه عن بُعد. تقدم عملية تنفيذ دفتر الملاحظات خيار إدراج معلمات كخلية جديدة في وقت التنفيذ، مثل بيانات اعتماد الحساب أو المتغيرات التي يجب تحديدها. يمكنك تعيين المكان في دفتر الملاحظات حيث تتم إضافة هذه الخلية الجديدة عن طريق إضافة العلامة parameters إلى خلية في دفتر الملاحظات الخاص بك. يتم إدراج الخلية الجديدة بعد هذه الخلية. خلية واحدة فقط مع علامة parameters يتم التعرف عليها من قبل العملية.
استيراد المكتبات والوحدات
في قالب دفتر الملاحظات الافتراضي، تقوم ArcGIS Notebooks فقط باستيراد وحدة gis من ArcGIS API for Python. عادة، ستحتاج إلى استخدام مكتبات Python إضافية متوفرة في وقت تشغيل دفتر الملاحظات الخاص بك. لاستخدام هذه المكتبات، قم بتشغيل أمر import.
شاهد جميع مكتبات Python المتوفرة في ArcGIS Notebooks
أنشئ خلية واكتب import <library>، ثم قم بتشغيل الخلية.
في ArcGIS API for Python وArcPy، وفي بعض الحالات الأخرى، يتم ترتيب مكتبات Python في وحدات. للوصول إلى المكتبات داخل وحدة، أعلن عن الوحدة للوصول باستخدام عبارة from، ثم أعلن عن مكتبة باستخدام عبارة import. على سبيل المثال، لاستدعاء مكتبة WebScene من وحدة mapping في ArcGIS API for Python، يمكنك تشغيل الأمر التالي في خلية:
from arcgis.mapping import WebSceneتتضمن ArcGIS Notebooks معلم الإكمال التلقائي عند تشغيل الخلايا. يمكنك استخدامه لمساعدتك في العثور على المكتبات والوحدات التي تحتاج إليها. في الخلية، اكتب الجزء الأول من الأمر، ثم اضغط على علامة التبويب لتنشيط معلم الإكمال التلقائي. وسوف يوفر القيم الممكنة التي يمكن أن تكمل الأمر.
على سبيل المثال، إذا كتبت arcgis. ثم ضغطت على علامة التبويب، فسيقوم دفتر الملاحظات بتوفير قائمة منسدلة لجميع الوحدات المتاحة في ArcGIS API for Python. يمكنك استخدام السهمين لأعلى ولأسفل للتنقل في القائمة؛ عندما تجد الخيار الذي تريده، اضغط على إدخال لإدراجه في سطر التعليمة البرمجية.
لمعرفة المزيد عن كيفية عمل ArcGIS API for Python وArcPy في دفاتر الملاحظات، راجع الموضوعات التالية:
استخدام الدوال في خلية
لإجراء تحليل والعمل مع البيانات في دفاتر الملاحظات، يمكنك استخدام دوال Python. يتم تضمين الدوال داخل مكتبات Python، وغالبًا ما تأخذ وسيطات الإدخال لتحديد كيفية تنفيذها والمحتوى الذي سيتم تنفيذه عليها.
يمكن أن تساعدك أداة الإكمال التلقائي لدفتر الملاحظات في العثور على الدوال من خلال توفير قائمة منسدلة لما هو متاح. بالنسبة لأي مكتبة bar، اكتب bar. واضغط على علامة التبويب لرؤية الدوال المتوفرة بداخلها.
على سبيل المثال، لعرض الأدوات المتاحة في مكتبة تلخيص البيانات لوحدة arcgis.features، أدخل التعليمة البرمجية التالية واضغط على علامة التبويب:
features.summarize_data.ستعرض أداة الإكمال التلقائي قائمة منسدلة بالأدوات المتاحة في المكتبة.
في كثير من الأحيان، يحتوي الأمر في دفتر الملاحظات على الوسيطات المطلوبة أو الاختيارية—وهي معلمات توفر معلومات لتنفيذ أمر ما. إذا انتهى بناء جملة الأمر بمجموعة فارغة من الأقواس (())، فهذا يعني أن الأمر يتطلب أو قد يشتمل على وسائط اختيارية يمكنك إضافتها.
أدخل الوسيطات داخل الأقواس، مع الفصل بين الوسيطات المتعددة بفواصل. لعرض سلسلة الوسيطات المطلوبة والاختيارية لأي دالة، استبدل الأقواس الفارغة بعلامة استفهام وقم بتشغيل الخلية. سيؤدي هذا إلى عرض docstring الخاص بالخلية، الذي يسرد جميع الوسيطات.
على سبيل المثال، تتطلب جميع الأدوات التي تتوفر من خلال جزء التحليل الخاص بمحرر دفتر الملاحظات وسيطات. ستؤدي إضافة أداة من هذا الجزء إلى خلية إلى إدراج بناء جملة ArcGIS API for Python للأداة، التي تنتهي بأقواس فارغة. إذا حاولت تشغيل بناء الجملة هذا في خلية بدون توفير وسيطة واحدة أو أكثر، فستفشل الخلية وستعرض رسالة خطأ.
لتشغيل أداة تجميع النقاط في مكتبة تلخيص البيانات، فإنه يمكنك تحديد موقع الأداة في جزء التحليل وإضافتها إلى خلية جديدة، أو كتابة بناء جملة الأداة كما يلي:
features.summarize_data.aggregate_points()لعرض قائمة الوسيطات الخاصة بالأداة، قم بتعديل بناء الجملة كما يلي وقم بتشغيل الخلية:
features.summarize_data.aggregate_points?يفتح هذا نافذة مرجع docstring للأداة. يحتوي هذا المرجع على أزرار لتوسيع النافذة أو إغلاقها في الزاوية اليمنى العلوية.
عندما تعمل على هذه الخلية، ضع في اعتبارك ما يلي:
- بالنسبة لأي دالة foo()، اكتب foo؟ واضغط على إدخال لإظهار سلسلة docstring للدالة، التي تصف الدالة.
- إذا بدأت خلية بعلامة !، فسيتم تشغيل محتويات الخلية كأمر bash في حاوية دفتر الملاحظات.
تشغيل خلية
عندما تقوم بتشغيل خلية، يتم تنفيذ التعليمة البرمجية الخاصة بها، ويتم تنفيذ جميع العمليات داخلها. يمكنك فقط تشغيل خلية كاملة، وليس قسمًا فرعيًا للخلية أو سطرًا معينًا من التعليمة البرمجية. يمكن أن تتكون الخلايا من سطر واحد أو عدة أسطر من التعليمة البرمجية.
لتشغيل خلية محددة، انقر فوق الزر تشغيل على شريط الأدوات، أو انقر فوق الخلايا > تشغيل الخلايا. يمكنك أيضًا الضغط على Ctrl+Enter لتشغيل الخلية التي يشير إليها مؤشر الماوس.
لإيقاف الخلية التي يتم تشغيلها يدويًا، انقر فوق مقاطعة > Kernel. يمكنك أيضًا النقر فوق زر الإيقاف المربّع في شريط الأدوات.
على يسار كل خلية تعليمة برمجية يوجد عنصر In [ ]. إذا لم يتم تشغيل الخلية بعد، أو إذا تم مسح خلية تم تشغيلها من قبل للإخراج، فسيكون القوس فارغًا. أثناء تشغيل الخلية، تحتوي على علامة نجمة: In [*]. عند اكتمال تشغيل خلية، يتم ملء قوس In [ ] الخاص بها برقم يشير إلى ترتيب الخلايا التي تم تشغيلها. نظرًا لأنه يمكن تشغيل الخلايا في دفتر الملاحظات بأي ترتيب ويمكن تشغيلها عدة مرات، فقد لا تكون أرقام In [ ] الموجودة في خلايا دفتر الملاحظات في ترتيب تسلسلي.
ملاحظة:
تحتفظ خلايا Markdown بعنصر In [ ] حتى يتم تشغيلها، وعند هذه النقطة يختفي العنصر ويصبح محتوى الخلية نصًا منسقًا.
عند الوصول إلى ناتج من سطر تعليمة برمجية في خلية تقوم بتشغيلها، يتم عرض الناتج في دفتر الملاحظات أسفل الخلية التي تم تنفيذها. ويوجد بجوار الناتج عنصر Out [ ]، الذي يطابق ما يوجد في عنصر In [ ] للخلية المقابلة.
التعامل مع kernel
عند تشغيل دفتر ملاحظات جديد، يتم تشغيل kernel معه. يعمل kernel هذا على تنفيذ التعليمة البرمجية التي تشغلها في دفتر الملاحظات. عند قيامك بتشغيل خلايا في دفتر الملاحظات (مع ملء عناصر In [ ] الخاصة بها)، يتم تخزين المتغيرات التي حددتها في الخلايا المنفذة في ذاكرة kernel.
لإعادة تشغيل kernel الخاص بدفتر الملاحظات ومسح متغيرات الذاكرة، انقر فوق إعادة تشغيل > Kernel. لإعادة تشغيل kernel، فقم بمسح المتغيرات داخل الذاكرة وتشغيل جميع الخلايا في دفتر الملاحظات بالتتالي، ثم انقر فوق Kernel > إعادة التشغيل وتشغيل الكل.
عند الانتهاء بنشاط باستخدام جهاز دفتر ملاحظات، انقر فوق إيقاف تشغيل > Kernel لإيقاف تشغيل kernel دفتر الملاحظات ومسح كل المتغيرات في الذاكرة. سيتوقف تشغيل kernel، ولكن لن يتم مسح مخرجات الخلايا التي تم تشغيلها.
عند ترك دفتر الملاحظات في وضع الخمول لفترة زمنية طويلة، سيتم إيقاف تشغيل kernel ومسح كل قيم الذاكرة تلقائيًا. تقدر هذه الفترة الزمنية افتراضيًا بـ 24 ساعة، ولكن يمكن أن يحددها مسؤول الموقع لتكون أقصر أو أطول.