نحوه ایجاد اسناد Word از R یا Python با Quarto

ایجاد خودکار اسناد Word با Quarto، یک سیستم انتشار فنی رایگان و منبع باز که با R، Python و سایر زبان های برنامه نویسی کار می کند، آسان است.

• مرحله ۱: نصب Quarto
• مرحله ۲: یک فایل سند Quarto ایجاد کنید
• مرحله ۳: افزودن متن با نحو Markdown
• مرحله ۴ (اختیاری): سند خود را از یک مرجع .docx
• مرحله ۵: نتایج کد R یا Python را به سند Word خود اضافه کنید
• مرحله ۶: رندر سند
• مرحله ۷ (اختیاری): چندین نسخه را با پارامترها به صورت خودکار انجام دهید

چندین راه برای ایجاد یک سند Word از زبان های برنامه نویسی وجود دارد، از جمله R Markdown و بسته افسر با R و کتابخانه python-docx در پایتون. اما یکی از جدیدترین و جذاب‌تر Quarto است، یک سیستم انتشار فنی رایگان و منبع باز از RStudio (اکنون Posit) که بومی پایتون و جولیا و همچنین R.

یکی از مزایای بزرگ Quarto این است که بر خلاف بسته های مخصوص Word، از همان فایل Quarto با تغییرات جزئی می توان برای تولید ده ها فرمت خروجی علاوه بر Word، از جمله PowerPoint، HTML و PDF استفاده کرد. (بیشتر بیاموزید: “Quarto چیست؟ RStudio نسل بعدی R Markdown را عرضه می کند”.) علاوه بر این، می توانید ایجاد گزارش های Word را به طور خودکار انجام دهید و نتایج تجزیه و تحلیل و کد تجسم خود را اضافه کنید.< /p>

در اینجا نحوه استفاده از Quarto برای ایجاد اسناد Word آمده است.

مرحله ۱: نصب Quarto

از آنجایی که Quarto یک کتابخانه خاص زبان نیست، آن را مانند هر نرم افزار مستقل دیگری نصب می کنید. می‌توانید دانلودهای باینری برای Windows، macOS و Linux را در صفحه “شروع به کار” Quarto پیدا کنید.

اگر کاربر R هستید و نسخه به‌روزی RStudio دارید، Quarto باید به‌طور پیش‌فرض گنجانده شود. نیازی نیست Quarto را جداگانه نصب کنید.

اگر می‌خواهید از Quarto در کد ویژوال استودیو استفاده کنید، برنامه افزودنی Quarto علاوه بر نرم افزار کاربردی Quarto. برای ارائه اسناد Quarto که شامل کد پایتون هستند، سیستم من همچنین به من دستور داد که Jupyter Notebook را با اجرای python3 -m pip install jupyter نصب کنم.

می توانید فایل های Quarto را با هر ویرایشگر متن ساده و ترمینال خود ایجاد و رندر کنید، همانطور که با اسکریپت های R یا Python می توانید، زیرا آنها متن ساده هستند و فایل های باینری نیستند. با این حال، همه ابزارهای داخلی یک IDE، مانند پیشنهادات تکمیل کد و دکمه رندر را از دست خواهید داد.

مرحله ۲: یک فایل سند Quarto ایجاد کنید

هنگامی که Quarto را نصب کردید، می توانید یک فایل Quarto جدید در IDE خود به روش معمول ایجاد کنید، یا File > New File > Quarto Document (نه Quarto Presentation) در RStudio، یا File > New File در VS Code و “Quarto” را به عنوان زبان انتخاب کنید.

در RStudio، می‌توانید از بین چند فرمت خروجی سند Quarto انتخاب کنید. Word را انتخاب کنید و سپس می توانید به طور خودکار یک سند نمونه Word یا یک سند خالی ایجاد کنید. تا زمانی که با سینتکس Quarto آشنا نشده باشید می‌تواند مفید باشد تا ببینید نمونه چگونه است.

نمونه سند Quarto ایجاد شده توسط RStudio هنگام انتخاب خروجی Word.

سرصفحه پیش‌فرض YAML در RStudio شامل عنوان، قالب خروجی (در این مورد docx برای Word) و ویرایشگر (WYSIWYG تصویری یا منبع) است.

