ჩემი დოკუმენტი

1. შესავალი

რა არის Quarto და რატომ არის მნიშვნელოვანი

Quarto არის ახალი, მძლავრი ინსტრუმენტი მონაცემთა მეცნიერებისთვის, რომელიც აერთიანებს კოდს, მის შედეგებს და თქვენს ნარატივს ერთ დოკუმენტში. ის შეიქმნა R Markdown-ის შემქმნელების მიერ და წარმოადგენს მის ევოლუციურ განვითარებას.

Quarto მნიშვნელოვანია შემდეგი მიზეზების გამო:

რეპროდუცირებადობა: Quarto დოკუმენტები სრულად რეპროდუცირებადია, რაც ნიშნავს, რომ თქვენი ანალიზი შეიძლება ზუსტად გაიმეოროს სხვამ.
მრავალფეროვანი აუთფუთი: Quarto მხარს უჭერს მრავალ ფორმატს, მათ შორის HTML, PDF, Word დოკუმენტებს და პრეზენტაციებს.
მრავალენოვანი მხარდაჭერა: მიუხედავად იმისა, რომ ჩვენ ვიყენებთ R-ს, Quarto ასევე მუშაობს Python-თან, Julia-სთან და სხვა ენებთან.

Quarto-ს უპირატესობები R Markdown-თან შედარებით

Quarto აუმჯობესებს R Markdown-ს რამდენიმე მნიშვნელოვანი გზით:

უნიფიცირებული სისტემა: Quarto აერთიანებს R Markdown ეკოსისტემის მრავალი პაკეტის ფუნქციონალს (rmarkdown, bookdown, blogdown, და ა.შ.) ერთ თანმიმდევრულ სისტემაში.
გაუმჯობესებული სინტაქსი: Quarto იყენებს უფრო ინტუიციურ სინტაქსს ზოგიერთი ოპერაციისთვის, მაგალითად, გრაფიკების ზომების კონტროლისთვის.
ვიზუალური რედაქტორი: Quarto მოდის ჩაშენებული ვიზუალური რედაქტორით, რაც ამარტივებს დოკუმენტის შექმნას მათთვის, ვინც ნაკლებად კომფორტულად გრძნობს თავს Markdown სინტაქსთან.
მრავალენოვანი მხარდაჭერა: Quarto თავიდანვე შეიქმნა მრავალენოვანი გამოყენებისთვის, რაც მას იდეალურს ხდის შერეული-ენის პროექტებისთვის.

ამ გაკვეთილში ჩვენ ვისწავლით Quarto-ს საფუძვლებს და შევქმნით ჩვენს პირველ Quarto დოკუმენტს R-ში.

2. Quarto დოკუმენტის სტრუქტურა

Quarto დოკუმენტი შედგება სამი ძირითადი ნაწილისგან:

YAML header

YAML (YAML Ain’t Markup Language) header არის დოკუმენტის დასაწყისში მოთავსებული მეტა-ინფორმაცია, რომელიც განსაზღვრავს დოკუმენტის გლობალურ პარამეტრებს. ის მოთავსებულია ორი — ხაზს შორის:

yaml

—

title: “ჩემი პირველი Quarto დოკუმენტი” author: “ჩემი სახელი” date: “2023-06-15” format: html # —

YAML header-ში შეგიძლიათ განსაზღვროთ ისეთი პარამეტრები, როგორიცაა სათაური, ავტორი, თარიღი, აუთფუთი ფორმატი და სხვა.

ტექსტური ნაწილი (Markdown ფორმატირება)

დოკუმენტის ძირითადი ტექსტი იწერება Markdown ფორმატში. Markdown არის მარტივი მარკირების ენა, რომელიც საშუალებას გაძლევთ ადვილად დააფორმატოთ ტექსტი:

სათაური 1

სათაური 2

სათაური 3

ბულეტ პუნქტი 1
ბულეტ პუნქტი 2

დანომრილი პუნქტი 1
დანომრილი პუნქტი 2

