راهنمای مبتدی برای استفاده از جاوا اسکریپت قابل مشاهده، R و پایتون با Quarto

استفاده از Quarto با جاوا اسکریپت قابل مشاهده یک راه حل عالی برای کاربران R و Python است که می خواهند گزارش های تعاملی و بصری جذاب تری ایجاد کنند.

• چرا از Quarto با جاوا اسکریپت قابل مشاهده استفاده کنیم؟
• Quarto را در IDE خود نصب و راه اندازی کنید
• استفاده از جاوا اسکریپت قابل مشاهده در سند Quarto
• وارد کردن داده به Observable از R یا Python
• عملکرد transpose()
• وارد کردن مستقیم داده های خارجی به Observable
• ترتیب سلول در Observable در مقابل Jupyter یا R Markdown

یک گزینه جذاب جدید برای افرادی وجود دارد که می‌خواهند بحث و تحلیل داده‌ها را در R یا Python انجام دهند، اما در جاوا اسکریپت تجسم کنند: Quarto.

این مقاله به شما نشان می‌دهد که چگونه یک سند Quarto را برای استفاده از جاوا اسکریپت قابل مشاهده تنظیم کنید، از جمله نحوه ارسال داده‌ها از R یا Python به یک قطعه کد قابل مشاهده. در قسمت ۲، خواهید فهمید که چگونه جاوا اسکریپت قابل مشاهده را با نوت بوک های قابل مشاهده بیاموزید — و چرا این کار ارزش انجام این کار را دارد حتی اگر فقط قصد استفاده از جاوا اسکریپت را در Quarto دارید. قسمت ۳ اصول تجسم داده ها با جاوا اسکریپت قابل مشاهده را به شما می دهد، از جمله نحوه تعاملی کردن طرح های خود.

بیایید شروع کنیم!

چرا از Quarto با جاوا اسکریپت قابل مشاهده استفاده کنیم؟

Quarto یک پلتفرم انتشار فنی منبع باز از RStudio است که به طور بومی از Python، R، Julia، و JavaScript قابل مشاهده پشتیبانی می کند – یک طعم جاوا اسکریپت که برای تجزیه و تحلیل داده ها طراحی شده است. استفاده از Quarto با Observable می تواند برای کاربران R و Python که می خواهند از جاوا اسکریپت نیز استفاده کنند، گزینه قانع کننده ای باشد. در اینجا چند دلیل وجود دارد:

• Quarto شامل دو تابع ساده و تک خطی با استفاده آسان برای انتقال داده ها از Python یا R برای استفاده در جاوا اسکریپت است.
• ترکیب نتایج حاصل از کدهای نوشته شده به چندین زبان در یک سند و افزودن متن توضیحی بسیار ساده است.
• یک سند Quarto می‌تواند چندین قالب HTML ایجاد کند: یک صفحه، اسلایدهای reveal.js و وب‌سایت‌های Quarto. (Quarto می‌تواند ده‌ها فرمت ثابت را نیز ایجاد کند، مانند PDF یا Word، اما ادغام Observable برای آن‌ها طراحی نشده است. در حال حاضر، هیچ راهی داخلی برای صادرات خروجی جاوا اسکریپت به عنوان تصاویر استاتیک وجود ندارد.)

اگر قبلاً نمودارهایی را با R یا Python ایجاد کرده اید، چرا در Observable تجسم کنید؟ یکی از دلایل این است که Observable دارای تعامل داخلی است. با استفاده از Observable، راه‌های ساده‌ای برای افزودن فیلترهای تعاملی بر روی داده‌های شما وجود دارد که آنچه را که در جداول و نمودارها ظاهر می‌شود کنترل می‌کند.

به‌علاوه، فایل‌های HTML ارائه‌شده Quarto را می‌توان بر روی هر سرور وب میزبانی کرد یا به صورت محلی با یک مرورگر ساده باز کرد، بدون نیاز به نصب زبان یا چارچوب جداگانه. این مورد در مورد گزینه هایی مانند Shiny برای R یا Dash برای Python صدق نمی کند (alpha Shiny برای Python می تواند بدون سرور Shiny اجرا شود، اما هنوز آماده تولید نیست). اگر می‌خواهید تجزیه و تحلیل داده‌ها در Python و R را با واکنش‌پذیری ترکیب کنید، استفاده از Quarto با Observable یک گردش کار زیبا ارائه می‌دهد.

در نهایت، Observable با هدف همکاری راه‌اندازی شد، بنابراین یافتن و استفاده از کد منبع باز شخص دیگری نسبتاً آسان است.

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

