28  كوارتو (Quarto)

28.1 مقدمة

يوفر Quarto إطار تأليف موحداً لعلم البيانات، حيث يجمع بين الكود، ونتائجه، والنص الشارح. مستندات Quarto قابلة لإعادة الإنتاج والتكرار بالكامل، وتدعم العشرات من صيغ المخرجات، مثل ملفات PDF، وملفات Word، والعروض التقديمية، وغيرها الكثير.

تم تصميم ملفات Quarto لتُستخدم بثلاث طرق رئيسية:

1. للتواصل مع متخذي القرار، الذين يرغبون في التركيز على الاستنتاجات، وليس الكود البرمجي وراء التحليل.

2. للتعاون مع علماء البيانات الآخرين (بما في ذلك نفسك في المستقبل!)، المهتمين بكل من استنتاجاتك وكيفية الوصول إليها (أي الكود).

3. كبيئة مخصصة لـ ممارسة علم البيانات، كدفتر ملاحظات معملي حديث حيث يمكنك تسجيل ليس فقط ما قمت به، ولكن أيضاً ما كنت تفكر فيه أثناء العمل.

نظام Quarto هو أداة واجهة سطر أوامر (Command Line Interface - CLI) وليس حزمة R. هذا يعني أن التعليمات والمساعدة غير متوفرة بشكل عام عبر رمز ?. بدلاً من ذلك، أثناء عملك خلال هذا الفصل واستخدامك لـ Quarto في المستقبل، يجب عليك الرجوع إلى توثيق Quarto الرسمي.

إذا كنت من مستخدمي R Markdown، فقد تفكر قائلاً “يبدو Quarto شبيهاً جداً بـ R Markdown”. وأنت لست مخطئاً! يقوم Quarto بتوحيد وظائف العديد من الحزم في منظومة R Markdown (مثل rmarkdown و bookdown و distill و xaringan وغيرها) في نظام واحد متسق، بالإضافة إلى توسيعه بدعم أصيل للغات برمجية متعددة مثل Python و Julia بالإضافة إلى R. بطريقة ما، يعكس Quarto كل ما تم تعلمه من توسيع ودعم منظومة R Markdown على مدار أكثر من عقد من الزمان.

28.1.1 المتطلبات المسبقة

أنت بحاجة إلى أداة سطر الأوامر الخاصة بـ كوارتو (Quarto CLI)، لكنك لا تحتاج إلى تثبيتها أو تحميلها صراحةً، حيث يقوم RStudio بذلك تلقائياً عند الحاجة.

28.2 أساسيات Quarto

هذا ملف Quarto — وهو ملف نصي عادي يحمل الامتداد .qmd:

---
title: "Diamond sizes"
date: 2022-09-12
format: html
---

```{r}
#| label: setup
#| include: false

library(tidyverse)

smaller <- diamonds |> 
  filter(carat <= 2.5)
```

We have data about `r nrow(diamonds)` diamonds.
Only `r nrow(diamonds) - nrow(smaller)` are larger than 2.5 carats.
The distribution of the remainder is shown below:

```{r}
#| label: plot-smaller-diamonds
#| echo: false

smaller |> 
  ggplot(aes(x = carat)) + 
  geom_freqpoly(binwidth = 0.01)
```

يحتوي الملف على ثلاثة أنواع رئيسية ومهمة من المحتوى:

1. ترويسة YAML (اختيارية) محاطة بـ ---.
2. كتل (Chunks) من كود R محاطة بـ ```.
3. نص عادي ممزوج بتنسيقات نصية بسيطة مثل # العناوين و _الخط المائل_.

يُظهر الشكل 28.1 مستند .qmd في RStudio باستخدام واجهة الدفتر (notebook interface) حيث تتداخل الأكواد والمخرجات. يمكنك تشغيل كل كتلة كود بالنقر فوق أيقونة التشغيل (تبدو كزر التشغيل Play في الجزء العلوي من الكتلة)، أو بالضغط على Cmd/Ctrl + Shift + Enter. يقوم RStudio بتنفيذ الكود وعرض النتائج مباشرة أسفل الكود.

الشكل 28.1: مستند Quarto في RStudio. الأكواد والمخرجات متداخلة في المستند، حيث يظهر الرسم البياني أسفل الكود مباشرة.

إذا كنت لا تحب رؤية الرسوم البيانية والمخرجات داخل المستند وتفضل الاستفادة من لوحتي Console و Plot في RStudio، يمكنك النقر على أيقونة الترس بجوار زر “Render” والتحويل إلى “Chunk Output in Console”، كما هو موضح في الشكل 28.2.

الشكل 28.2: مستند Quarto في RStudio مع عرض الرسم البياني في لوحة Plots.

لإنشاء تقرير كامل يحتوي على جميع النصوص والأكواد والنتائج، انقر فوق “Render” أو اضغط على Cmd/Ctrl + Shift + K. يمكنك أيضاً القيام بذلك برمجياً باستخدام الأمر quarto::quarto_render("diamond-sizes.qmd"). سيعرض هذا التقرير في لوحة العرض (Viewer pane) كما هو موضح في الشكل 28.3 وينشئ ملف HTML.

الشكل 28.3: مستند Quarto في RStudio مع المستند المعالج (rendered) في لوحة العرض Viewer.

عند معالجة (render) المستند، يرسل Quarto ملف .qmd إلى knitr (https://yihui.org/knitr/)، والذي ينفذ جميع كتل الأكواد وينشئ مستند ماركداون (.md) جديداً يتضمن الكود ومخرجاته. ثم تتم معالجة ملف الماركداون الناتج عن knitr بواسطة pandoc (https://pandoc.org)، وهو المسؤول عن إنشاء الملف النهائي. تُوضح هذه العملية في الشكل 28.4. ميزة مسار العمل المكون من خطوتين هي أنه يمكنك إنشاء مجموعة واسعة جداً من صيغ المخرجات، كما ستتعلم في الفصل 29.

الشكل 28.4: مخطط لمسار عمل Quarto من qmd إلى knitr، إلى md، إلى pandoc، وصولاً إلى المخرجات بصيغ PDF أو MS Word أو HTML.

لبدء العمل على ملف .qmd الخاص بك، اختر من شريط القوائم: File > New File > Quarto Document…. سيقوم برنامج RStudio بفتح معالج إعداد (wizard) يمكنك استخدامه لتعبئة ملفك مسبقاً ببعض المحتويات المفيدة التي تذكرك بكيفية عمل الميزات الرئيسة لنظام Quarto.

تتطرق الأقسام التالية إلى المكونات الثلاثة لمستند Quarto بمزيد من التفصيل: نص الماركداون، وكتل الأكواد البرمجية، وترويسة YAML.

28.2.1 تمارين

1. أنشئ مستند Quarto جديداً باستخدام File > New File > Quarto Document. اقرأ التعليمات. تدرب على تشغيل الكتل بشكل فردي. ثم قم بمعالجة (render) المستند بالنقر فوق الزر المخصص ثم باستخدام اختصار لوحة المفاتيح المناسب. تحقق من أنه يمكنك تعديل الكود، وإعادة تشغيله، ورؤية المخرجات المعدلة.

2. أنشئ مستند Quarto جديداً لكل صيغة من الصيغ الثلاث المدمجة: HTML و PDF و Word. قم بمعالجة (render) كل من المستندات الثلاثة. كيف تختلف المخرجات؟ كيف تختلف المدخلات؟ (قد تحتاج إلى تثبيت LaTeX لتتمكن من بناء مخرجات PDF — سيطلب منك RStudio ذلك إذا كان ضرورياً).

28.3 المحرر المرئي (Visual editor)

يوفر المحرر المرئي (Visual editor) في RStudio واجهة WYSIWYM (ما تراه هو ما تعنيه) لتأليف مستندات Quarto. في الكواليس، يُكتب النص في مستندات Quarto (ملفات .qmd) بلغة Markdown، وهي مجموعة خفيفة من القواعد والتنسيقات للملفات النصية العادية. في الواقع، يستخدم Quarto لغة Pandoc markdown (نسخة موسعة قليلاً يفهمها Quarto)، بما في ذلك الجداول، والمراجع، والإحالات المرجعية، والحواشي السفلية، وكتل divs/spans، وقوائم التعريفات، والخصائص، و HTML/TeX الخام، بالإضافة إلى دعم تنفيذ خلايا الكود وعرض مخرجاتها بشكل مباشر. بينما تم تصميم Markdown ليكون سهلاً في القراءة والكتابة، كما ستري في قسم 28.4، فإنه لا يزال يتطلب تعلم بناء جمل (syntax) جديد. لذلك، إذا كنت جديداً على المستندات الحسابية مثل ملفات .qmd ولكن لديك خبرة في استخدام أدوات مثل Google Docs أو MS Word، فإن أسهل طريقة لبدء العمل مع Quarto في RStudio هي المحرر المرئي.

في المحرر المرئي، يمكنك إما استخدام الأزرار الموجودة في شريط القوائم لإدراج الصور والجداول والإحالات المرجعية وما إلى ذلك، أو يمكنك استخدام الاختصار الشامل ⌘ + / أو Ctrl + / لإدراج أي شيء تقريباً. إذا كنت في بداية السطر (كما هو موضح في الشكل 28.5)، يمكنك أيضاً إدخال / فقط لاستدعاء الاختصار.

الشكل 28.5: المحرر المرئي في Quarto.

يتم تسهيل إدراج الصور وتخصيص كيفية عرضها أيضاً باستخدام المحرر المرئي. يمكنك إما لصق صورة من الحافظة مباشرة في المحرر المرئي (وسيقوم RStudio بوضع نسخة من تلك الصورة في مجلد المشروع وربطها)، أو يمكنك استخدام قائمة Insert > Figure / Image في المحرر المرئي للانتقال إلى الصورة التي تريد إدراجها أو لصق عنوان URL الخاص بها. بالإضافة إلى ذلك، باستخدام القائمة نفسها، يمكنك تغيير حجم الصورة وإضافة نص توضيحي، ونص بديل، ورابط.

يحتوي المحرر المرئي على العديد من الميزات الأخرى التي لم نذكرها هنا والتي قد تجدها مفيدة كلما اكتسبت خبرة في التأليف باستخدامها.

والأهم من ذلك، بينما يعرض المحرر المرئي محتواك بالتنسيق المفعل، فإنه يحفظ محتواك في الكواليس بلغة Markdown العادية، ويمكنك التنقل والتبديل بين المحرر المرئي ومحرر المصدر (Source editor) لعرض محتواك وتعديله باستخدام أي من الأداتين.

28.3.1 تمارين

1. أعد إنشاء المستند الموضح في الشكل 28.5 باستخدام المحرر المرئي.

2. باستخدام المحرر المرئي، أدخل كتلة كود باستخدام قائمة Insert ثم أداة إدراج أي شيء (insert anything tool).

3. باستخدام المحرر المرئي، اكتشف كيفية القيام بما يلي:

   أ. إضافة حاشية سفلية (footnote).
   ب. إضافة خط أفق الفاصل (horizontal rule).
   ج. إضافة اقتباس بارز / اقتباس كتلي (block quote).

4. في المحرر المرئي، انتقل إلى Insert > Citation وأدرج استشهاداً بالورقة العلمية المعنونة Welcome to the Tidyverse باستخدام المعرف الرقمي للكائن (DOI)، وهو 10.21105/joss.01686. قم بمعالجة المستند واكتشف كيف يظهر المرجع في المستند. ما التغيير الذي تلاحظه في YAML الخاص بمستندك؟

28.4 محرر المصدر (Source editor)

يمكنك أيضاً تحرير مستندات Quarto باستخدام محرر المصدر (Source editor) في RStudio، دون مساعدة من المحرر المرئي. بينما سيشعر المحرر المرئي بالآلفة لأولئك الذين لديهم خبرة في الكتابة باستخدام أدوات مثل Google Docs، فإن محرر المصدر سيشعر بالآلفة لأولئك الذين لديهم خبرة في كتابة نص برمجيات R أو مستندات R Markdown. يمكن أن يكون محرر المصدر مفيداً أيضاً لتصحيح أي أخطاء في بناء جمل Quarto حيث يكون من الأسهل غالباً اكتشافها في النص العادي.

يوضح الدليل أدناه كيفية استخدام Pandoc’s Markdown لتأليف مستندات Quarto في محرر المصدر.

## Text formatting

*italic* **bold** ~~strikeout~~ `code`

superscript^2^ subscript~2~

[underline]{.underline} [small caps]{.smallcaps}

## Headings

# 1st Level Header

## 2nd Level Header

### 3rd Level Header

## Lists

-   Bulleted list item 1

-   Item 2

    -   Item 2a

    -   Item 2b

1.  Numbered list item 1

2.  Item 2.
    The numbers are incremented automatically in the output.

## Links and images

<http://example.com>

[linked phrase](http://example.com)

![optional caption text](quarto.png){fig-alt="Quarto logo and the word quarto spelled in small case letters"}

## Tables

| First Header | Second Header |
|--------------|---------------|
| Content Cell | Content Cell  |
| Content Cell | Content Cell  |

أفضل طريقة لتعلم هذه القواعد هي ببساطة تجربتها. سيستغرق الأمر بضعة أيام، ولكن سرعان ما ستصبح طبيعة ثانية، ولن تحتاج إلى التفكير فيها. إذا نسيت، يمكنك الحصول على ورقة مرجعية سريعة مفيدة عبر Help > Markdown Quick Reference.

28.4.1 تمارين

1. تدرب على ما تعلمته من خلال إنشاء سيرة ذاتية (CV) موجزة. يجب أن يكون العنوان هو اسمك، ويجب أن تتضمن عناوين لـ (على الأقل) التعليم أو العمل. يجب أن يتضمن كل قسم من الأقسام قائمة نقطية بالوظائف/الدرجات العلمية. قم بتمييز السنة بخط عريض.

2. باستخدام محرر المصدر والمرجع السريع لـ Markdown، اكتشف كيفية القيام بما يلي:

   أ. إضافة حاشية سفلية.
   ب. إضافة خط أفقي فاصل.
   ج. إضافة اقتباس كتلي.

3. انسخ والمصق محتويات diamond-sizes.qmd من https://github.com/hadley/r4ds/tree/main/quarto في مستند Quarto محلي. تحقق من إمكانية تشغيله، ثم أضف نصاً بعد المضلع التكراري يصف أبرز ميزاته.

4. أنشئ مستنداً في Google Docs أو MS Word (أو حدد مستنداً أنشأته سابقاً) يحتوي على بعض المحتويات مثل العناوين والروابط والنصوص المنسقة وما إلى ذلك. انسخ محتويات هذا المستند والصقها في مستند Quarto في المحرر المرئي. ثم، انتقل إلى محرر المصدر وافحص الكود المصدري.

28.5 كتل الأكواد البرمجية (Code chunks)

لتشغيل كود داخل مستند Quarto، تحتاج إلى إدراج كتلة كود (chunk). هناك ثلاث طرق للقيام بذلك:

1. اختصار لوحة المفاتيح Cmd + Option + I / Ctrl + Alt + I.

2. أيقونة زر “Insert” في شريط أدوات المحرر.

3. كتابة محددات الكتلة يدويًا ```{r} و ```.

نوصيك بتعلم اختصار لوحة المفاتيح. سيوفر لك الكثير من الوقت على المدى الطويل!

يمكنك الاستمرار في تشغيل الكود باستخدام اختصار لوحة المفاتيح الذي تعرفه وتحبه الآن (كما نأمل!): Cmd/Ctrl + Enter. ومع ذلك، تحصل الكتل على اختصار لوحة مفاتيح جديد: Cmd/Ctrl + Shift + Enter، والذي يشغل جميع الأكواد في الكتلة. فكر في الكتلة كدالّة. يجب أن تكون الكتلة قائمة بذاتها نسبياً، وتركز على مهمة واحدة.

تصف الأقسام التالية ترويسة الكتلة التي تتكون من ```{r}، تليها تسمية التسمية التوضيحية الاختيارية وخيارات الكتل المختلفة الأخرى، كل منها في سطر خاص به، ومميزة بـ #|.

