20.docs.qmd

---
title: "Reports"
author: "Lev Kovalenko"
format: 
    revealjs: 
        theme: dark
        self-contained: true
        echo: true
        source: true
---

## Проблемы DS отчетов{.scrollable}

:::: {.columns }
 
::: {.column width="50%" }
Отчет пишут в конце проекта:
- Описывают конечное решение
- Теряются промежуточные эксперименты
- Теряется описание мотивации к некоторым шагам 
- Теряется часть результатов
 
:::
 
::: {.column width="50%"}
Отчет пишут в процессе проекта:
- Фиксируют все шаги исследования
- Легко делиться знаниями в рабочей команде
- В любой момент можно продемонстрировать результаты
:::
::::

:::{.notes}
Сегодня мы поговорим о документации к DS проекту. Начнем с того - какие в ней есть проблемы. Точнее в процессах большинства проектов. Наверное вы знаете, что по итогам DS проектов пишутся статьи и, собственно, проблемы которые в них есть  рождаются от того, что документация пишется по итогу, а не в процессе работы над проектом.

Получается, что документация или статья описывает только конечное решение, а не путь к его получению. А для того что бы воспроизвести решение, нужно знать какой путь был проделан. Изз-аз этого проблематично воспроизвести работу по статье. Так как потеряны связующие моменты - промежуточные выводы. Например вы построили модель для классификации обращений и проинтерпретировали ее. Увидели, что наибольший вес в ней имеют мусорные токены типа приветствий и ФИО людей. Отсюда появляется мотивация для очистки обращений от таких токенов и повторное проведение моделирования. Если не описать это, то в будущем будет потеряна информация, а почему же делались те или иные шаги в решении.

Кроме этих выводов теряются какие-то промежуточные результаты экспериментов. Да и не только промежуточные. Если вовремя не описать какие-то результаты, их довольно легко потерять и не воспроизвести в конце работ над проектом. Таким образом можно потерять важные результаты, которые влияли на ваше исследование.

Эти проблемы решает ведение документации по ходу проекта. Есо записывать результаты каждого эксперимента, каждого шага исседваония, то вы их точно не потеряете. И все записи будут у вас храниться, а если все это вести внутри гита, то и версионироваться. Ранее я уже говорил что мы сделали версионирование исследований, то есть начали версионирвоать данные + код + результаты, сюда стоит добавить и версионирование документации, самих отчетов.

Кроме этого написание отчета в процессе работы позволит легко делиться знаниями внутри команды, можно без труда узнать результаты работы других членов команды, не созваниваясь с ними и не обсуждаю всю проделанную работу. Это сэклномит время на омуникации и позволит исследваотелям не держать все знания в голове. Ну и на последок из плюшек - это наличие промежуточного отчета позволит показывать промежуточные результаты заказчикам без особых затруднений. Не нужно будет готовить презентации с нуля, можно будет использовать для демонстрации ваш отчет.
:::

# Что нужно описать в отчете?

## Четкая цель

- Общее описание проблемы
- Цели и задачи проекта
- Бизнес-постановка задачи
- Основные метрики и требования приемки
- Вид результата

:::{.notes}
Одним из самых разочаровывающих и расточительных усилий является разработка чего-то, что на самом деле никому не нужно. И тем не менее, все мы иногда становимся жертвами этого (по крайней мере, я знаю, что бывал).

Чтобы снизить этот риск, начинать любой проект стоит с четкой цели. Описать, а какую проблему вы все таки решаете, какая цель у проекта и какие задачи для достижения это цели нужно решить. Задокументируйте бизнес-цели заказчика. Определите, как ваш проект по науке о данных удовлетворит его потребности. И какие требования к нему будут выдвигаться. Так же стоит зафиксировать что будет являться результатом проекта в каком виде он будет.

На своем опыте могу сказать, что стоит документировать то, что вы не собираетесь делать (выходящее за рамки вашего проекта).
:::

## Данные

- Источники данных
- Описание данных
- Препроцессинг
- Анализ данных

:::{.notes}
Что стоит описывать про данные?

Источники данных - Описание источников, откуда были взяты данные. Каким образом планируется забирать данные из этих источников.
- Какие данные используются для модели?
- Почему были выбраны именно эти данные (и исключены другие наборы данных)?
- Как были получены данные?
- Где находятся данные?
- Как часто обновляются данные?

Описание данных - Какие данные будут использоваться на проекте, в каком они формате, какая у них структура.
- Как выглядят данные? (среднее значение, медиана, мода, асимметрия, ожидаемый объем данных и т. д.)
- Какие известные проблемы в данных?

