Сохранение результатов работы

Трушин Иван Витальевич

младший научный сотрудник
НИИ антимикробной химиотерапии
ФГБОУ ВО СГМУ Минздрава России

🙋‍♂️ Проверка связи

Если слышно/видно поставьте в чат плюс +

🎯 Цели занятия

Научиться сохранять таблицы в Excel с оформлением
Узнать, как лучше представлять табличные данные
Познакомиться с технологией публикации Quarto
Написать первый отчет

1️⃣ Сохранение таблиц в Excel

Работа с Excel с пакетом `openxlsx`

# Быстрое сохранение нескольких таблиц
write.xlsx(
  list("Машины" = mtcars, "Цветы" = iris), 
  file ="data/myworkbook.xlsx", 
  asTable = TRUE)

# Создание книги
wb <- createWorkbook()

# Добавление листа
sheet = "Данные"
addWorksheet(wb, sheetName = sheet, 
  gridLines = TRUE)

# Объединение ячеек
mergeCells(wb, sheet, 
           cols = 1:ncol(iris), 
           rows = 1)

# Запись текста
writeData(wb, sheet, "Заголовок для таблицы", 
  colNames = FALSE, rowNames = FALSE, 
  startCol = 1, startRow = 1)

# Запись таблицы
writeData(wb, sheet, iris, 
  colNames = TRUE, rowNames = FALSE,
  startCol = 1, startRow = 2)

# Установка ширины столбцов
setColWidths(wb, sheet,
  cols = 1:ncol(iris), widths = "auto")


# Добавление стилей оформления
tableHeaderStyle <- createStyle(
  fontSize = 12, fontColour = "black",  
  halign = "center", valign = "center", 
  fgFill = "lightcyan2",
  border = "TopBottomLeftRight", 
  borderColour = "black",
  textDecoration = "bold", wrapText = TRUE)

addStyle(wb, sheet, tableHeaderStyle, rows = 2, 
         cols = 1:ncol(iris), gridExpand = TRUE)
         
# Сохранение документа
saveWorkbook(wb,  "data/openxlsx_report.xlsx", 
  overwrite = TRUE)

2️⃣ Оформление таблиц

10 рекомендаций для лучших таблиц

Ten Guidelines for Better Tables

Выделение заголовков столбцов таблицы

Использование визуальных разделителей вместо сетки

Выравнивание чисел по правому краю

Важно также обращать внимание на то, каким шрифтом написаны цифры

Выравнивание текста по левому краю

Адекватный уровень точности

Направление внимания с помощью отступов

Единицы измерения

Выделение выбросов и важных значений

Группировка данных

Использование дополнительных визуализаций

Оформление таблиц с `flextable`

mtcars  %>% flextable() %>% theme_vanilla() %>% save_as_docx(path = "mytable.docx")

Пример оформления таблицы с `flextable`

ft <- data %>% 
 flextable(col_keys = c("diagnosis","sex","n","percent_overall")) %>%
 # Подпись таблицы.
 set_caption("Типы диагнозов") %>%
 # Добавление строки заголовка.
 add_header_lines("Вторая строка заголовка") %>%
 # Добавление строки примечания.
 add_footer_lines("На основании данных из набора cytomegalovirus")
 width(j = c(1,2), width = 3, unit = "cm") %>%
 width(j = c(3,4,5), width = 2, unit = "cm")
 # Выбор первой строки заголовка.
 font(fontname = "Times New Roman", i = 1, part = "header") %>%
 # Оформление примечаний.
 font(fontname = "Times New Roman", part = "footer") %>%
 fontsize(size = 9, part = "footer") %>%
 italic(part = "footer") %>%
 # Заголовки столбцов включают две строки.
 bold(i = c(2,3), part = "header") %>%
 # Выделение столбца диагнозов курсивом.
 italic(j = "diagnosis", part = "body")  %>%
 # Выделение строки итогов на основе значения ячейки.
 bold(i = ~ diagnosis == "Всего", part = "body")

