29 صيغ وتنسيقات Quarto

29.1 مقدمة

حتى الآن، رأيت استخدام Quarto لإنتاج مستندات HTML. يقدم هذا الفصل نظرة عامة موجزة عن بعض الأنواع الكثيرة الأخرى للمخرجات التي يمكنك إنتاجها باستخدام Quarto.

توجد طريقتان لتحديد مخرجات المستند:

بشكل دائم، عن طريق تعديل ترويسة YAML (YAML header):

title: "Diamond sizes"
format: html

بشكل مؤقت، عن طريق استدعاء الدالة quarto::quarto_render() يدوياً:

quarto::quarto_render("diamond-sizes.qmd", output_format = "docx")

هذا مفيد إذا كنت تريد إنتاج أنواع متعددة من المخرجات برمجياً، حيث يمكن للمعامل output_format أن يقبل أيضاً قائمة من القيم.

quarto::quarto_render("diamond-sizes.qmd", output_format = c("docx", "pdf"))

29.2 خيارات المخرجات

يوفر Quarto مجموعة واسعة من صيغ المخرجات. يمكنك العثور على القائمة الكاملة على https://quarto.org/docs/output-formats/all-formats.html. تشترك العديد من الصيغ في بعض خيارات المخرجات (على سبيل المثال، toc: true تضمين جدول المحتويات)، ولكن الصيغ الأخرى تحتوي على خيارات خاصة بها (على سبيل المثال، code-fold: true يطوي كتل الأكواد داخل وسم <details> لمخرجات HTML بحيث يمكن للمستخدم عرضها عند الطلب، وهو أمر غير قابل للطبيق في مستندات PDF أو Word).

لتجاوز الخيارات الافتراضية، ستحتاج إلى استخدام حقل format موسع. على سبيل المثال، إذا كنت تريد معالجة مستند html مع جدول محتويات طافٍ، فستستخدم:

format:
  html:
    toc: true
    toc_float: true

يمكنك حتى المعالجة إلى مخرجات متعددة من خلال تقديم قائمة من الصيغ:

format:
  html:
    toc: true
    toc_float: true
  pdf: default
  docx: default

لاحظ الصيغة الخاصة (pdf: default) إذا كنت لا تريد تجاوز أي خيارات افتراضية.

للمعالجة إلى جميع الصيغ المحددة في ترويسة YAML الخاصة بالمستند، يمكنك استخدام output_format = "all".

quarto::quarto_render("diamond-sizes.qmd", output_format = "all")

29.3 المستندات

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

pdf ينشئ ملف PDF باستخدام LaTeX (وهو نظام مفتوح المصدر لتنسيق المستندات)، والذي ستحتاج إلى تثبيته. سيقوم RStudio بتنبيهك إذا لم يكن مثبتًا لديك بالفعل.
docx لمستندات Microsoft Word ((.docx)).
odt لمستندات OpenDocument Text ((.odt)).
rtf لمستندات التنسيق الغني Rich Text Format ((.rtf)).
gfm لمستندات ماركداون مدعومة من GitHub Flavored Markdown ((.md)).
ipynb لدفاتر مذكرات جوبيتر Jupyter Notebooks ((.ipynb)).

تذكر، عند إنشاء مستند لمشاركته مع صناع القرار، يمكنك إيقاف العرض الافتراضي للأكواد عن طريق ضبط الخيارات العامة في ترويسة YAML الخاصة بالمستند:

execute:
  echo: false

بالنسبة لمستندات html، هناك خيار آخر وهو جعل كتل الأكواد مخفية افتراضيًا، ولكن يمكن إظهارها بنقرة واحدة:

format:
  html:
    code: true

29.4 العروض التقديمية