28.5.1 تسمية الكتلة (Chunk label)

يمكن إعطاء الكتل تسمية اختيارية، على سبيل المثال:

```{r}
#| label: simple-addition
1 + 1
```

#> [1] 2

هذا يوفر ثلاث مزايا رئيسية:

1. يمكنك التنقل بسهولة أكبر إلى كتل معينة باستخدام مستكشف الكود المنسدل في أسفل يسار محرر النصوص البرمجية:

2. ستكون للرسوم البيانية التي تنتجها الكتل أسماء مفيدة تجعل من السهل استخدامها في مكان آخر. المزيد عن ذلك في قسم 28.6.

3. يمكنك إعداد شبكات من الكتل المخزنة مؤقتاً (cached) لتجنب إعادة إجراء الحسابات المكلفة عند كل تشغيل. المزيد عن ذلك في قسم 28.8.

يجب أن تكون تسميات الكتل قصيرة ولكن معبرة ولا تحتوي على مسافات. نوصي باستخدام الشرطات (-) للفصل بين الكلمات (بدلاً من الشرطات السفلية _) وتجنب الرموز الخاصة الأخرى في تسميات الكتل.

أنت حر عموماً في تسمية الكتلة الخاصة بك كما تحب، ولكن هناك اسم كتلة واحد يمنح سلوكاً خاصاً: setup. عندما تكون في وضع الدفتر، سيتم تشغيل الكتلة المسمى setup تلقائياً مرة واحدة، قبل تشغيل أي كود آخر.

بالإضافة إلى ذلك، لا يمكن تكرار تسميات الكتل. يجب أن تكون تسمية كل كتلة فريدة من نوعها.

28.5.2 خيارات الكتل (Chunk options)

يمكن تخصيص مخرجات الكتلة باستخدام الخيارات، وهي حقول يتم تزويدها لترويسة الكتلة. يوفر Knitr ما يقرب من 60 خياراً يمكنك استخدامها لتخصيص كتل الأكواد البرمجية الخاصة بك. سنغطي هنا أهم خيارات الكتل التي ستستخدمها بشكل متكرر. يمكنك رؤية القائمة الكاملة على https://yihui.org/knitr/options/.

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

• eval: false يمنع تقييم الكود وتنفيذه. (وبالطبع إذا لم يتم تشغيل الكود، لن يتم إنشاء أي نتائج). هذا مفيد لعرض كود توضيحي، أو لتعطيل كتلة كبيرة من الكود دون وضع علامة التعليق على كل سطر.

• include: false يشغل الكود، ولكنه لا يظهر الكود أو النتائج في المستند النهائي. استخدم هذا لكود الإعداد الذي لا تريد أن يربك تقريرك.

• echo: false يمنع عرض الكود، لكنه يظهر النتائج في الملف النهائي. استخدم هذا عند كتابة تقارير موجهة لأشخاص لا يريدون رؤية كود R الأساسي.

• message: false أو warning: false يمنع ظهور الرسائل أو التحذيرات في الملف النهائي.

• results: hide يخفي المخرجات المطبوعة؛ بينما fig-show: hide يخفي الرسوم البيانية.

• error: true يجعل المعالجة تستمر حتى لو أرجع الكود خطأً. نادراً ما يكون هذا شيئاً ترغب في تضمينه في النسخة النهائية من تقريرك، ولكنه قد يكون مفيداً جداً إذا كنت بحاجة إلى تصحيح أخطاء ما يحدث بدقة داخل ملف .qmd الخاص بك. كما أنه مفيد إذا كنت تدرس R وتريد تضمين خطأ عمداً. الإعداد الافتراضي، error: false يجعل المعالجة تفشل إذا كان هناك خطأ واحد في المستند.

يتم إدراج كل خيار من خيارات الكتلة هذه في ترويسة الكتلة، متبوعاً بـ #|، على سبيل المثال، في الكتلة التالية لا تطبع النتيجة لأن الخيار eval تم ضبطه على false.

```{r}
#| label: simple-multiplication
#| eval: false
2 * 2
```

يلخص الجدول التالي أنواع المخرجات التي يقوم كل خيار بإخفائها وإلغائها:

الخيار	تشغيل الكود	إظهار الكود	المخرجات	الرسوم	الرسائل	التحذيرات
eval: false	X		X	X	X	X
include: false		X	X	X	X	X
echo: false		X
results: hide			X
fig-show: hide				X
message: false					X
warning: false						X

28.5.3 الخيارات العامة (Global options)

كلما عملت أكثر مع knitr، ستكتشف أن بعض خيارات الكتل الافتراضية لا تناسب احتياجاتك وتريد تغييرها.

يمكنك القيام بذلك عن طريق إضافة الخيارات المفضلة في YAML الخاص بالمستند، تحت قسم execute. على سبيل المثال، إذا كنت تُعد تقريراً لجمهور لا يحتاج إلى رؤية الكود الخاص بك بل يكتفي بالنتائج والسرد النصي فقط، فقد تضبط echo: false على مستوى المستند بأكمله. سيؤدي ذلك إلى إخفاء الكود افتراضياً، وبالتالي إظهار الكتل التي تختار إظهارها صراحةً فقط (باستخدام echo: true). قد تفكر في ضبط message: false و warning: false، لكن ذلك سيجعل تصحيح المشاكل أكثر صعوبة لأنك لن ترى أي رسائل تحذيرية في المستند النهائي.