დახრილი და მუქი ტექსტი

ბმული

კოდის ბლოკები (chunks)

R კოდის ჩასასმელად გამოიყენება სპეციალური სინტაქსი, რომელსაც ეწოდება “chunk”:

print("გამარჯობა, Quarto!")

[1] "გამარჯობა, Quarto!"

კოდის ბლოკები იწყება {r} და მთავრდება სიმბოლოებით. ბლოკის პარამეტრები (მაგ., label, echo) იწერება #| სიმბოლოებით.

ეს სამი კომპონენტი - YAML header, Markdown ტექსტი და კოდის ბლოკები - ქმნის Quarto დოკუმენტის ძირითად სტრუქტურას. შემდეგ ნაწილში ჩვენ შევქმნით ჩვენს პირველ Quarto დოკუმენტს ამ სტრუქტურის გამოყენებით.

3. პირველი Quarto დოკუმენტის შექმნა

ახლა, როდესაც გავეცანით Quarto დოკუმენტის სტრუქტურას, შევქმნათ ჩვენი პირველი დოკუმენტი.

ახალი Quarto დოკუმენტის შექმნა RStudio-ში

გახსენით RStudio
აირჩიეთ File > New File > Quarto Document…
დიალოგურ ფანჯარაში მიუთითეთ სათაური (მაგ., “ჩემი პირველი Quarto დოკუმენტი”)
აირჩიეთ HTML ფორმატი
დააჭირეთ “Create”

YAML header-ის კონფიგურაცია

RStudio შექმნის ახალ დოკუმენტს საწყისი YAML header-ით. მოდიფიცირება გავუკეთოთ მას:

yaml

—

title: “ჩემი პირველი Quarto დოკუმენტი” author: “თქვენი სახელი” format: html html: toc: true code-fold: true # —

ეს YAML კონფიგურაცია ქმნის HTML დოკუმენტს სარჩევით (toc: true) და დაკეცილი კოდის ბლოკებით (code-fold: true).

მარტივი ტექსტის დამატება

YAML header-ის შემდეგ დავამატოთ მარტივი ტექსტი Markdown ფორმატში:

შესავალი

ეს არის ჩემი პირველი Quarto დოკუმენტი. Quarto საშუალებას მაძლევს:

შევქმნა ინტერაქტიული დოკუმენტები
გავაერთიანო კოდი და ტექსტი
გამოვაქვეყნო შედეგები სხვადასხვა ფორმატში

R კოდის ბლოკის დამატება და გაშვება

ახლა დავამატოთ R კოდის ბლოკი:

library(ggplot2)
data(iris)

ggplot(iris, aes(x = Sepal.Length, y = Petal.Length, color = Species)) +
  geom_point() +
  theme_minimal() +
  labs(title = "Iris მონაცემების ვიზუალიზაცია") +
  theme(text = element_text(family = "FiraGO")) #შეცვალე ეს ფონტი იმით რაც გიყენია, ან ინგლისურად დაწერე სათაური და #theme წაშალე საერთოდ

ეს კოდის ბლოკი ქმნის მარტივ scatter plot-ს Iris მონაცემთა ნაკრების გამოყენებით.

დოკუმენტის რენდერი

დოკუმენტის რენდერისთვის დააჭირეთ “Render” ღილაკს RStudio-ს ზედა პანელში ან გამოიყენეთ კლავიატურის კომბინაცია Ctrl+Shift+K (Windows/Linux) ან Cmd+Shift+K (Mac).

რენდერის შემდეგ, თქვენ უნდა დაინახოთ HTML დოკუმენტი სარჩევით, დაფორმატებული ტექსტით და ინტერაქტიული გრაფიკით.

4. კოდის ბლოკების ოპციები

Quarto-ში კოდის ბლოკებს აქვთ მრავალი ოპცია, რომლებიც საშუალებას გაძლევთ გააკონტროლოთ, როგორ სრულდება და გამოისახება კოდი თქვენს დოკუმენტში.

ძირითადი ოპციების გამოყენება