Quarto را در IDE خود نصب و راه اندازی کنید

Quarto یک برنامه نرم افزاری جداگانه است و یک بسته R یا Python نیست. اگر از R استفاده می‌کنید و نسخه به‌روزی از RStudio دارید، نرم‌افزار Quarto همراه است. اگر از Python یا R در Visual Studio Code (VS Code) استفاده می‌کنید، برنامه نرم‌افزار Quarto را از صفحه شروع Quarto و برنامه افزودنی VS Code Quarto.

نصب Quarto

اگر هرگز از Quarto استفاده نکرده‌اید، می‌توانید دستورالعمل‌های نصب Quarto و راه‌اندازی IDE را در نحوه ایجاد اسناد Word از R یا Python در Quarto پیدا کنید. (اگرچه بیشتر آن مقاله بر روی Word تمرکز دارد، دستورالعمل‌های راه‌اندازی کلی یکسان است.) علاوه بر این، اگر هرگز از Markdown استفاده نکرده‌اید، راهنمای کاربر Pandoc شامل یک نمای کلی است.

استفاده از جاوا اسکریپت قابل مشاهده در سند Quarto

برای گنجاندن جاوا اسکریپت قابل مشاهده در سند Quarto، از {ojs} برای یک قطعه کد قابل مشاهده استفاده کنید، در مقابل {r} برای کد R و { python} برای پایتون. قبل از گزینه‌های قطعه، یک #| در R و Python وجود دارد، اما //| برای Observable است. این یک مثال است:

```{ojs}
//| echo: false
//| eval: true 
YOUR CODE GOES HERE
```

کد بالا یک قطعه کد ojs ایجاد می‌کند که کد را در آن اجرا می‌کند اما آن کد اصلی را در سند نهایی نمایش نمی‌دهد.

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

وارد کردن داده به Observable از R یا Python

می‌توانید داده‌ها را در R یا Python وارد کنید، بحث کنید و تجزیه و تحلیل کنید و سپس آن نتایج را با تابع ojs_define() به Observable ارسال کنید. مایا گانز، یک توسعه دهنده در Atorus که چندین سال پیش کارآموز در RStudio بود، گفت: “این جادو است.” برای کاربران R و Python برای افزودن جاوا اسکریپت به گردش کار خود، “به طور چشمگیری مانع ورود را کاهش می دهد”.

برای ارسال داده‌های درهم‌آمیز از R یا Python به جاوا اسکریپت قابل مشاهده، نحو این است:

```{r}
ojs_define(my_ojs_data = my_wrangled_r_object)
```

توجه داشته باشید که ojs_define() همچنین در تکه‌های کد پایتون کار می‌کند. با این حال، از زمان نوشتن این مقاله، نمی‌توانید یک قطعه R یا Python را با ojs_define() به صورت تعاملی در RStudio اجرا کنید. اگر سعی کنید روی نماد اجرای قطعه کلیک کنید، شکست می‌خورد. در حال حاضر،  ojs_define() فقط زمانی کار می‌کند که Quarto کل سند را یکباره ارائه کند.

یکی از سخنگویان RStudio گفت که آنها امیدوارند در آینده تجربه بهتری داشته باشند، اما از آنجا که اشتباه کردن تجربه کاربری (UX) آسان است، در حال حاضر آنها بر اجرای کل سند تمرکز کرده اند.

عملکرد transpose()

یک مرحله دیگر برای استفاده از داده‌های R یا Python در Observable وجود دارد: transpose().

تجسم‌های جاوا اسکریپت معمولاً از قالب داده متفاوتی نسبت به قاب‌های داده مستطیلی که معمولاً در R یا Python مورد نیاز هستند استفاده می‌کنند. به عنوان مثال، در زیر نمونه ای جزئی از داده ها برای یک نمودار چند خطی از وب سایت Apache ECharts:

series: [
    {
      name: 'Email',
      type: 'line',
      stack: 'Total',
      data: [120, 132, 101, 134, 90, 230, 210]
    },
    {
      name: 'Search Engine',
      type: 'line',
      stack: 'Total',
      data: [820, 932, 901, 934, 1290, 1330, 1320]
    }
  ]

این آرایه‌ای از اشیاء جاوا اسکریپت است، نه قالب ردیف‌ها و ستون‌هایی که توسط کتابخانه‌هایی مانند ggplot2 استفاده می‌شود. . خوشبختانه، یک تابع واحد وجود دارد، transpose()، که فریم های داده R یا Python ارسال شده به Observable را به فرمت مورد نیاز Observable تبدیل می کند. اگر فراموش کردید که از transpose() روی داده‌های وارد شده با ojs_define() استفاده کنید، و سپس سعی کنید از آن داده‌ها در Observable استفاده کنید، ممکن است با خطایی مانند این روبرو شوید:< /p>