Оформление таблиц с `gt`

mtcars  %>% gt() %>% gt_theme_pff() %>% gtsave("gt.html")

Пример оформления таблицы с `gt`

gt <- data %>%  gt()
 tab_header(title = "Типы диагнозов", 
            subtitle = "Вторая строка заголовка") %>% 
 tab_source_note(source_note = md("На основании данных из набора `cytomegalovirus`")) %>%
 tab_footnote(footnote = "Доля пациента в рамках диагноза",
              locations = cells_column_labels(columns = percent_diag)) %>%
 tab_footnote(footnote = "Доля пациентов в рамках исследования",
              locations = cells_column_labels(columns = percent_overall)) %>% 
 fmt(columns = c(1:2), fns = str_to_title) %>%
 tab_style(
   locations = cells_body(columns = "percent_diag", rows = percent_diag > 50),
   style = cell_text( color = 'red', weight = 'bold')
 )

3️⃣ Научно издательская система `quarto`

Что такое `quarto`

Quarto® — это научно-техническая издательская система с открытым исходным кодом, построенная на основе Pandoc и использующая Markdown для разметки.

Pandoc — универсальный конвертер для работы с текстовыми документами для форматирования научных и технических текстов, поддерживающий более 40 различных форматов.

Quarto CLI — это интерфейс командной строки, который преобразует обычные различные форматы (.md, .rmd, .qmd или .ipynb / Jupyter notebook) в статические отчеты PDF / Word / HTML, интерактивные книги, веб-сайты, блоги, презентации и многое другое.

Quarto позволяет создавать динамический контент с помощью Python, R, Julia и Observable JavaScript.

Статьи

Веб-страницы

Книги

Презентации

Больше примеров разработок в Quarto

https://quarto.org/docs/gallery/

Как работает `quarto`

Структура документа `quarto`

Метаданные (YAML)

---
format: html
---

Исполняемый код (R/Python/Julia/…)

```{r}
#| eval: true
library(dplyr)
mtcars %>% group_by(cyl) %>% summarize(mean = mean(mpg), .groups = "drop")
```

# A tibble: 3 × 2
    cyl  mean
  <dbl> <dbl>
1     4  26.7
2     6  19.7
3     8  15.1

Текст (Markdown/HTML)

# Heading 1
This is a sentence with some **bold text**, some *italic text* and an [image](image.png).

Markdown (форматирование текста)

Markdown	Вывод
`курсив и полужирный`	курсив и полужирный
`надстрочный^2^ / подстрочный~2~`	надстрочный² / подстрочный₂
`~~зачеркнутый~~`	~~зачеркнутый~~
`verbatim code`	`verbatim code`

Markdown (заголовки)

Markdown	Вывод
`# Заголовок 1`	Заголовок 1
`## Заголовок 2`	Заголовок 2
`### Заголовок 3`	Заголовок 3
`#### Заголовок 4`	Заголовок 4

Markdown (ссылки и рисунки)

Markdown	Вывод
`<https://smolgmu.ru/>`	https://smolgmu.ru/
`[СПСА](https://dd.smolgmu.ru/)`	СПСА
`![Caption](logo-dd.png)`	Caption
`[![Caption](logo-dd.png)](https://smolgmu.ru/)`
`[![Caption](logo-dd.png)](https://smolgmu.ru/ "СГМУ")`

Markdown (списки)

Markdown (таблицы)

Markdown

| Справа | Слева | По умолчанию | По центру |
|-------:|:------|--------------|:---------:|
|     12 | 12    | 12           |    12     |
|    123 | 123   | 123          |    123    |
|      1 | 1     | 1            |     1     |

Вывод

Справа	Слева	По умолчанию	По центру
12	12	12	12
123	123	123	123
1	1	1	1

Формулы в Quarto

Математические формулы в Quarto используют разделители $ для встроенных математических элементов текста и разделители $$ для выносной математики на основе LaTeX-синтаксиса.

Диаграммы Mermaid