eval: კოდის შესრულება

eval: false ოპცია აჩერებს კოდის შესრულებას. ეს სასარგებლოა, როდესაც გსურთ კოდის ჩვენება შესრულების გარეშე:

ggplot(iris, aes(x = Sepal.Length, y = Petal.Length)) + geom_point()

echo: კოდის ჩვენება

echo: false ოპცია მალავს კოდს, მაგრამ აჩვენებს მის შედეგს:

  Sepal.Length    Sepal.Width     Petal.Length    Petal.Width   
 Min.   :4.300   Min.   :2.000   Min.   :1.000   Min.   :0.100  
 1st Qu.:5.100   1st Qu.:2.800   1st Qu.:1.600   1st Qu.:0.300  
 Median :5.800   Median :3.000   Median :4.350   Median :1.300  
 Mean   :5.843   Mean   :3.057   Mean   :3.758   Mean   :1.199  
 3rd Qu.:6.400   3rd Qu.:3.300   3rd Qu.:5.100   3rd Qu.:1.800  
 Max.   :7.900   Max.   :4.400   Max.   :6.900   Max.   :2.500  
       Species  
 setosa    :50  
 versicolor:50  
 virginica :50

include: კოდისა და შედეგის ჩვენება

include: false ოპცია ასრულებს კოდს, მაგრამ არ აჩვენებს არც კოდს და არც მის შედეგს:

ფიგურების ზომების კონტროლი

Quarto-ში ფიგურების ზომების კონტროლი მარტივია:

ggplot(iris, aes(x = Sepal.Length, y = Petal.Length, color = Species)) +
  geom_point() +
  theme_minimal()

Scatter plot of iris data

კეშირების გამოყენება

კეშირება სასარგებლოა გრძელვადიანი გამოთვლებისთვის. ის ინახავს შედეგებს და არ ასრულებს კოდს ხელახლა, თუ ის არ შეცვლილა:

# ვთქვათ, ეს არის გრძელვადიანი გამოთვლა
Sys.sleep(5)
print("გრძელვადიანი გამოთვლა დასრულდა!")

[1] "გრძელვადიანი გამოთვლა დასრულდა!"

ეს ოპციები საშუალებას გაძლევთ გააკონტროლოთ, როგორ ჩანს და სრულდება თქვენი კოდი Quarto დოკუმენტში, რაც ძალიან სასარგებლოა სხვადასხვა აუდიტორიისთვის დოკუმენტების მომზადებისას.

5. მონაცემთა ვიზუალიზაცია Quarto-ში

Quarto-ს ერთ-ერთი ძლიერი მხარეა მისი უნარი, შეუთავსოს R-ის ვიზუალიზაციის შესაძლებლობები ინტერაქტიულ დოკუმენტებს. ამ ნაწილში ჩვენ გამოვიყენებთ ggplot2-ს გრაფიკების შესაქმნელად და ვნახავთ, როგორ შეგვიძლია მათი ოპტიმიზაცია Quarto-სთვის.

ggplot2-ით გრაფიკის შექმნა

პირველ რიგში, შევქმნათ მარტივი scatter plot iris მონაცემთა ნაკრებისთვის:

library(ggplot2)

ggplot(iris, aes(x = Sepal.Length, y = Petal.Length, color = Species)) + geom_point() + theme_minimal() + labs(title = "Iris ყვავილების Sepal და Petal ზომები", x = "Sepal სიგრძე", y = "Petal სიგრძე")

Iris ყვავილების Sepal და Petal ზომების შედარება

გრაფიკის გაფორმება და ოპტიმიზაცია Quarto-სთვის

ახლა გავაუმჯობესოთ ჩვენი გრაფიკი Quarto-სთვის ოპტიმიზაციით:

library(ggplot2)
library(viridis)  # უკეთესი ფერთა პალეტისთვის