يمكنك أيضًا استخدام Quarto لإنتاج عروض تقديمية. تحصل على تحكم بصرّي أقل مقارنة بأدوات مثل Keynote أو PowerPoint، ولكن الإدراج التلقائي لنتائج كود R في العرض التقديمي يمكن أن يوفر قدرًا هائلاً من الوقت. تعمل العروض التقديمية عن طريق تقسيم المحتوى الخاص بك إلى شرائح، حيث تبدأ شريحة جديدة عند كل عنوان من المستوى الثاني (##). بالإضافة إلى ذلك، تشير العناوين من المستوى الأول (#) إلى بداية قسم جديد مع شريحة عنوان القسم تكون ممركزة افتراضيًا في المنتصف.

يدعم Quarto مجموعة متنوعة من صيغ العروض التقديمية، بما في ذلك:

revealjs - عرض تقديمى HTML باستخدام revealjs.
pptx - عرض تقديمى PowerPoint.
beamer - عرض تقديمى PDF باستخدام LaTeX Beamer.

يمكنك قراءة المزيد حول إنشاء العروض التقديمية باستخدام Quarto على https://quarto.org/docs/presentations.

29.5 التفاعلية (Interactivity)

تمامًا مثل أي مستند HTML، يمكن لمستندات HTML المنشأة باستخدام Quarto أن تحتوي على مكونات تفاعلية أيضًا. نقدم هنا خيارين لتضمين التفاعلية في مستندات Quarto الخاصة بك: htmlwidgets و Shiny.

29.5.1 المكونات التفاعلية htmlwidgets

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

library(leaflet)
leaflet() |>
  setView(174.764, -36.877, zoom = 16) |>
  addTiles() |>
  addMarkers(174.764, -36.877, popup = "Maungawhau")

الشيء الرائع في htmlwidgets هو أنك لست بحاجة إلى معرفة أي شيء عن HTML أو JavaScript لاستخدامها. تم تغليف جميع التفاصيل داخل الحزمة، لذلك لا داعي للقلق بشأنها.

هناك العديد من الحزم التي توفر htmlwidgets، بما في ذلك:

dygraphs للتمثيلات البيانية التفاعلية للسلاسل الزمنية.
DT للجداول التفاعلية.
threejs للمخططات ثلاثية الأبعاد التفاعلية.
DiagrammeR للمخططات الهيكلية (مثل مخططات التدفق ومخططات العقد والروابط البسيطة).

لمعرفة المزيد حول htmlwidgets ورؤية قائمة كاملة بالحزم التي توفرها، قم بزيارة https://www.htmlwidgets.org.

29.5.2 Shiny

توفر htmlwidgets تفاعلية من جانب العميل (client-side) — تحدث جميع التفاعلات داخل المتصفح، بشكل مستقل عن R. من ناحية، هذا أمر رائع لأنه يمكنك من توزيع ملف HTML دون أي اتصال بـ R. ومع ذلك، فإن هذا يحد بشكل أساسي مما يمكنك القيام به للتحول إلى الأشياء التي تم تنفيذها في HTML و JavaScript. نهج بديل هو استخدام shiny، وهي حزمة تسمح لك بإنشاء تفاعلية باستخدام كود R، وليس JavaScript.

لاستدعاء كود Shiny من مستند Quarto، أضف server: shiny إلى ترويسة YAML:

title: "تطبيق ويب Shiny"
format: html
server: shiny

ثم يمكنك استخدام دوال “المدخلات” لإضافة مكونات تفاعلية إلى المستند:

library(shiny)

textInput("name", "What is your name?")
numericInput("age", "How old are you?", NA, min = 0, max = 150)

مربعا مدخلات فوق بعضهما البعض. المربع العلوي يقول "ما هو اسمك؟"، والمربع السفلي يقول "كم عمرك؟".

تحتاج أيضاً إلى كتلة كود تحتوي على خيار الكتلة context: server والذي يحتوي على الكود الذي يحتاج إلى التشغيل داخل خادم Shiny.

يمكنك بعد ذلك الإشارة إلى القيم باستخدام input$name و input$age، وسيتم إعادة تشغيل الكود الذي يستخدمها تلقائياً كلما تغيرت.

لا يمكننا عرض تطبيق shiny مباشر هنا لأن تفاعلات shiny تحدث على جانب الخادم (server-side). هذا يعني أنه يمكنك كتابة تطبيقات تفاعلية دون معرفة JavaScript، ولكنك تحتاج إلى خادم لتشغيلها. هذا يطرح عقبة لوجستية: تحتاج تطبيقات Shiny إلى خادم Shiny لتشغيلها عبر الإنترنت. عند تشغيل تطبيقات Shiny على جهازك الكمبيوتر، يقوم Shiny تلقائيًا بإعداد خادم Shiny لك، ولكنك تحتاج إلى خادم Shiny عام إذا كنت تريد نشر هذا النوع من التفاعلية عبر الإنترنت. هذا هو المقابل الأساسي لاستخدام shiny: يمكنك القيام بأي شيء في مستند shiny يمكنك القيام به في R، ولكنه يتطلب تشغيل بيئة R في الخلفية.

لمعرفة المزيد حول Shiny، نوصي بقراءة كتاب Mastering Shiny بواسطة هادلي ويكهام، https://mastering-shiny.org.

29.6 المواقع الإلكترونية والكتب

باستخدام القليل من البنية التحتية الإضافية، يمكنك استخدام Quarto لإنشاء موقع ويب كامل أو كتاب:

ضع ملفات .qmd الخاصة بك في دليل واحد. سيكون index.qmd هو الصفحة الرئيسية.
أضف ملف YAML باسم _quarto.yml يحدد التنقل للموقع. في هذا الملف، اضبط نوع project إما على book أو website، على سبيل المثال:
```
project:
  type: book
```

على سبيل المثال، ينشئ ملف _quarto.yml التالي موقع ويب من ثلاثة ملفات المصدر: index.qmd (الصفحة الرئيسية)، و viridis-colors.qmd، و terrain-colors.qmd.

project:
  type: website

website:
  title: "A website on color scales"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: viridis-colors.qmd
        text: Viridis colors
      - href: terrain-colors.qmd
        text: Terrain colors

ملف _quarto.yml الذي تحتاجه لكتاب منظم بشكل مشابه جداً. يوضح المثال التالي كيفية إنشاء كتاب من أربعة فصول يتم معالجته إلى ثلاثة مخرجات مختلفة (html و pdf و epub). مرة أخرى، ملفات المصدر هي ملفات .qmd.

project:
  type: book

book:
  title: "A book on color scales"
  author: "Jane Coloriste"
  chapters:
    - index.qmd
    - intro.qmd
    - viridis-colors.qmd
    - terrain-colors.qmd

format:
  html:
    theme: cosmo
  pdf: default
  epub: default

نوصي باستخدام مشروع RStudio للمواقع والكتب الخاصة بك. بناءً على ملف _quarto.yml، سيتعرف RStudio على نوع المشروع الذي تعمل عليه، ويضيف تبويب Build إلى بيئة التطوير (IDE) والتي يمكنك استخدامها لمعالجة ومعاينة المواقع والكتب الخاصة بك. يمكن أيضاً معالجة كل من المواقع والكتب باستخدام quarto::quarto_render().

اقرأ المزيد على https://quarto.org/docs/websites حول مواقع Quarto وعلى https://quarto.org/docs/books حول الكتب.

29.7 صيغ أخرى

يقدم Quarto صيغ مخرجات أكثر بكثير:

يمكنك كتابة مقالات علمية للأوراق البحثية باستخدام قوالب مجلات Quarto: https://quarto.org/docs/journals/templates.html.
يمكنك إخراج مستندات Quarto إلى دفاتر مذكرات جوبيتر مع format: ipynb: https://quarto.org/docs/reference/formats/ipynb.html.

راجع https://quarto.org/docs/output-formats/all-formats.html للحصول على قائمة بأشكال وصيغ أكثر.

29.8 ملخص

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

لمعرفة المزيد حول التواصل الفعال بهذه الصيغ المختلفة، نوصي بالمصادر التالية:

لتحسين مهاراتك في العروض التقديمية، جرب كتاب Presentation Patterns بواسطة نيل فورد، وماتيو مكولوف، وناثانيال شوتا. يقدم مجموعة من الأنماط الفعالة (منخفضة وعالية المستوى) التي يمكنك تطبيقها لتحسين عروضك التقديمية.
إذا كنت تقدم محادثات أكاديمية، فقد يعجبك دليل مجموعة ليك لإلقاء المحادثات.
لم نأخذ الدورة بأنفسنا، ولكننا سمعنا أشياء جيدة عن دورة مات ماكغاريتي عبر الإنترنت حول التحدث أمام الجمهور: https://www.coursera.org/learn/public-speaking.
إذا كنت تقوم بإنشاء العديد من لوحات المعلومات (dashboards)، فتأكد من قراءة كتاب ستيفن فيو Information Dashboard Design: The Effective Visual Communication of Data. سيساعدك على إنشاء لوحات معلومات مفيدة حقاً، وليس فقط جميلة في المظهر.
غالباً ما يتطلب التواصل الفعال لأفكارك إلماماً ببعض أساسيات التصميم الجرافيكي. ويعد كتاب روبين ويليامز The Non-Designer’s Design Book مكان ممتاز للبدء.