Quarto ابزار تولید گزارش

جواد فردمال

چیستی و چرایی

Quarto یک ابزار قدرتمند، متن باز و رایگان برای نگارش انواع گزارش علمی (مقاله، وبلاگ، کتاب، ارایه و …) است.

برخی ویژگیهای Quarto

امکان گنجاندن انواع اشیا دراخل متن وجود دارد (متن، کددستور، خروجی برنامه، جدول، نمودار، شکل، فرمول)
پشتیبانی چندزبانه و قابلیت ltr و rtl
قابلیت تولید خروجی‌های مختلف (HTML، PDF، Word، و …)
پشتیبانی و اجرای کد برنامه‌های R، Python، JuliaLang و …
قابلیت سفارشی‌سازی با استفاده از قالب‌های موجود یا ایجاد قالب جدید با کمک کدهای CSS و SCSS.
همزمانی مراحل تحلیل و نگارش
داینامیک بودن گزارش بنا به ورودی اولیه
ایجاد گزارش های تعاملی (Apps)

آماده‌سازی

1- نصب R

The Comprehensive R Archive Network

2- نصب RStudio

Posit: The Open-Source Data Science Company

3- به روز رسانی Quarto CLI

Quarto: Scientific & technical publishing system

4- نصب TinyTex

ترمینال ویندوز (Windows terminal) یا PowerShell را اجرا کنید.
دستور quarto install tinytex را اجرا کنید

نمونه هایی از اسناد و گزارش ها

گزارش
ارایه
وبسایت
- NASA Openscapes
- Practical Deep Learning
کتاب
- Hands-On Programming with R
- R for Data Science (2e)
متن تعاملی
- Diamonds Explorer

نکته

برای دیدن نمونه های بیشتر گالری Quarto را ببینید

ایجاد سند در Rstudio

flowchart LR
  B(File ...) --> C(New File ...)
  C --> D{Qurto Document ...}
  D --> E{Document}
  D --> F{Presentation}
  D --> G{Interactive}
  E --> H[html]
  E --> I[pdf]
  E --> J[Word]
  F --> K[Reveal JS]
  F --> L[Beamer]
  F --> M[Power Point]
  G --> N[Shiny]
  G --> O[Observable JS]

نکته

پسوند اسناد qmd میباشد و براساس فرمت خروجی، فایلهایی با فرمت های مختلف دیگر نیز ایجاد خواهد شد.

مراحل ایجاد سند

1- انتخاب سند جدید Quarto

2- انتخاب قالب و الگوی سند

نمونه ای از گزارش ایجاد شده در فرمت HTML

حالت Source در مقابل Visual

بخش های مختلف سند

YAML
TEXT
CHUNK

YAML

YAML (Yet Another Markup Language) فرا داده و برخی تنظیات متن را انجام میدهد.
شروع و پایان این بخش با --- است.
تنظیماتی مثل:
- عنوان، زیرعنوان، نویسنده، تاریخ و …
- فرمت تولیدی، قالب صفحه بندی، رفرنس، و …
تنظیمات به صورت key: value است.

---
title: My Quarto Project
author: John Doe
format: docx
---

نکته

انجام برخی از تنظیمات در سایر بخش ها (TEXT و CHUNK) نیز ممکن است
برای دیدن و آشنایی با دیگر تنظیمات YAML،کلیک کنید

TEXT

منظور از بخش TEXT شامل

متن ساده
جدول
شکل
فرمول
لینک
لیست
دیاگرام
و …

Visual یا Source

برای نگارش متن می توان وارد سربرگ Visual یا سربرگ Source شد.
در سربرگ Visual می توان از منوها و ابزارهای موجود برای فرمت متن، گنجاندن عکس یا جدول، رفرنس و … استفاده کرد
در سربرگ Source برای فرمت متن، گنجاندن عکس و … بایستی از کدهای Markdown استفاده کرد.

نکته

بخش آتی مربوط به نحوه استفاده از کدهای Markdown برای فرمت نوشته هاست. اگر از سربرگ ویژال استفاده میکنید نیاز به آن نیست

فرمت متن ساده

برخی دستورات برای فرمت دادن به متن

ایتالیک و بولد و زیرنویس و … (Rmarkdown)

**Bold** –> Bold
*Italic* –> Italic
~~strikethrough~~ –> ~~strikethrough~~
Sub~Script~ –> Sub_Script
Super^Script^ –> Super^Script

فرمول (LaTex)

داخل متن $E=m \times c^2$ –> داخل متن $E=m\times c^2$
در خط جدا $$E=m \times c^2$$ –> در خط جدا \[E=m\times c^2\]

تصویر و لینک

![Quarto logo](images/quarto2.png) –>