ggplot(iris, aes(x = Sepal.Length, y = Petal.Length, color = Species)) +
  geom_point(size = 3, alpha = 0.7) +
  geom_smooth(method = "lm", se = FALSE, aes(group = 1)) +
  scale_color_viridis(discrete = TRUE) +
  theme_minimal(base_size = 14) +
  labs(title = "Iris ყვავილების Sepal და Petal ზომების დამოკიდებულება",
       subtitle = "სხვადასხვა სახეობისთვის",
       x = "Sepal სიგრძე (სმ)", 
       y = "Petal სიგრძე (სმ)",
       color = "სახეობა") +
  theme(legend.position = "bottom", text = element_text(family = "FiraGO"))

Scatter plot showing the relationship between Sepal Length and Petal Length for different Iris species — გაუმჯობესებული Iris ყვავილების Scatter Plot

ამ გაუმჯობესებულ ვერსიაში ჩვენ:

გავზარდეთ გრაფიკის ზომა fig-width და fig-height ოპციებით.
დავამატეთ ალტერნატიული ტექსტი fig-alt ოპციით ხელმისაწვდომობისთვის.
გამოვიყენეთ viridis ფერთა პალეტა უკეთესი კონტრასტისთვის.
დავამატეთ ტრენდის ხაზი geom_smooth()-ით.
გავაუმჯობესეთ წერტილების ვიზუალური მხარე size და alpha პარამეტრებით.
დავამატეთ ინფორმაციული სათაური და ქვესათაური.
გავზარდეთ ფონტის ზომა უკეთესი წაკითხვადობისთვის.

Quarto-ში ვიზუალიზაციის ოპტიმიზაცია გულისხმობს არა მხოლოდ ლამაზი გრაფიკების შექმნას, არამედ მათ მორგებას დოკუმენტის ფორმატზე, ხელმისაწვდომობის გაუმჯობესებას და ინფორმაციის ეფექტურად გადმოცემას.

6. ცხრილების შექმნა

Quarto-ში ცხრილების შექმნა და გაფორმება შესაძლებელია რამდენიმე გზით. ამ ნაწილში ჩვენ განვიხილავთ ორ პოპულარულ მეთოდს: knitr::kable() ფუნქციას და gt პაკეტს.

knitr::kable() ფუნქციის გამოყენება

knitr::kable() არის მარტივი, მაგრამ მოქნილი ფუნქცია ცხრილების შესაქმნელად:

library(dplyr)


Attaching package: 'dplyr'

The following objects are masked from 'package:stats':

    filter, lag

The following objects are masked from 'package:base':

    intersect, setdiff, setequal, union

iris_summary <- iris %>% group_by(Species) %>% 
  summarize( Mean_Sepal_Length = mean(Sepal.Length), 
             Mean_Sepal_Width = mean(Sepal.Width), 
             Mean_Petal_Length = mean(Petal.Length), 
             Mean_Petal_Width = mean(Petal.Width))

knitr::kable(iris_summary, digits = 2)

Iris მონაცემების შეჯამება სახეობების მიხედვით
Species	Mean_Sepal_Length	Mean_Sepal_Width	Mean_Petal_Length	Mean_Petal_Width
setosa	5.01	3.43	1.46	0.25
versicolor	5.94	2.77	4.26	1.33
virginica	6.59	2.97	5.55	2.03

ცხრილის გაფორმება

knitr::kable()-ს შეგვიძლია დავამატოთ დამატებითი ფორმატირება kableExtra პაკეტის გამოყენებით:

library(kableExtra)


Attaching package: 'kableExtra'

The following object is masked from 'package:dplyr':

    group_rows

iris_summary %>%
  knitr::kable(digits = 2) %>%
  kable_styling(bootstrap_options = c("striped", "hover", "condensed"),
                full_width = FALSE) %>%
  add_header_above(c(" " = 1, "საშუალო ზომები (სმ)" = 4)) %>%
  column_spec(1, bold = TRUE) %>%
  row_spec(0, bold = TRUE)

გაფორმებული Iris მონაცემების შეჯამება
	საშუალო ზომები (სმ)