اگر با یک سند خالی در VS Code شروع می‌کنید، می‌توانید سرصفحه اصلی YAML را در بالا اضافه کنید:

---
title: "Your document title"
format: docx
---

تا آنجا که من می دانم، ویرایشگر WYSIWYG Quarto در VS Code وجود ندارد، بنابراین دلیلی برای تعیین ویرایشگر وجود ندارد.

سپس شروع به ایجاد محتوای خود کنید.

مرحله ۳: اضافه کردن متن با نحو Markdown

Quarto از نسخه Pandoc از نحو Markdown استفاده می کند< /a> برای نوشتن متن. این شامل زیرخط‌های تکی در اطراف متنی که می‌خواهید به صورت مورب، دو ستاره برای متنی که می‌خواهید پررنگ شود، خطوط خالی بین پاراگراف‌ها، دو یا چند فاصله در انتهای یک خط برای ایجاد یک شکست خط، و نمادهای هش در ابتدای یک خط است. برای نشان دادن اندازه قلم هدر. یک هش منفرد بزرگترین اندازه فونت، h1 را نشان می دهد. دو دومین بزرگتر است، h2; و غیره.

برخی از قالب‌های سند مبتنی بر CSS که برای قالب‌های خروجی Quarto HTML طراحی شده‌اند، هنگام صادرات به Word کار نمی‌کنند. با این حال، می‌توانید یک سند Word با سبک مرجع جداگانه با فونت ایجاد کنید. سبک‌ها، اندازه‌ها و مواردی از این دست برای سند شما.

کد زیر باید در ترمینال شما (نه کنسول R یا پایتون) اجرا شود تا یک سند سبک پیش‌فرض Word ایجاد شود، در این مثال به نام my_doc_style.docx (شما می‌توانید آن را هر چیزی بنامید):< /p>

quarto pandoc -o my-doc-style.docx \
   --print-default-data-file reference.docx

این یک فایل Word .docx معمولی ایجاد می کند، نه یک الگوی Microsoft Word .dotx. می‌توانید با باز کردن پانل Styles از روبان Word، .docx مرجع خود را باز کنید و سبک‌های آن را مانند هر سند Word سفارشی کنید.

برای استفاده از الگو در سند Quarto، آن را با دستور زیر به سربرگ YAML سند اضافه کنید:

format: 
  docx: 
    reference-doc: my-doc-style.docx

سفارشی‌سازی‌های دیگری برای اسناد Quarto Word وجود دارد، مانند افزودن فهرست مطالب یا شماره‌گذاری بخش، که می‌توانید آن‌ها را در مستندات Quarto برای Word.

مرحله ۵: نتایج کد R یا Python را به سند Word خود اضافه کنید

یکی از بهترین چیزها در مورد تولید سند Word از R یا Python، امکان اجرای کد و افزودن نتایج به سند شما – از جمله گرافیک است.

این کار را با افزودن تکه‌های کد به فایل Quarto خود انجام می‌دهید، که با سه بکتیک تنظیم می‌شوند، مانند این برای R:

```{r}
# R code here
```

یا این برای پایتون:

```{python}
# Python code here
```

می‌توانید گزینه‌هایی را برای یک قطعه کد تنظیم کنید، مانند نمایش کد (echo)، اجرای کد (eval)، نمایش پیام‌های هشدار کد، و غیره. گزینه‌های تکه‌ای با #|  (اغلب به عنوان “هش لوله”) برای R، Python یا Julia شروع می‌شوند.

گزینه‌های قطعه زیر نتایج کد R را در یک تکه نشان می‌دهند اما کد را در سند Word نشان نمی‌دهند:

```{r}
#| echo: false
#| eval: true
# R code here
```

گزینه های دیگر عبارتند از #| fig-cap: شرح من برای شرح شکل، #| warning: false برای نمایش ندادن هیچ پیام هشداری هنگام اجرای کد، و #| cache: true برای ذخیره کردن نتایج یک قطعه محاسباتی فشرده که در آن داده ها تغییر نمی کنند.

با استفاده از !expr با نحوی مانند 