TypeError: e is not iterable

اگر آن خطا را مشاهده کردید، بررسی کنید که آیا از transpose(my_ojs_data) در داده‌های وارد شده با ojs_define() استفاده کرده‌اید یا خیر.

شما می توانید با چیزی شبیه به این یک شیء انتقال یافته جدید در یک قطعه کد قابل مشاهده ایجاد کنید:

```{ojs}
mydata = transpose(my_ojs_data)
```

سپس، از mydata در همه عملکردهای بعدی خود استفاده کنید. یا، می‌توانید هر بار که به مجموعه داده‌های خود در Observable دسترسی پیدا می‌کنید، به transpose(my_ojs_data)  مراجعه کنید.

در نهایت، توجه داشته باشید که ojs_define() و transpose() ویژه اسناد Quarto هستند، نه نوت‌بوک‌های Observable که در پلتفرم وب Observable میزبانی می‌شوند. در ObservableHQ.com. نوت‌بوک‌های میزبان کد R یا Python را اجرا نمی‌کنند.

وارد کردن مستقیم داده های خارجی به Observable

همچنین می‌توانید داده‌های خارجی را مستقیماً به Observable وارد کنید. در اینجا نحوی برای وارد کردن یک فایل CSV محلی با تابع  FileAttachment()  Observable در داخل یک قطعه کد ojs آمده است:

mydata = FileAttachment("my_csv-file.csv").csv({ typed: true })

({ typed: true }) از FileAttachment() می‌خواهد تا انواع ستون‌ها را حدس بزند. برای تجزیه صحیح داده‌ها برای استفاده از ojs، حتماً .csv() بعد از File.Attachment()  را برای یک فایل CSV اضافه کنید.

چند فرمت دیگر با FileAttachment() نیز کار می‌کنند، مانند FileAttachment().json().

برای یک فایل CSV که به صورت آنلاین میزبانی می‌شود، می‌توانید از عملکرد csv()  کتابخانه جاوا اسکریپت D3 استفاده کنید:

mydata = d3.csv("https://www.domain.com/myfile.csv")

D3.js به طور پیش‌فرض در راه‌اندازی قابل مشاهده Quarto گنجانده شده است.

ترتیب سلول در Observable در مقابل Jupyter یا R Markdown

در یک دفترچه یادداشت Jupyter یا فایل R Markdown، سلول‌های کد هنگام ارائه سند از بالا به پایین اجرا می‌شوند. تنها استثنا این است که به‌جای اجرای یک‌باره کل فایل، سلول‌ها را به‌صورت جداگانه و با ترتیبی متفاوت راه‌اندازی کنید. این بدان معناست که شما نمی‌توانید سلولی داشته باشید که قبل از سلولی که  تعریف می‌کند، یک متغیر x را فراخوانی کند. بنابراین، موارد زیر یک خطا ایجاد می کند:

y = x * 10
x = 6 + 12

علاوه بر این، نمی‌توانید تابعی را که در بالای سلولی که تابع را ایجاد کرده‌اید فراخوانی کنید.

اما، در Observable، سلول‌ها به ترتیبی که نیاز دارند اجرا می‌شوند—که به آن یک جریان داده واکنشی. این بدان معناست که می‌توانید به x با y = x * 10 در یک سلول  بالا سلولی که x را تعریف می‌کند، رجوع کنید. و، می توانید از یک تابع سفارشی در بالای نوت بوک خود استفاده کنید، اما در پایان آن را تعریف کنید. این بخشی از واکنش‌پذیری داخلی Observable است: اگر مقدار متغیری در یک سلول تغییر کند، همه سلول‌هایی که از متغیر استفاده می‌کنند به‌روزرسانی می‌شوند، نه تنها سلول‌های زیر.

اما اگرچه این برای تعامل مفید است، به این معناست که شما نمی توانید یک متغیر را بیش از یک بار تعریف کنید؛ نه مگر اینکه در داخل یک بلوک کد در همان سلول باشد، مانند عبارت if ... else که با پرانتز احاطه شده است. در غیر این صورت، Observable نمی داند کدام یک باید اول اجرا شود.

چند تفاوت دیگر بین جاوا اسکریپت Observable و “vanilla” وجود دارد که می‌توانید در مورد آنها در Observable جاوا اسکریپت نیست. بعدی: یادگیری جاوا اسکریپت قابل مشاهده با نوت بوک های قابل مشاهده.