Species	Mean_Sepal_Length	Mean_Sepal_Width	Mean_Petal_Length	Mean_Petal_Width
setosa	5.01	3.43	1.46	0.25
versicolor	5.94	2.77	4.26	1.33
virginica	6.59	2.97	5.55	2.03

gt პაკეტის გამოყენება

gt პაკეტი გვთავაზობს უფრო მეტ კონტროლს ცხრილების გაფორმებაზე:

library(gt)

Warning: package 'gt' was built under R version 4.3.3

iris_summary %>%
  gt() %>%
  fmt_number(columns = -Species, decimals = 2) %>%
  cols_label(
    Species = "სახეობა",
    Mean_Sepal_Length = "საშუალო Sepal სიგრძე",
    Mean_Sepal_Width = "საშუალო Sepal სიგანე",
    Mean_Petal_Length = "საშუალო Petal სიგრძე",
    Mean_Petal_Width = "საშუალო Petal სიგანე"
  ) %>%
  tab_header(
    title = "Iris ყვავილების ზომების შეჯამება",
    subtitle = "საშუალო მნიშვნელობები სახეობების მიხედვით"
  ) %>%
  tab_source_note(
    source_note = "წყარო: R-ის ჩაშენებული iris მონაცემთა ნაკრები"
  ) %>%
  opt_row_striping() %>%
  tab_options(
    column_labels.font.weight = "bold",
    table.font.size = 12,
    heading.title.font.size = 16,
    heading.subtitle.font.size = 14
  )

Iris მონაცემების შეჯამება gt პაკეტის გამოყენებით
სახეობა	საშუალო Sepal სიგრძე	საშუალო Sepal სიგანე	საშუალო Petal სიგრძე	საშუალო Petal სიგანე
Iris ყვავილების ზომების შეჯამება
საშუალო მნიშვნელობები სახეობების მიხედვით
setosa	5.01	3.43	1.46	0.25
versicolor	5.94	2.77	4.26	1.33
virginica	6.59	2.97	5.55	2.03
წყარო: R-ის ჩაშენებული iris მონაცემთა ნაკრები

ეს მაგალითები გვიჩვენებს, როგორ შევქმნათ და გავაფორმოთ ცხრილები Quarto-ში. knitr::kable() არის კარგი არჩევანი მარტივი ცხრილებისთვის, ხოლო gt გვთავაზობს მეტ მოქნილობას რთული ფორმატირებისთვის. ორივე მეთოდი კარგად მუშაობს Quarto-სთან და საშუალებას გაძლევთ შექმნათ პროფესიული დონის ცხრილები თქვენს დოკუმენტებში.

7. დოკუმენტის რენდერი და ექსპორტი

Quarto-ს ერთ-ერთი მთავარი უპირატესობაა მისი უნარი, დაარენდეროს დოკუმენტები სხვადასხვა ფორმატში. ამ ნაწილში განვიხილავთ, როგორ მოვახდინოთ დოკუმენტის რენდერი HTML და PDF ფორმატებში.

HTML ფორმატში რენდერი

HTML არის Quarto-ს ნაგულისხმევი აუთფუთ ფორმატი. HTML დოკუმენტები ინტერაქტიულია და ადვილად გაზიარებადი ვებში.

თქვენი დოკუმენტის HTML-ში დასარენდერებლად:

RStudio-ში: დააჭირეთ “Render” ღილაკს ან გამოიყენეთ კლავიატურის კომბინაცია Ctrl+Shift+K (Windows/Linux) ან Cmd+Shift+K (Mac).

PDF ფორმატში რენდერი

PDF ფორმატი იდეალურია ბეჭდვისთვის ან ოფიციალური დოკუმენტებისთვის. PDF-ში დასარენდერებლად საჭიროა LaTeX-ის დაყენება თქვენს სისტემაზე.

PDF-ში დასარენდერებლად:

YAML header-ში მიუთითეთ PDF ფორმატი:

—

title: “ჩემი დოკუმენტი” format: pdf # —
RStudio-ში: დააჭირეთ “Render” ღილაკს.

