iis-project/eda/README.md

# Разведочный анализ данных (EDA)

## Блокноты Jupyter

* `cars_eda` — Очистка и первичный анализ данных о подержанных автомобилях.

  Использует CSV-файл сырых данных из [датасета](https://www.kaggle.com/datasets/vijayaadithyanvg/car-price-predictionused-cars/data). Каноническое расположение файла данных: `data/cars.csv`.

  Создаёт файлы очищенных данных (по умолчанию &mdash; CSV) и аугментированных данных (по умолчанию &mdash; pickle). Канонические расположения: соответственно `data/cars.clean.<ext>` и `data/cars.aug.<ext>`, с заменой `<ext>` на расширение в зависимости от формата: `csv` для CSV, `pickle` для pickle.

  **Выводы по исследованию**:

  * Выполнена очистка датасета: удалены несколько аномальных объектов, переименованы некоторые ошибочно названные признаки. (Пропущенных значений в датасете нет.)

  * Датасет дополнен (аугментирован) потенциально полезными синтетическими признаками: отношение цены с пробегом к изначальной цене, возраст (предполагаемый на основе года выпуска автомобиля и распределения этих годов выпуска в датасете), логарифмы количественных величин. Аугментированная версия сохраняется отдельно.

  * Предварительно подтверждена возможность определения рыночной цены автомобиля с пробегом по использованным признакам, **в особенности** по следующим: исходная цена, возраст и пробег автомобиля, тип продающего лица (дилер или частное лицо), топливо (автомобили на дизельном топливе редко бывают дешёвыми).

    * Цена продажи с пробегом сильно линейно коррелирует с изначальной ценой.

    * Интересно, что возраст автомобиля является заметно лучшим предиктором снижения стоимости, чем пробег, при этом корреляция между возрастом и пробегом существенная, но не определяющая.

    * Существует огромная разница в ценах у дилеров и частных лиц (у частных лиц дешевле в разы).

    * Существует слабая, но заметная прямая корреляция между изначальной ценой автомобиля и пробегом к дате последующей продажи.

    * Датасет не очень однороден (у него есть "тяжёлый центр"), и с малым количеством объектов это может создать проблемы с устойчивостью предсказания цен. Рекомендуется применение робастных методов ограниченной сложности; однако прямая линейная регрессия для предсказания цены проодажи может всё-таки оказаться не лучшим методом.

  Графические артефакты исследования сохранены в директории `./cars_eda_figures/`.

## Установка

Для EDA необходимы общие зависимости, см. [Общие зависимости](../README.md#общие-зависимости) в `README.md`.

Для EDA используется среда [Jupyter](https://jupyter.org/). Т.к. блокноты хранятся в текстовом формате под контролем версий, нужно также дополнение [Jupytext](https://jupytext.readthedocs.io/en/latest/) (как минимум для ручной конвертации блокнотов; см. ниже).

Опционально можно использовать дополнение [papermill](https://papermill.readthedocs.io/en/latest/) для простого параметризованного исполнения блокнотов.

### Общий порядок

**Внимание**: Оптимальный порядок установки и конфигурации Jupyter для работы с проектом неоднозначен. См. обоснование выбранного здесь порядка работы с блокнотами Jupyter и возможные альтернативные варианты в статье [Использование Jupyter с виртуальными окружениями Python](https://asrelo.hashnode.dev/using-jupyter-with-python-virtual-environments-ru).

1. Выполните установку общих зависимостей, если это ещё не выполнено, см. **Общие зависимости** в `README.md`.

2. Jupyter и дополнения должны быть установлены в систему, а **не** в виртуальное окружение. При необходимости деактивируйте виртуальное окружение.

   ```sh
   deactivate
   ```

3. [Установите Jupyter](https://jupyter.org/install) и Jupytext в систему (**не** в виртуальное окружение).

   ```sh
   pip install -U notebook jupytext
   ```

   Полная инструкция по установке Jupytext: [Installation &#8212; Jupytext  documentation](https://jupytext.readthedocs.io/en/latest/install.html).

4. **Опционально**, установите papermill в систему (**не** в виртуальное окружение).

   ```sh
   pip install -U papermill
   ```

   Полная инструкция по установке: [Installation - papermill 2.4.0 documentation](https://papermill.readthedocs.io/en/stable/installation.html).

5. Активируйте **виртуальное окружение** повторно.

6. Установите ядро Jupyter, связанное с данным виртуальным окружением, в директорию этого виртуального окружения. Укажите следующее имя ядра: `python3_venv`.

   ```sh
   python -m ipykernel --sys-prefix --name python3_venv
   ```

7. **Опционально**, **заранее** сохраните в переменную окружения `JUPYTER_PATH` путь к данным Jupyter в виртуальном окружении `<path>` &mdash; см. п. 1 в инструкции по использованию.

   * Windows (PowerShell):

     ```ps
     [System.Environment]::SetEnvironmentVariable('JUPYTER_PATH', "<path>;$env:JUPYTER_PATH", 'User')
     ```

   * Windows (cmd):

     ```bat
     setx JUPYTER_PATH "<path>;%PATH%;JUPYTER_PATH"
     ```

   * UNIX (sh):

     ```sh
     echo 'export JUPYTER_PATH="<path>:$JUPYTER_PATH"' >> ~/.profile
     ```

**Внимание**: На данном этапе могут отсутствовать пригодные для прямого использования блокноты `.ipynb` (например, если проект развёртывается с нуля). Об использовании спаренных блокнотов и конвертации форматов см. [Использование Jupytext](#использование-jupytext).

### Зависимости

Используемые непосредственно кодом проекта зависимости для разведочного анализа данных (EDA) (директория `eda/`) &mdash; пакеты Python &mdash; на данный момент включены в общие зависимости (см. выше).

## Работа с блокнотами Jupyter

### Jupyter

1. **Если** при выполнении инструкции по установке Вы **не** сохранили в переменную окружения JUPYTER_PATH путь к данным Jupyter в виртуальном окружении, этот путь нужно добавить в переменную окружения сейчас.

   Добавьте в переменную окружения `JUPYTER_PATH` абсолютный путь (далее обозначаемый `<path>`) `$VIRTUAL_ENV/share/jupyter`, где следует заменить `$VIRTUAL_ENV` на путь к директории, где развёрнуто виртуальное окружение. Для инструментов [`venv`](https://docs.python.org/3/library/venv.html), [`virtualenv`](https://virtualenv.pypa.io/en/stable/) можно просто в активном виртуальном окружении использовать подстановку переменной окружения `VIRTUAL_ENV` (активное виртуальное окружение не повлияет на дальнейшие шаги).

   * Windows (PowerShell):

     ```ps
     $env:JUPYTER_PATH = "<path>;$env:JUPYTER_PATH"
     ```

   * Windows (cmd):

     ```bat
     set "JUPYTER_PATH=<path>;%JUPYTER_PATH%"
     ```

   * UNIX (sh):

     ```sh
     export JUPYTER_PATH="<path>:$JUPYTER_PATH"
     ```

2. Запустите глобальный установленное приложение Jupyter (**не** из виртуального окружения).

   * Например, запустите Jupyter Notebook:

     ```sh
     jupyter notebook
     ```

     Веб-приложение Notebook должно открыться в веб-браузере автоматически. Если этого не произошло, найдите в сообщениях сервера Jupyter строку примерно следующего содержания:

         [I 08:58:24.417 NotebookApp] The Jupyter Notebook is running at: http://localhost:8888/

     Откройте веб-браузер и перейдите по ссылке, выведенной в конце указанного сообщения.

   См. также [документацию Jupyter](https://docs.jupyter.org/en/stable/running.html).

2. Используйте приложение для навигации по файловой системе (в частности, по каталогу `eda/`), редактирования и исполнения кода в блокнотах.

3. Если приложение Jupyter запрашивает **выбор ядра** Jupyter (**kernel**) или Вы сталкиваетесь с необъяснимыми **ошибками импортов**, выберите для текущего блокнота ядро с именем `python3_venv`.

   * **Jupyter Notebook**: Может понадобиться выбор вручную; кнопка для выбора ядра для открытого блокнота находится в верхнем правом углу веб-страницы.

### Расширение Jupyter для Visual Studio Code

1. Запустите Visual Studio Code.

2. Откройте корневую директорию проекта в VS Code (*File* -> *Open Folder...*).

3. Если Вы открыли директорию проекта и VS Code запрашивает выбор автоматически обнаруженного виртуального окружения, согласитесь.

3. **Если** VS Code запрашивает выбор автоматически обнаруженного виртуального окружения, согласитесь.

   **Иначе** [укажите](https://code.visualstudio.com/docs/python/environments#_working-with-python-interpreters) своё виртуальное окружение самостоятельно.

4. Используйте VS Code с расширением Jupyter для навигации по файловой системе (в частности, по каталогу `eda/`), редактирования и исполнения кода в блокнотах. **Не забывайте** при открытии любого блокнота проверять, что выбрано корректное ядро Jupyter (принадлежащее корректному виртуальному окружению). (Кнопка для выбора ядра для открытого блокнота находится в верхнем правом углу области содержимого вкладки; по умолчанию Вы увидите название выбранного виртуального окружения; если ядро не выбрано, на кнопке написано *Select Kernel*.)

### Использование Jupytext

Описанные ниже команды `jupytext` используют глобальной установленный экземпляр Jupytext (однако его можно запускать и изнутри виртуального окружения).

Для автоматической синхронизации связанных блокнотов (включая создание блокнотов отсутствующих, но ожидаемых форматов):

```sh
jupytext --sync eda/cars_eda.py
```

Jupytext довольно удобно работает в оригинальной среде Jupyter, синхронизируя изменения связанных файлов на лету при работе в Jupyter, **ориентируясь на метки времени на файлах**. См. документацию [Jupytext](https://jupytext.readthedocs.io/en/latest/index.html).

**Внимание**: С расширением Jupyter для Visual Studio Code Jupytext **не работает напрямую**. Для использования блокнотов `.ipynb` с расширением Jupyter для VS Code нужно синхронизировать текстовый файл под контролем версий и файл `.ipynb` вручную указанными выше командами. Однако заметьте, что это же расширение может исполнять блокнот в текстовом формате самостоятельно, посредством автоматизированного ведения временного блокнота; и оно даже автоматически создаёт/подхватывает локальное ядро Jupyter в виртуальном окружении.