title: "تقريري"
execute:
  echo: false

نظراً لأن Quarto مصمم ليكون متعدد اللغات (يعمل مع R بالإضافة إلى لغات أخرى مثل Python و Julia إلخ)، فإن جميع خيارات knitr ليست متوفرة على مستوى تنفيذ المستند لأن بعضها يعمل فقط مع knitr وليس مع المحركات الأخرى التي يستخدمها Quarto لتشغيل الكود بلغات أخرى (مثل Jupyter). ومع ذلك، لا يزال بإمكانك ضبط هذه الخيارات كخيارات عامة لمستندك تحت الحقل knitr، ضمن opts_chunk. على سبيل المثال، عند كتابة الكتب والدروس التعليمية نحدد الخيارات التالية:

title: "درس تعليمي"
knitr:
  opts_chunk:
    comment: "#>"
    collapse: true

يستخدم هذا تنسيق التعليق المفضل لدينا ويضمن دمج الكود والمخرجات معاً بشكل وثيق.

28.5.4 الأكواد المدمجة في النص (Inline code)

هناك طريقة أخرى لتضمين كود R داخل مستند Quarto: مباشرة في النص العادي، باستخدام: `r `. يمكن أن يكون هذا مفيداً جداً إذا ذكرت خصائص بياناتك في النص. على سبيل المثال، كان مثال المستند المستخدم في بداية الفصل يحتوي على:

لدينا بيانات حول `r nrow(diamonds)` ألماسة. فقط `r nrow(diamonds) - nrow(smaller)` هي أكبر من 2.5 قيراط. وتوزيع المتبقي موضح أدناه:

عند معالجة التقرير، يتم إدراج نتائج هذه الحسابات في النص مباشرة:

لدينا بيانات حول 53940 ألماسة. فقط 126 هي أكبر من 2.5 قيراط. وتوزيع المتبقي موضح أدناه:

عند إدراج الأرقام في النص، تكون الدالّة format() صديقتك الوفية. فهي تسمح لك بتحديد عدد الأرقام digits حتى لا تطبع بدرجة غير معقولة من الدقة، وفصل المئات big.mark لجعل الأرقام أسهل في القراءة. يمكنك دمج هذه العناصر في دالّة مساعدة:

comma <- function(x) format(x, digits = 2, big.mark = ",")
comma(3452345)
#> [1] "3,452,345"
comma(.12358124331)
#> [1] "0.12"

28.5.5 تمارين

1. أضف قسماً يستكشف كيف تتغير أحجام الألماس حسب القطع واللون والنقاء. افترض أنك تكتب تقريراً لشخص لا يعرف R، وبدلاً من ضبط echo: false في كل كتلة، قم بضبط خيار عام على مستوى المستند.

2. قم بتنزيل diamond-sizes.qmd من https://github.com/hadley/r4ds/tree/main/quarto. أضف قسماً يصف أكبر 20 ألماسة، بما في ذلك جدول يعرض أهم صفاتها.

3. عدّل diamonds-sizes.qmd لاستخدام label_comma() لإنتاج مخرجات منسقة بشكل جميل. تضمين أيضاً النسبة المئوية للألماس الذي يزيد حجمه عن 2.5 قيراط.

28.6 الرسوم البيانية والأشكال (Figures)

يمكن أن تكون الرسوم البيانية والأشكال في مستند Quarto مدمجة (مثل ملف PNG أو JPEG) أو تم إنشاؤها كنتاج لكتلة كود برمجية.

لإدراج صورة من ملف خارجي، يمكنك استخدام قائمة Insert في المحرر المرئي في RStudio واختيار Figure / Image. سيعرض هذا نافذة منبثقة حيث يمكنك الانتقال إلى الصورة التي تريد إدراجها بالإضافة إلى إضافة نص بديل أو نص توضيحي لها وتعديل حجمها. في المحرر المرئي، يمكنك أيضاً ببساطة لصق صورة من الحافظة الخاصة بك في المستند وسيضع RStudio نسخة من تلك الصورة في مجلد المشروع الخاص بك.

إذا قمت بتضمين كتلة كود تنشئ رسمًا بيانيًا (على سبيل المثال، تتضمن استدعاءً لـ ggplot())، فسيتم تضمين الشكل الناتج تلقائياً في مستند Quarto الخاص بك.

28.6.1 أبعاد الرسوم البيانية (Figure sizing)

يتمثل التحدي الأكبر في الرسوم البيانية داخل Quarto في الحصول على الحجم والشكل المناسبين للأشكال والرسوم البيانية. هناك خمسة خيارات رئيسية تتحكم في أبعاد الأشكال: fig-width و fig-height و fig-asp و out-width و out-height. يعد ضبط أبعاد الصور أمراً معقداً نظراً لوجود حجمين مختلفين (حجم الشكل كما ينشئه R، والحجم الذي يتم إدراجه به في المستند النهائي)، وطرق متعددة لتحديد هذا الحجم (أي: الارتفاع، والعرض، ونسبة العرض إلى الارتفاع: حيث تختار اثنين من أصل ثلاثة).

نوصي باستخدام ثلاثة من الخيارات الخمسة:

• تتجه المخططات والرسوم البيانية لأن تكون أكثر جمالاً وتسقاً إذا كان لها عرض موحد. لتطبيق ذلك، اضبط fig-width: 6 (أي 6 بوصات) و fig-asp: 0.618 (النسبة الذهبية) في الخيارات الافتراضية. ثم في الكتل الفردية، قم بتعديل fig-asp فقط حسب الحاجة.

• التحكم في حجم مخرجات العرض باستخدام out-width واضبطه كنسبة مئوية من عرض متن المستند النهائي. نقترح ضبط out-width: "70%" و fig-align: center.

  منح هذا الإعداد الرسوم البيانية مساحة مناسبة دون أن تشغل مساحة مفرطة.

• لوضع مخططات متعددة في صف واحد، اضبط layout-ncol على 2 لمخططين، و 3 لثلاثة مخططات، وهكذا. يقوم هذا الخيار فعلياً بضبط out-width على “50%” لكل مخطط إذا كان layout-ncol يساوي 2، و “33%” إذا كان layout-ncol يساوي 3، وهكذا. اعتماداً على ما تحاول توضيحه (مثل عرض البيانات أو توضيح التباين في المخططات)، قد تحتاج أيضاً إلى تعديل fig-width كما هو موضح أدناه.

إذا وجدت أنك تضطر إلى تدقيق النظر لقراءة النصوص الموجودة داخل الرسم البياني، فهذا يعني أنك بحاجة إلى تعديل fig-width. إذا كان fig-width أكبر من الحجم الذي يُعرض به الشكل في المستند النهائي، فسيكون حجم النص صغيراً جداً؛ وإذا كان fig-width أصغر، فسيكون النص كبيراً جداً. ستحتاج غالباً إلى إجراء بعض التجارب لتحديد النسبة الصحيحة بين fig-width والعرض النهائي في مستندك. لتوضيح المبدأ، تحتوي المخططات الثلاثة التالية على fig-width بقيم 4 و 6 و 8 على التوالي:

إذا كنت تريد التأكد من ثبات حجم الخط عبر جميع الرسوم البيانية، فكلما قمت بضبط out-width، ستحتاج أيضاً إلى تعديل fig-width للحفاظ على نفس النسبة مع out-width الافتراضي. على سبيل المثال، إذا كان fig-width الافتراضي لديك هو 6 و out-width هو “70%”، فعندما تضبط out-width: "50%" ستحتاج إلى ضبط fig-width ليصبح 4.3 (أي: 6 * 0.5 / 0.7).

يعد التحكّم في أبعاد الرسوم البيانية وتحجيمها علماً وفناً، وقد يتطلب الوصول إلى النتيجة المثالية اتباع أسلوب التجربة والخطأ المتكرر. يمكنك معرفة المزيد حول التحكّم في أبعاد الرسوم البيانية في منشور مدونة التحكم في مقياس المخططات.

28.6.2 خيارات مهمة أخرى

عند المزج بين الأكواد البرمجية والنصوص، كما في هذا الكتاب، يمكنك ضبط fig-show: hold بحيث تُعرض الرسوم البيانية بعد الكود مباشرة. لهذا الخيار أثر جانبي إيجابي يُجبرك على تقسيم كتل الأكواد الكبيرة وإدراج الشروحات بينها.

لإضافة شرح أو عنوان توضيحي للرسم البياني، استخدم fig-cap. في Quarto، سيؤدي هذا إلى تحويل الشكل من شكل مدمج في السطر (inline) إلى شكل طافٍ (floating).

إذا كنت تقوم بإنشاء مخرجات بصيغة PDF، فإن نوع الرسوم البيانية الافتراضي هو PDF. وهو إعداد افتراضي ممتاز لأن ملفات PDF تتميز بجودة عالية متجهة (vector graphics). ومع ذلك، يمكن أن تنتج مخططات كبيرة الحجم وبطيئة للغاية إذا كنت تعرض آلاف النقاط. في هذه الحالة، اضبط fig-format: "png" لفرض استخدام صيغة PNG. فهي أقل جودة بقليل، لكنها ستكون أكثر إدماجاً وأصغر حجماً بكثير.

من الجيد تسمية كتل الأكواد التي تنتج رسوماً بيانية، حتى لو لم تعتد تسمية الكتل الأخرى بشكل منتظم. تُستخدم تسمية الكتلة لإنشاء اسم ملف الرسم البياني على القرص الصلب، لذا فإن تسمية كتل الأكواد تجعل من السهل جداً استخراج المخططات وإعادة استخدامها في حالات أخرى (على سبيل المثال، إذا كنت تريد إدراج رسم بياني واحد سريعاً في بريد إلكتروني).

28.6.3 تمارين

1. افتح ملف diamond-sizes.qmd في المحرر المرئي، واعثر على صورة ألماسة، وانسخها، ثم الصقها في المستند. انقر نقراً مزدوجاً على الصورة وأضف عنواناً توضيحياً. قم بتغيير حجم الصورة واعمل معالجة (render) لمستندك. لاحظ كيفية حفظ الصورة في دليل العمل الحالي الخاص بك.

2. قم بتعديل تسمية كتلة الكود في diamond-sizes.qmd التي تنشئ الرسم البياني لتبدأ بالبادئة fig- وأضف عنواناً توضيحياً للشكل باستخدام خيار الكتلة fig-cap. ثم، قم بتعديل النص الموجود أعلى كتلة الكود لإضافة إحالة مرجعية (cross-reference) إلى الشكل عبر Insert > Cross Reference.

3. قم بتغيير حجم الشكل باستخدام خيارات الكتل التالية، واحداً تلو الآخر، وقم بمعالجة (render) المستند، وصف كيف يتغير الشكل:

   أ. fig-width: 10
   

   ب. fig-height: 3
   

   ج. out-width: "100%"
   

   د. out-width: "20%"

28.7 الجداول (Tables)

على غرار الرسوم البيانية والأشكال، يمكنك تضمين نوعين من الجداول في مستند Quarto. إما جداول ماركداون يتم إنشاؤها مباشرة في مستند Quarto (باستخدام قائمة Insert Table) أو جداول ناتجة عن تنفيذ كتلة كود برمجية. في هذا القسم، سنركز على النوع الثاني، وهو الجداول المنشأة عبر الحسابات البرمجية.

بشكل افتراضي، يطبع Quarto إطارات البيانات (data frames) والمصفوفات كما تراها في شاشة Console:

mtcars[1:5, ]
#>                    mpg cyl disp  hp drat    wt  qsec vs am gear carb
#> Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
#> Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
#> Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
#> Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
#> Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2

إذا كنت تفضل عرض البيانات بتنسيق إضافي وأكثر جاذبية، يمكنك استخدام الدالّة knitr::kable(). ينشئ الكود أدناه الجدول الموضح في الجدول 28.1.

knitr::kable(mtcars[1:5, ])

الجدول 28.1: جدول منشأ بواسطة knitr kable.

	mpg	cyl	disp	hp	drat	wt	qsec	vs	am	gear	carb
Mazda RX4	21.0	6	160	110	3.90	2.620	16.46	0	1	4	4
Mazda RX4 Wag	21.0	6	160	110	3.90	2.875	17.02	0	1	4	4
Datsun 710	22.8	4	108	93	3.85	2.320	18.61	1	1	4	1
Hornet 4 Drive	21.4	6	258	110	3.08	3.215	19.44	1	0	3	1
Hornet Sportabout	18.7	8	360	175	3.15	3.440	17.02	0	0	3	2

اقرأ توثيق الدالّة عبر ?knitr::kable لرؤية الطرق الأخرى التي يمكنك من خلالها تخصيص الجدول. للحصول على تخصيصات احترافية أكثر عمقاً، فكر في استخدام الحزم التالية: gt و huxtable و reactable و kableExtra و xtable و stargazer و pander و tables و ascii. توفر كل حزمة منها مجموعة أدوات لإرجاع جداول منسقة انطلاقاً من كود R.

28.7.1 تمارين

1. افتح diamond-sizes.qmd في المحرر المرئي، وأدرج كتلة كود، وأضف جدولاً باستخدام knitr::kable() يعرض أول 5 أعمدة/صفوف من إطار بيانات diamonds.
2. اعرض نفس الجدول باستخدام gt::gt() بدلاً من ذلك.
3. أضف تسمية للكتلة تبدأ بالبادئة tbl- وأضف عنواناً توضيحياً للجدول باستخدام خيار الكتلة tbl-cap. ثم، قم بتعديل النص الموجود أعلى كتلة الكود لإضافة إحالة مرجعية للجدول باستخدام Insert > Cross Reference.

28.8 التخزين المؤقت (Caching)