PDF-ის დამატებითი ოპციები:

—

title: “ჩემი დოკუმენტი” format: pdf: toc: true number-sections: true colorlinks: true # — ”

მრავალფორმატიანი აუთფუთი

შესაძლებელია ერთი დოკუმენტის რამდენიმე ფორმატში დარენდერება:

—

title: “ჩემი დოკუმენტი” format: html: default pdf: default docx: default # —

რჩევები წარმატებული რენდერისთვის

დარწმუნდით, რომ ყველა საჭირო პაკეტი დაყენებულია.
გამოიყენეთ სწორი სინტაქსი YAML header-ში.
რეგულარულად დაარენდერეთ დოკუმენტი მუშაობის პროცესში შეცდომების ადრეულ ეტაპზე აღმოსაჩენად.
გამოიყენეთ RStudio-ს ვიზუალური რედაქტორი მარტივი ფორმატირებისთვის.

Quarto-ს მოქნილობა საშუალებას გაძლევთ შექმნათ ერთი წყარო დოკუმენტი და დაარენდეროთ ის სხვადასხვა ფორმატში საჭიროებისამებრ, რაც ძალიან მოსახერხებელია სხვადასხვა აუდიტორიისთვის ან გამოყენების სცენარებისთვის.

9. დასკვნა და შემდგომი ნაბიჯები

ამ გაკვეთილში ჩვენ გავეცანით Quarto-ს საფუძვლებს და ვისწავლეთ, როგორ შევქმნათ ინტერაქტიული დოკუმენტები R-ში. აი, რას მოიცავდა ჩვენი გაკვეთილი:

შევისწავლეთ Quarto-ს არსი და მისი უპირატესობები
გავეცანით Quarto დოკუმენტის სტრუქტურას
შევქმენით პირველი Quarto დოკუმენტი
ვისწავლეთ კოდის ბლოკების ოპციების გამოყენება
გავაკეთეთ მონაცემთა ვიზუალიზაცია Quarto-ში
შევქმენით და გავაფორმეთ ცხრილები
ვისწავლეთ დოკუმენტის რენდერი და ექსპორტი სხვადასხვა ფორმატში

შემდგომი ნაბიჯები

Quarto-ს შესაძლებლობები ამით არ შემოიფარგლება. რამდენიმე თემა, რომელიც შეგიძლიათ შეისწავლოთ Quarto-ში თქვენი უნარების გასაღრმავებლად:

ინტერაქტიული ვიზუალიზაციები: შეისწავლეთ plotly ან ინტერაქტიული ggplot2-ის გამოყენება Quarto-ში.
მრავალენოვანი დოკუმენტები: გაეცანით, როგორ შეგიძლიათ გამოიყენოთ R-თან ერთად Python ან Julia ერთ დოკუმენტში.
პრეზენტაციების შექმნა: Quarto-ს აქვს შესანიშნავი შესაძლებლობები პრეზენტაციების შესაქმნელად.
ვებსაიტებისა და ბლოგების შექმნა: Quarto-ს შეუძლია მთლიანი ვებსაიტებისა და ბლოგების გენერირება.
თანამშრომლობა და ვერსიების კონტროლი: შეისწავლეთ, როგორ გამოიყენოთ Quarto Git-თან ერთად ეფექტური თანამშრომლობისთვის.
კასტომიზაცია და თემები: გაეცანით Quarto-ს თემებს და ისწავლეთ საკუთარი თემების შექმნა.
გაფართოებული YAML ოპციები: შეისწავლეთ უფრო რთული YAML კონფიგურაციები სპეციფიკური საჭიროებებისთვის.

რესურსები შემდგომი სწავლისთვის

Quarto-ს ოფიციალური დოკუმენტაცია
R for Data Science (2e) - წიგნი, რომელიც მოიცავს Quarto-ს გამოყენებას
RStudio-ს Quarto ვებინარები და სასწავლო მასალები
Quarto Tip a Day - სასარგებლო რჩევები Quarto-ს შესახებ