Препроцессинг - Какие шаги были сделаны по предобработке данных, приведения их к нормальному виду.
- Как вы изменяли данные (преобразования, импутации, применялись другие методы очистки данных и т. д.)

Анализ данных - Результаты проведения EDA. Данный раздел может содержать скриншоты из Jupyter с комментариями и выводами.
- Какие есть закономерности в данных?

Документирование данных поможет во многих отношениях. Основная цель документации - помочь исследователям, которые захотят работать с теми же данными или данными из того же источника. Подробное описание некоторых моментов сильно облегчит жизнь последующим исследователям, а так же позволит распространить эту информацию в вашей команде.
:::

## Эксперименты

- Проверяемая гипотеза
- Используемые признаки, целевую переменную
- Препроцессинг признаков
- Постановка эксперимента
- Выводы

:::{.notes}
Переходим к тому, что близко сердцу каждого специалиста по данным, — к научному методу. Этот основной процесс проходит через цикл выдвижения гипотезы, проведения эксперимента и измерения результатов. Большинство проектов по науке о данных также проходят эти этапы — часто повторяя их несколько раз. В процессе проведения эксперимента опишите:

1) Какую гипотезу вы проверяете?
    - Какую гипотезу вы проверяете?
    - Для чего в целом вы проводите данное исследование?
    - Какой результат вы ожидаете?
2) Данные для исследования:
    - Какой датасет вы использовали в исследовании?
    - Пример данных, которые вы взяли для исследования?
    - Какие манипуляции вы делали над данными?
    - Пример данных, которые вы получили?
    - Как количественно и качественно изменился датасет?
3) Постановка эксперимента:
    - Какие инструменты вы используете?
    - Почему именно они?
    - Есть ли какая-то специфика эксперимента? Расскажите о ней.
4) Полученные результаты:
    - Что вы получили в результате эксперимента?
    - Покажите таблицы, графики, метрики моделей и прочее.
5) Выводы:
    - Как вы интерпретируете свои результаты?
    - Что важного можно из них вынести?
    - Какие следующие шаги вы видите?

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

## Общие выводы

- Выводы по результатам экспериментов
- Извлеченные уроки
- Результаты эксплуатации

:::{.notes}
Под конец проектной работы стоит указать какие этапы исследования были проведены, какие были результаты проверки гипотез. Описание трудностей, с которыми столкнулись исследователи в процессе выполнения проекта. Ну и описание результатов опытной эксплуатации модели, удалось ли заказчику достигнуть поставленных целей.
:::

# Инструменты

## Markdown

:::: {.columns }
 
::: {.column width="50%" }
**Pros**
 
- Простой синтаксис
- Поддерживает картинки, html, математические формулы
- Легко генерирует html или pdf
- Рендерится в gitlab/github
- Можно настроить локальные ссылки
 
:::
 
::: {.column width="50%"}
**Cons**
 
- Нет возможности включать произвольный контент-файл
- Нет способа сборки в единый отчет
 
:::
::::

## Latex

:::: {.columns }
 
::: {.column width="50%" }
**Pros**
 
- Поддерживает произвольные контент-файлы
- Есть система сборки в единый отчет
- Хорошая поддержка модульности
- Легко генерирует pdf
- Умеет создавать презентации
 
:::
 
::: {.column width="50%"}
**Cons**
 
- Не рендерится в gitlab/github
- Сложный синтаксис
- Требует настройки
- Сложные шаблоны и файлы стилей
- Платформозависим
 
:::
::::

## Sphinx

:::: {.columns }
 
::: {.column width="50%" }
**Pros**
 
- Поддерживает произвольные контент-файлы
- Есть система сборки в единый отчет
- Поддерживает разные синтаксисы (markdown, rst)
- Легко генерирует html или pdf
- Простые шаблоны и стили на css
 
:::
 
::: {.column width="50%"}
**Cons**
 
- Требует настройки
- Очень щепетилен к путям
 
:::
::::

## Quarto markdown

:::: {.columns }
 
::: {.column width="50%" }
**Pros**
 
- Поддерживает картинки, html, математические формулы
- Есть система сборки в единый отчет
- Легко генерирует html или pdf
- Умеет запускать код
- Умеет создавать презентации
 
:::
 
::: {.column width="50%"}
**Cons**
 
- Требует настройки
- Нет возможности включать произвольный контент-файл
 
:::
::::