عادةً، تبدأ كل عملية معالجة (render) للمستند من حالة نظيفة وخالية تماماً. هذا أمر رائع لإعادة الإنتاج والموثوقية، لأنه يضمن تسجيل كل عملية حسابية مهمة في الكود. ومع ذلك، قد يكون الأمر شاقاً ومستغرقاً للوقت إذا كان لديك بعض الحسابات التي تستغرق وقتاً طويلاً. الحل في هذه الحالة هو استخدام الإعداد cache: true.

يمكنك تفعيل التخزين المؤقت في knitr على مستوى المستند بأكمله لتخزين نتائج جميع الحسابات في المستند مؤقتاً باستخدام خيارات YAML القياسية:

---
title: "مستندي"
execute: 
  cache: true
---

يمكنك أيضاً تفعيل التخزين المؤقت على مستوى الكتلة لتخزين نتائج الحسابات مؤقتاً لكتلة محددة:

```{r}
#| cache: true
# كود لحسابات تستغرق وقتاً طويلاً...
```

عند ضبط هذا الخيار، سيتم حفظ مخرجات الكتلة في ملف خاص على القرص الصلب. في عمليات التشغيل اللاحقة، سيتحقق knitr لمعرفة ما إذا كان الكود قد تغير، وإذا لم يتغير، فسيقوم بإعادة استخدام النتائج المخزنة مؤقتاً.

يجب استخدام نظام التخزين المؤقت بحذر، لأنه يعتمد افتراضياً على الكود فقط، وليس على الاعتماديات الخاصة به. على سبيل المثال، تعتمد كتلة processed_data هنا على كتلة raw-data:

``` {{r}}
#| label: raw-data
#| cache: true
rawdata <- readr::read_csv("a_very_large_file.csv")
```

``` {{r}}
#| label: processed_data
#| cache: true
processed_data <- rawdata |> 
  filter(!is.na(import_var)) |> 
  mutate(new_variable = complicated_transformation(x, y, z))
```

تخزين كتلة processed_data مؤقتاً يعني أنه سيتم إعادة تشغيلها إذا تم تغيير أنبوب dplyr، ولكن لن يتم إعادة تشغيلها إذا تغير استدعاء read_csv(). يمكنك تجنب هذه المشكلة باستخدام خيار الكتلة dependson:

``` {{r}}
#| label: processed-data
#| cache: true
#| dependson: "raw-data"
processed_data <- rawdata |> 
  filter(!is.na(import_var)) |> 
  mutate(new_variable = complicated_transformation(x, y, z))
```

يجب أن يحتوي dependson على متجه حرفي لـ كل كتلة اعتمدت عليها الكتلة المخزنة مؤقتاً. سيعمل knitr على تحديث نتائج الكتلة المخزنة مؤقتاً كلما اكتشف تغيير أحد اعتمادياتها.

لاحظ أن الكتل لن يتم تحديثها إذا تغير الملف الخارجي a_very_large_file.csv، لأن التخزين المؤقت في knitr يتتبع التغييرات داخل ملف .qmd فقط. إذا كنت تريد أيضاً تتبع التغييرات في ذلك الملف الخارجي، يمكنك استخدام الخيار cache.extra. هذا الخيار عبارة عن تعبير R اختياري يلغي التخزين المؤقت كلما تغيرت قيمته. والدالّة الممتازة للاستخدام هنا هي file.mtime(): حيث ترجع تاريخ ووقت آخر تعديل للملف. عندها يمكنك كتابة ما يلي:

``` {{r}}
#| label: raw-data
#| cache: true
#| cache.extra: !expr file.mtime("a_very_large_file.csv")
rawdata <- readr::read_csv("a_very_large_file.csv")
```

لقد اتبعنا نصيحة ديفيد روبنسون لتسمية هذه الكتل: حيث تسمى كل كتلة باسم الكائن الرئيسي الذي تنشئه. هذا يسهل فهم وتحديد مواصفات dependson.

مع تعقد استراتيجيات التخزين المؤقت تدريجياً، من الجيد مسح جميع التخزينات المؤقتة بانتظام باستخدام الأمر knitr::clean_cache().

28.8.1 تمارين

1. قم بإعداد شبكة من الكتل بحيث تعتمد الكتلة d على c و b، وتعتمد كل من b و c على الكتلة a. اجعل كل كتلة تطبع الوقت عبر lubridate::now()، واضبط cache: true، ثم تحقق من فهمك لسلوك التخزين المؤقت.

28.9 استكشاف الأخطاء وإصلاحها (Troubleshooting)

قد يكون استكشاف الأخطاء وإصلاحها في مستندات Quarto أمراً صعباً لأنك لم تعد تعمل في بيئة R تفاعلية مباشرة، وستحتاج إلى تعلم بعض المهارات الجديدة. بالإضافة إلى ذلك، قد يكون الخطأ ناتجاً عن مشكلات في مستند Quarto نفسه أو بسبب كود R الموجود داخل المستند.

أحد الأخطاء الشائعة في المستندات التي تحتوي على كتل أكواد هو تكرار تسميات الكتل (duplicated chunk labels)، والتي تنتشر بشكل خاص إذا كان سير عملك يتضمن نسخ كتل الأكواد ولصقها. لمعالجة هذه المشكلة، كل ما عليك فعله هو تغيير إحدى التسميات المكررة.

إذا كانت الأخطاء ناتجة عن كود R في المستند، فإن أول شيء يجب عليك تجريبه دائماً هو إعادة إنشاء المشكلة في جلسة تفاعلية. أعد تشغيل R، ثم اختر “Run all chunks”، إما من قائمة Code تحت Run region أو باستخدام اختصار لوحة المفاتيح Ctrl + Alt + R. إذا كنت محظوظاً، فسيؤدي ذلك إلى إعادة إنتاج المشكلة، ويمكنك معرفة ما يحدث بشكل تفاعلي.

إذا لم يساعدك ذلك، فلابد أن هناك شيئاً مختلفاً بين بيئتك التفاعلية وبيئة Quarto. ستحتاج إلى استكشاف الخيارات المتاحة منهجياً. الفرق الأكثر شيوعاً هو مجلد العمل (working directory): مجلد العمل لمستند Quarto هو المجلد الذي يقع فيه الملف نفسه. تحقق من أن مجلد العمل هو ما تتوقعه عن طريق تضمين getwd() في إحدى كتل الكود.

بعد ذلك، قم بتوليد أفكار حول جميع الأشياء التي قد تسبب المشكلة. ستحتاج إلى التحقق منهجياً من أنها هي نفسها في جلسة R وجلسة Quarto الخاصة بك. أسهل طريقة القيام بذلك هي ضبط error: true على الكتلة التي تسبب المشكلة، ثم استخدام print() و str() للتحقق من أن الإعدادات كما تتوقعها.

28.10 ترويسة YAML (YAML header)

يمكنك التحكم في العديد من الإعدادات الأخرى على مستوى “المستند ككل” عن طريق تعديل معاملات ترويسة YAML. قد تتساءل عما يرمز إليه اختصار YAML: إنه اختصار لـ “YAML Ain’t Markup Language” (يامل ليست لغة ترميز)، وهي مصممة لتمثيل البيانات الهرمية بطريقة يسهل على البشر قراءتها وكتابتها. يستخدمها Quarto للتحكم في العديد من تفاصيل المخرجات. سنتناول هنا ثلاثة جوانب: المستندات القائمة بذاتها، ومعاملات المستند، والمراجع والمصادر.