Подерживается вывод диаграмм, например в формате Mermaid.

flowchart TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]

flowchart TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]

Выносные блоки

:::{.callout-note}
## Заметка 

Этот элемент будет использоваться для заметок.
:::

:::{.callout-caution appearance="simple"}
## Важно

Этот элемент будет использоваться для предупреждений.
:::

:::{.callout-warning icon=false}
## Предостережение

Этот элемент будет использоваться для предостережений.
:::

Заметка

Этот элемент будет использоваться для заметок.

Замечание

Этот элемент будет использоваться для важных замечаний.

Важно

Этот элемент будет использоваться для предупреждений.

Предостережение

Этот элемент будет использоваться для предостережений.

Совет

Этот элемент будет использоваться для рекомендаций и советов.

Блоки кода

```{r}
#| output-location: column
#| label: fig-airquality
#| fig-cap: Temperature and ozone level.
#| warning: false

library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess"
)
```

Возможности для рендеринга

Используйте кнопку Render в RStudio IDE для рендеринга файла и предварительного просмотра выходных данных.

Quarto как R-библиотека:

library(quarto)
quarto_render("document.qmd") # defaults to html
quarto_render("document.qmd", output_format = "pdf")

Quarto в командной строке:

quarto render document.qmd # defaults to html
quarto render document.qmd --to pdf
quarto render document.qmd --to docx

Основные сервисы для веб-публикации

Вы можете опубликовать Quarto документы в самых различных местах, включая популярные издательские сервисы:

Сервис	Описание
Netlify	Используйте Netlify, если вам нужна поддержка пользовательских доменов, аутентификации, предварительного просмотра ветвей и других более продвинутых возможностей.
GitHub Pages	Публикуйте контент на основе исходного кода, управляемого в репозитории GitHub. Используйте страницы GitHub, когда исходный код вашего документа или сайта размещен на GitHub.
Quarto Pub	Служба публикации документов, веб-сайтов и книг Quarto. Используйте Quarto Pub, если вам нужен бесплатный, простой в использовании сервис для общедоступного контента.
другие сервисы	Контент, отображаемый с помощью Quarto, использует стандартные форматы (HTML, Pdf, MS Word и т.д.), которые могут быть опубликованы где угодно. Используйте это, если один из описанных выше методов не соответствует вашим требованиям.

4️⃣ Параметризированные отчеты в Quarto

Зачем нужны параметризованные отчеты

File with the word '.qmd' inside and the word 'Function' above.

An arrow points from 'Input' with 'params$year' to the previous image with 'Function' and '.qmd' file.

In addition to the previous two images, arrows point to five reports with years 2019 through 2023 on them in a flow chart.

Описание параметров в YAML-заголовке

---
title: "Отчет"         # Metadata
format:                # Установка формата вывода
  html:                                     
  docx:                            
params:                # Значения параметров по умолчанию
  person: Иванов И.И.
  year: 2023                                
---

Доступ к значениям параметров

Для доступа к значениям параметров в чанках или в разметке нужно использовать переменную params.

params будет представлять собой список.

str(params)

List of 2
 $ person: chr "Иванов И.И."
 $ year  : num 2023

Доступ к значениям с помощью $.

params$person

[1] "Иванов И.И."

Для инлайн использования в тексте можно также образаться через `r `.

Результаты, полученные для `r params$person`.

Результаты, полученные для Иванов И.И..

Рендер с `quarto::quarto_render()`