[GoOgLe](https://www.google.com/) –> GoOgLe

لیست ها
تیترها
…

مثال

عبارت نگارش شده در قالب Rmarkdown:

### Benthic Biodiversity experiment

\  

These data were obtained from a mesocosm experiment which aimed to examine the effect 
of benthic polychaete (*Nereis diversicolor*) biomass on sediment nutrient 
(NH~4~, NO~3~ and PO~3~) release. At the start of the experiment 15 replicate mesocosms 
were filled with 20 cm^2^ of **homogenised** marine sediment and assigned to one of five 
polychaete biomass treatments (0, 0.5, 1, 1.5, 2 g per mesocosm).

حاصل عبارت بالا:

Benthic Biodiversity experiment

These data were obtained from a mesocosm experiment which aimed to examine the effect of benthic polychaete (Nereis diversicolor) biomass on sediment nutrient (NH₄, NO₃ and PO₃) release. At the start of the experiment replicate mesocosms were filled with 20 cm² of homogenised marine sediment and assigned to one of five polychaete biomass treatments (0, 0.5, 1, 1.5, 2 g per mesocosm).

مثال

عبارت نگارش شده در قالب Rmarkdown:

These      data were      obtained from a
mesocosm experiment which    aimed to examine the
effect
of          benthic polychaete (*Nereis diversicolor*) biomass.

حاصل عبارت بالا:

These data were obtained from a mesocosm experiment which aimed to examine the effect of benthic polychaete (Nereis diversicolor) biomass.

مهم

بیش از یک فاصله در متن در نظر گرفته نمی شود
خط خالی در متن در نظر گرفته نمی شود

CHUNK

شامل کد دستورهای R، Python، Julia و …
قابل تنظیم به صورت درون و بین خطوط
دارای تنظیمات مختلف برای کنترل نمایش کدها و خروجی

ساختار کلی آن برای کدهای بین خصوط به شکل

```{r}
#| echo: false

cat("output = ", 1 + 1)
```

که منجر به خروجی

output =  2

است و برای نوشتن کد درون خطوط به شکل

the mean of {r} names(BOD)[2] is: {r} round(mean(BOD[,2]),2)

استفاده می شود که منجر به خروجی زیر میشود

the mean of demand is: 14.83

کنترل نمایش کدها و خروجی

تنظیمات در CHUNK با استفاده از عبارت |# مشخص میشود.
تنظیمات در قالب کلی Key: Value میباشد

```{r}
#| fig-cap: نمودار 1
#| message: false
#| warning: false
require(tidyverse)
p1 <- BOD %>% ggplot(aes(y=demand,x=Time)) +
  geom_point()
p1
```

برخی از Keyهای مهم عبارت است از:
- echo: آیا کدهای برنامه در سند نهایی نمایش داده شود یا خیر (true/false/fenced)
- eval: آیا کدها اجرا شوند یا فقط نمایش داده شوند (true/false)
- include: آیا اگر قرار است کدها اجرا شوند، خروجی در سند نهایی نمایش داده شود یا خیر (true/false)
- warning: آیا پیام های احتیاط که ممکن است در حین اجرای ایجاد شود نمایش داده شود (true/false)
- message: آیا پیغامهایی که ممکن است در حین اجرای کد ایجاد شود نمایش داده شود یا خیر
- …

مثال از گزینه های تنظیم CHUNK

1- CHUNK اول و خروجی مربوطه

👇 ورودی

```{r}
#| collapse: true
#| message: true
#| warning: true
#| fig-align: center
#| fig-width: 3
#| fig-height: 2.5
require(tidyverse)
ggplot(data=BOD, aes(y=demand,x=Time)) +
  geom_point()
```

👇 خروجی

require(tidyverse)
## Loading required package: tidyverse
## Warning: package 'tidyverse' was built under R version 4.3.3
## Warning: package 'lubridate' was built under R version 4.3.3
## ── Attaching core tidyverse packages ──────────────────────── tidyverse 2.0.0 ──
## ✔ dplyr     1.1.4     ✔ readr     2.1.5
## ✔ forcats   1.0.0     ✔ stringr   1.5.1
## ✔ ggplot2   3.4.4     ✔ tibble    3.2.1
## ✔ lubridate 1.9.3     ✔ tidyr     1.3.1
## ✔ purrr     1.0.2
## ── Conflicts ────────────────────────────────────────── tidyverse_conflicts() ──
## ✖ dplyr::filter() masks stats::filter()
## ✖ dplyr::lag()    masks stats::lag()
## ℹ Use the conflicted package (<http://conflicted.r-lib.org/>) to force all conflicts to become errors
ggplot(data=BOD, aes(y=demand,x=Time)) +
  geom_point()

2- CHUNK دوم و خروجی مربوطه

👇 ورودی

```{r}
#| collapse: true
#| message: false
#| warning: false
#| fig-align: center
#| fig-width: 6
#| fig-height: 5
#| code-fold: true
require(tidyverse)
ggplot(data=BOD, aes(y=demand,x=Time)) +
  geom_point()
```

👇 خروجی

Code

require(tidyverse)
ggplot(data=BOD, aes(y=demand,x=Time)) +
  geom_point()

3- CHUNK سوم و خروجی مربوطه

👇 ورودی

```{r}
#| collapse: true
#| message: false
#| warning: false
#| fig-align: center
#| fig-width: 6
#| fig-height: 5
#| code-fold: false
#| code-line-numbers: false
require(tidyverse)
ggplot(data=BOD, aes(y=demand,x=Time)) +
  geom_point()
```

👇 خروجی

require(tidyverse)
ggplot(data=BOD, aes(y=demand,x=Time)) +
  geom_point()

4- CHUNK چهارم و خروجی مربوطه

👇 ورودی

```{r}
#| collapse: true
#| message: true
#| warning: true
#| fig-align: center
#| fig-width: 3
#| fig-height: 2.5
require(tidyverse)
ggplot(data=BOD, aes(y=demand,x=Time)) +
  geom_point()
```

👇 خروجی

require(tidyverse)
ggplot(data=BOD, aes(y=demand,x=Time)) +
  geom_point()

Quarto ابزار تولید گزارش

چیستی و چرایی

برخی ویژگیهای Quarto

آماده‌سازی

نمونه هایی از اسناد و گزارش ها

ایجاد سند در Rstudio

مراحل ایجاد سند

بخش های مختلف سند

YAML

TEXT

Visual یا Source

فرمت متن ساده

مثال

Benthic Biodiversity experiment

مثال

CHUNK

کنترل نمایش کدها و خروجی

مثال از گزینه های تنظیم CHUNK

پرسش و پاسخ

با بهترین آرزوها