می‌توانید کد را در گزینه figure caption اجرا کنید.

#| fig-cap: !expr paste("Data pulled on"Sys.Date())

مرحله ۶: رندر سند

با استفاده از دکمه Render، میانبر صفحه کلید Ctrl/Cmd + Shift + K یا با دستور ترمینال 

می‌توانید یک سند Quarto را در RStudio یا VS Code رندر کنید.

quarto render my_quarto_document.qmd --to docx

برای سندی به نام my_quarto_document.

کاربران R همچنین می‌توانند از دستور پکیج Quarto R

استفاده کنند

quarto_render("my_quarto_document")

توجه: گاهی اوقات، سند اولیه Word پیش‌نمایش که از RStudio در نسخه‌های اولیه ظاهر می‌شد، همیشه نمودار من را نشان نمی‌داد. به نظر می رسد که رفع شده است. با این حال، اگر این اتفاق برای شما افتاد، سعی کنید فایل .docx اولیه را به عنوان یک سند Word جدید و قابل ویرایش کپی کنید، زیرا این مشکل برای من حل شد.

مرحله ۷ (اختیاری): چندین نسخه را با پارامترها خودکار کنید

امکان ایجاد فایل های Word با نتایج کد شما نه تنها برای اسناد یکبار مصرف مفید است. همچنین به شما امکان می‌دهد گزارش‌های منظم داده و به‌روزرسانی‌ها را با کدی ساده کنید که داده‌های جدید را از یک منبع خارجی استخراج می‌کند، محاسبات جدید را اجرا می‌کند و با یک تماس رندر، نمودارهای به‌روز تولید می‌کند.

اما Quarto همچنین این قابلیت را دارد که پارامترها را به یک گزارش اضافه کند، که مانند متغیرهایی هستند که در هنگام رندر به صورت خارجی تعریف شده اند. این به شما امکان می دهد از یک گزارش به عنوان الگو استفاده کنید و همان گزارش را برای پارامترهای مختلف مانند شهرها یا مناطق ایجاد کنید. به عنوان مثال، اگر نیاز به اجرای یک گزارش برای هر یک از ۱۰ شهر داشتید، city می تواند به عنوان پارامتری در سربرگ YAML سند شما تعریف شود، مانند

---
title: "My Quarto Document"
params:
city: New York
---

که پارامتری به نام شهر را با مقدار پیش‌فرض نیویورک تنظیم می‌کند. سپس می‌توانید با params$city به مقدار پارامتر شهر در کد R خود دسترسی پیدا کنید، مانند 

```{r}
#| echo: false
cat("This report is about", params$city)
```

برای ایجاد چندین گزارش در R با استفاده از یک سند Quarto اما مقادیر متفاوت برای پارامتر، من معمولاً یک تابع برای رندر کردن سند خود ایجاد می‌کنم و سپس از تابع walk() بسته purrr برای اجرای من استفاده می‌کنم. عملکرد در لیستی از موارد به عنوان مثال، اگر سند Quarto پارامتری من به نام params_test.qmd با یک پارامتر به نام شهر باشد، این می تواند تابع رندر من در R باشد:

render_my_doc <- function(the_city = "New York", the_doc = "params_test.qmd") {
quarto::quarto_render(input = the_doc, execute_params = list("city" = the_city), 
   output_file = paste0("test_", the_city, ".docx"), output_format = "docx")
}

و به این صورت از تابع خود برای تولید سه سند جداگانه برای نیویورک، شیکاگو و لس آنجلس استفاده می کنم:

library(purrr)
walk(list("New York", "Chicago", "Los Angeles"), render_my_doc)

نحو پایتون کمی متفاوت است و بر اساس کتابخانه کارخانه کاغذسازی است. به عنوان مثال، تعریف یک پارامتر در یک قطعه کد پایتون انجام می شود که شبیه

است

```{python}
#| tags: [parameters]
city = 'Boston'
```

می‌توانید اطلاعات بیشتری درباره پارامترسازی اسناد پایتون در سند پارامترهای Quarto بخوانید. /a>.

اگر به R و نکات بیشتری در مورد R علاقه دارید، به بیشتر با R انجام دهید بروید!