quarto::quarto_render(
  input = "template.qmd",         # Файл шаблона
  output_format = "html",         # Выходной формат
  output_file = "Report.html",    # Имя выходного файла
  execute_params = list(          # Список передаваемых параметров
    person = "Иванов И.И.",
    year = 2022
  )

Рендер сразу нескольких отчетов

Для упрощения процедура можно собрать data.frame с названиями результирующих файлов и передаваемыми параметрами со следюущими столбцами:

output_file: filename.ext
execute_params: именованный список параметров

Затем запустить пакетную обработку.

reports %>% 
  purrr::pwalk(
    quarto::quarto_render,
    input = "template.qmd",
    output_format = "html"  
    )

Оптимизация отчетов

При пакетном рендеринге отчетов рекомендуется сделать так, чтобы html файл сразу в себе включал все необходимые ресурсы.

# Include in YAML
---
format: 
  html:
    embed-resources: true
---

Чтобы файл не разрастался, его можно разбить на смысловые блоки и включать их в основной документ с помощью {{< include part1.qmd >}}.

Выборочный рендеринг в зависимости от формата

Можно включать и отключать различные блоки в зависимости от выводимого формата

:::: {.content-visible when-format="html"}
::: panel-tabset

Содержимое вкладки которое будет показываться только в HTML

:::
::::

:::: {.content-visible unless-format="html"}

Содержимое которое не будет показываться в HTML

::::

5️⃣ Рефлексия

🤌 Что мы узнали на лекции

Научились сохранять таблицы в формате Excel с оформлением с помощью пакета openxlsx
Узнали про формат Markdown и как он помогает оформлять текст
Сформировали о опубликовали первый отчет с помощью издательской системы quarto

6️⃣ Полезные материалы

Шпаргалка по Quarto

Что можно почитать

🔗 Ссылки

🖥️ Презентация
https://vk.cc/cRpq6w

👩‍💻 Код проекта
https://vk.cc/cRpq75

💬 Группа курса в Telegram
t.me/+ZzzdU5ZvWuw4M2Ri

📧 Пишите на почту
dt.science@post.smolgmu.ru

Сохранение результатов работы

🙋‍♂️ Проверка связи

🎯 Цели занятия

1️⃣ Сохранение таблиц в Excel

Работа с Excel с пакетом openxlsx

2️⃣ Оформление таблиц

10 рекомендаций для лучших таблиц

Выделение заголовков столбцов таблицы

Использование визуальных разделителей вместо сетки

Выравнивание чисел по правому краю

Выравнивание текста по левому краю

Адекватный уровень точности

Направление внимания с помощью отступов

Направление внимания с помощью отступов

Единицы измерения

Выделение выбросов и важных значений

Группировка данных

Использование дополнительных визуализаций

Оформление таблиц с flextable

Пример оформления таблицы с flextable

Оформление таблиц с gt

Пример оформления таблицы с gt

3️⃣ Научно издательская система quarto

Что такое quarto

Статьи

Веб-страницы

Книги

Презентации

Больше примеров разработок в Quarto

Как работает quarto

Структура документа quarto

Метаданные (YAML)

Исполняемый код (R/Python/Julia/…)

Текст (Markdown/HTML)

Markdown (форматирование текста)

Markdown (заголовки)

Заголовок 1

Заголовок 2

Заголовок 3

Заголовок 4

Markdown (ссылки и рисунки)

Markdown (списки)

Markdown (таблицы)

Markdown

Вывод

Формулы в Quarto

Диаграммы Mermaid

Выносные блоки

Блоки кода

Возможности для рендеринга

Основные сервисы для веб-публикации

4️⃣ Параметризированные отчеты в Quarto

Зачем нужны параметризованные отчеты

Описание параметров в YAML-заголовке

Доступ к значениям параметров

Рендер с quarto::quarto_render()

Рендер сразу нескольких отчетов

Оптимизация отчетов

Выборочный рендеринг в зависимости от формата

5️⃣ Рефлексия

🤌 Что мы узнали на лекции

6️⃣ Полезные материалы

Шпаргалка по Quarto

Что можно почитать

🔗 Ссылки

❤️ Спасибо за внимание!

Работа с Excel с пакетом `openxlsx`

Оформление таблиц с `flextable`

Пример оформления таблицы с `flextable`

Оформление таблиц с `gt`

Пример оформления таблицы с `gt`

3️⃣ Научно издательская система `quarto`

Что такое `quarto`

Как работает `quarto`

Структура документа `quarto`

Рендер с `quarto::quarto_render()`