28.10.1 المستندات القائمة بذاتها (Self-contained)

عادةً ما تحتوي مستندات HTML على عدد من الاعتمادات/الارتباطات الخارجية (مثل: الصور، وأوراق أنماط CSS، ولغة JavaScript، وغيرها)، وبشكل افتراضي، يضع نظام Quarto هذه الاعتمادات في مجلد يحمل الاسم _files ضمن المسار/المجلد نفسه الذي يحتوي على ملف .qmd الخاص بك. وإذا قمت بنشر ملف HTML على منصة استضافة (مثل: QuartoPub عبر الرابط: https://quartopub.com/)، فإن الاعتمادات الموجودة في هذا المجلد تُنشر جنبًا إلى جنب مع مستندك، وتغدو بالتالي متاحة في التقرير المنشور. ومع ذلك، إذا كنت ترغب في إرسال التقرير عبر البريد الإلكتروني إلى أحد الزملاء، فقد تفضل الحصول على مستند HTML منفرد ومستقل ذاتيًا (self-contained) يدمج داخله جميع اعتماداته الخارجية. يمكنك تحقيق ذلك من خلال تحديد الخيار embed-resources:

format:
  html:
    embed-resources: true

سيكون الملف الناتج قائماً بذاته بالكامل، بحيث لن يحتاج إلى ملفات خارجية ولا إلى اتصال بالإنترنت ليتم عرضه بشكل صحيح بواسطة المتصفح.

28.10.2 المعاملات (Parameters)

يمكن أن تتضمن مستندات Quarto معلماً واحداً أو أكثر يمكن تحديد قيمها عند معالجة التقرير (render). تكون المعاملات مفيدة عندما تريد إعادة معالجة نفس التقرير بقيم مختلفة لمدخلات رئيسية متنوعة. على سبيل المثال، قد تقوم بإنشاء تقارير مبيعات لكل فرع، أو نتائج اختبارات لكل طالب، أو ملخصات ديموغرافية لكل دولة. للإعلان عن معلم واحد أو أكثر، استخدم الحقل params.

يستخدم هذا المثال المعامل my_class لتحديد فئة السيارات التي سيتم عرضها:

---
format: html
params:
  my_class: "suv"
---

```{r}
#| label: setup
#| include: false

library(tidyverse)

class <- mpg |> filter(class == params$my_class)
```

# Fuel economy for `r params$my_class`s

```{r}
#| message: false

ggplot(class, aes(x = displ, y = hwy)) + 
  geom_point() + 
  geom_smooth(se = FALSE)
```

كما ترى، تتوفر المعاملات داخل كتل الكود كقائمة للقراءة فقط تسمى params.

يمكنك كتابة المتجهات الأولية مباشرة في ترويسة YAML. يمكنك أيضاً تشغيل تعبيرات R الاختيارية عن طريق تقديم قيمة المعامل بـ !expr. هذه طريقة ممتازة لتحديد معاملات التاريخ/الوقت.

params:
  start: !expr lubridate::ymd("2015-01-01")
  snapshot: !expr lubridate::ymd_hms("2015-01-01 12:30:00")

28.10.3 قائمة المراجع والاستشهادات

يمكن لـ Quarto توليد الاستشهادات وقائمة المراجع تلقائياً بأنماط وأساليب متعددة. أسهل طريقة لإضافة الاستشهادات والمراجع إلى مستند Quarto هي استخدام المحرر المرئي في RStudio.

لإضافة استشهاد باستخدام المحرر المرئي، انتقل إلى Insert > Citation. يمكن إدراج الاستشهادات من مصادر متنوعة:

1. مراجع DOI (المعرف الرقمي للكائنات).

2. مكتبات Zotero الشخصية أو الجماعية.

3. عمليات البحث في Crossref أو DataCite أو PubMed.

4. قائمة مراجع مستندك (ملف .bib في مجلد مستندك).

في الكواليس، يستخدم الوضع المرئي تمثيل Pandoc markdown القياسي للاستشهادات (مثل [@citation]).

إذا أضفت استشهاداً باستخدام إحدى الطرق الثلاث الأولى، فسيقوم المحرر المرئي تلقائياً بإنشاء ملف bibliography.bib لك وإضافة المرجع إليه. سيضيف أيضاً حقل bibliography إلى YAML الخاص بالمستند. كلما أضفت المزيد من المراجع، سيتم تعبئة هذا الملف باستشهاداتها. يمكنك أيضاً تحرير هذا الملف مباشرة باستخدام العديد من صيغ المراجع الشائعة بما في ذلك BibLaTeX و BibTeX و EndNote و Medline.

لإنشاء استشهاد داخل ملف .qmd الخاص بك في محرر المصدر، استخدم مفتاحاً يتكون من ‘@’ + معرف الاستشهاد من ملف المراجع. ثم ضع الاستشهاد بين قوسين مربعين. إليك بعض الأمثلة:

افصل بين الاستشهادات المتعددة بـ `;`: كلام كلام [@smith04; @doe99].

يمكنك إضافة تعليقات اختيارية داخل القوسين المربعين: 
كلام كلام [انظر @doe99, pp. 33-35; أيضاً @smith04, ch. 1].

قم بإزالة القوسين المربعين لإنشاء استشهاد مدمج في النص: يذكر @smith04 
كلاماً، أو يذكر @smith04 [p. 33] كلاماً.

أضف `-` قبل الاستشهاد لإخفاء اسم المؤلف: 
ذكر سميث كلاماً [-@smith04].

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

يمكنك تغيير نمط الاستشهادات وقائمة المراجع الخاصة بك عن طريق الإشارة إلى ملف CSL (لغة نمط الاستشهاد) في الحقل csl:

bibliography: rmarkdown.bib
csl: apa.csl

كما هو الحال مع حقل المراجع، يجب أن يحتوي ملف csl على المسار المؤدي إلى الملف. نفترض هنا أن ملف csl يقع في نفس المجلد الذي يوجد به ملف .qmd. مكان ممتاز للعثور على ملفات نمط CSL لأنماط المراجع الشائعة هو https://github.com/citation-style-language/styles.

28.11 سير العمل (Workflow)

في وقت سابق، ناقشنا سير عمل أساسي لالتقاط كود R الخاص بك حيث تعمل بشكل تفاعلي في الكونسول Console، ثم تلتقط ما يعمل في محرر النصوص البرمجية script editor. يجمع Quarto بين المنصة ومحرر النصوص البرمجية، مما يذيب الفوارق بين الاستكشاف التفاعلي والتقاط الكود على المدى الطويل. يمكنك التكرار والتطوير بسرعة داخل الكتلة، والتعديل وإعادة التنفيذ باستخدام Cmd/Ctrl + Shift + Enter. عندما تكون راضياً، تنتقل وتبدأ كتلة جديدة.

يعد Quarto مهماً أيضاً لأنه يدمج النصوص والكود بانسجام وثيق. هذا يجعله دفتراً تحليلياً ممتازاً لأنه يتيح لك تطوير الكود وتسجيل أفكارك. يشترك الدفتر التحليلي في العديد من الأهداف نفسها مع دفتر الملاحظات المعملي الكلاسيكي في العلوم الطبيعية. فهو:

• يسجل ما قمت به ولماذا قمت به. بغض النظر عن مدى قوة ذاكرتك، إذا لم تسجل ما تفعله، فسياتي وقت تنسى فيه التفاصيل المهمة. اكتبها حتى لا تنسى!

• يدعم التفكير الصارم والمنهجي. من المرجح أن تصل إلى تحليل قوي إذا قمت بتسجيل أفكارك أثناء السير في العمل، واستمررت في التأمل فيها. هذا يوفر عليك الوقت أيضاً عندما تقوم في النهاية بصياغة تحليلك لمشاركته مع الآخرين.

• يساعد الآخرين على فهم عملك. من النادر القيام بتحليل البيانات بمفردك، وغالباً ما ستعمل كجزء من فريق. يساعدك دفتر الملاحظات المعملي على مشاركة ليس فقط ما قمت به، ولكن لماذا قمت به مع زملائك في العمل أو المختبر.

يمكن أيضاً ترجمة الكثير من النصائح القيمة حول استخدام دفاتر الملاحظات المعملية بفعالية إلى دفاتر التحليل. لقد استعنا بتجاربنا الخاصة ونصائح كولين بورينجتون حول دفاتر الملاحظات المعملية (https://colinpurrington.com/tips/lab-notebooks) للوصول إلى النصائح التالية:

• تأكد من أن كل دفتر يحتوي على عنوان وصفي، واسم ملف معبر، وفقرة أولى تصف باختصار أهداف التحليل.

• استخدم حقل التاريخ في ترويسة YAML لتسجيل تاريخ بدء العمل على الدفتر:

  date: 2016-08-23

  استخدم صيغة ISO8601 YYYY-MM-DD حتى لا يكون هناك أي غموض. استخدمها حتى لو لم تكن تكتب التواريخ بهذه الطريقة عادةً!

• إذا قضيت وقتاً طويلاً في فكرة تحليل وتبين أنها طريق مسدود، فلا تحذفها! اكتب ملاحظة قصيرة عن سبب فشلها واتركها في الدفتر. سيساعدك ذلك على تجنب الوقوع في نفس الطريق المسدود عندما تعود إلى التحليل في المستقبل.

• بشكل عام، من الأفضل إدخال البيانات خارج R. ولكن إذا كنت بحاجة إلى تسجيل قصاصة صغيرة من البيانات، فقم بتنسيقها بوضوح باستخدام tibble::tribble().

• إذا اكتشفت خطأً في ملف بيانات، فلا تقم بتعديله مباشرة أبداً، ولكن اكتب كوداً لتصحيح القيمة. واشرح سبب إجرائك للتصحيح.

• قبل أن تنهي عملك لليوم، تأكد من أنه يمكنك معالجة (render) الدفتر بنجاح. إذا كنت تستخدم التخزين المؤقت، فتأكد من مسح التخزينات المؤقتة. سيسمح لك ذلك بإصلاح أي مشاكل بينما لا تزال الأكواد حاضرة في ذهنك.

• إذا كنت تريد أن يكون كودك قابلاً لإعادة الإنتاج على المدى الطويل (أي بحيث يمكنك العودة لتشغيله الشهر القادم أو العام القادم)، فستحتاج إلى تتبع إصدارات الحزم التي يستخدمها كودك. النهج الصارم هو استخدام renv، https://rstudio.github.io/renv/index.html، والذي يخزن الحزم في مجلد مشروعك. والطريقة السريعة هي تضمين كتلة تشغل sessionInfo() — لن يتيح لك ذلك إعادة إنشاء حزمك بسهولة كما هي اليوم، ولكن على الأقل ستعرف ما كانت عليه.

• ستنشئ العديد والعديد والعديد من دفاتر التحليل على مدار حياتك المهنية. كيف ستنظمها حتى تتمكن من العثور عليها مرة أخرى في المستقبل؟ نوصي بتخزينها في مشاريع فردية، والوصول إلى مخطط تسمية جيد.

28.12 ملخص

في هذا الفصل قدمنا لك Quarto لتأليف ونشر المستندات الحسابية القابلة لإعادة الإنتاج والتكرار والتي تجمع بين الأكواد والنصوص في مكان واحد. لقد تعلمت كيفية كتابة مستندات Quarto في RStudio باستخدام المحرر المرئي أو محرر المصدر، وكيف تعمل كتل الأكواد البرمجية وكيفية تخصيص الخيارات لها، وكيفية تضمين الرسوم البيانية والجداول في مستندات Quarto الخاصة بك، وخيارات التخزين المؤقت للحسابات. بالإضافة إلى ذلك، تعلمت كيفية تعديل خيارات ترويسة YAML لإنشاء مستندات قائمة بذاتها أو معتمدة على معاملات، بالإضافة إلى تضمين الاستشهادات وقائمة المراجع. لقد قدمنا لك أيضاً بعض النصائح لاستكشاف الأخطاء وإصلاحها وتحسين سير العمل.

رغم أن هذه المقدمة يجب أن تكون كافية للبدء مع Quarto، إلا أنه لا يزال هناك الكثير لتعلمه. لا يزال Quarto حديثاً نسبياً، ولا يزال ينمو بسرعة. أفضل مكان للبقاء على اطلاع بأحدث الابتكارات هو موقع Quarto الرسمي: https://quarto.org.

هناك موضوعان مهمان لم نغطهما هنا: التعاون والتفاصيل الدقيقة لتوصيل أفكارك بدقة إلى الآخرين. التعاون جزء حيوي من علم البيانات الحديث، ويمكنك جعل حياتك أسهل بكثير باستخدام أدوات التحكم في الإصدار، مثل Git و GitHub. نوصي بقراءة “Happy Git with R”، وهي مقدمة سهلة الاستخدام لـ Git و GitHub لمستخدمي R، أعدتها جيني براين. الكتاب متاح مجاناً على الإنترنت: https://happygitwithr.com.

لم نتطرق أيضاً إلى ما يجب عليك كتابته بالفعل من أجل توصيل نتائج تحليلك بوضوح. لتحسين كتابتك، نوصي بشدة بقراءة إما Style: Lessons in Clarity and Grace لجوزيف ويليامز وجوزيف بيزوب، أو The Sense of Structure: Writing from the Reader’s Perspective لجورج جوبين. سيساعدك كلا الكتابين على فهم بنية الجمل والفقرات، ويمنحانك الأدوات لجعل كتابتك أكثر وضوحاً. (هذه الكتب مكلفة نوعاً ما إذا تم شراؤها جديدة، ولكن يتم استخدامها في العديد من فصول اللغة الإنجليزية لذا توجد الكثير من النسخ المستعملة الرخيصة). يمتلك جورج جوبين أيضاً عدداً من المقالات القصيرة حول الكتابة على https://www.georgegopen.com/litigation-articles.html. وهي موجهة للمحامين، ولكن كل شيء فيها ينطبق تقريباً على علماء البيانات أيضاً.