|
|
|
|
@@ -30,7 +30,7 @@
|
|
|
|
|
|
|
|
|
|
## Установка
|
|
|
|
|
|
|
|
|
|
Для EDA необходимы общие зависимости, см. **Общие зависимости** в `README.md`.
|
|
|
|
|
Для EDA необходимы общие зависимости, см. [Общие зависимости](../README.md#общие-зависимости) в `README.md`.
|
|
|
|
|
|
|
|
|
|
Для EDA используется среда [Jupyter](https://jupyter.org/). Т.к. блокноты хранятся в текстовом формате под контролем версий, нужно также дополнение [Jupytext](https://jupytext.readthedocs.io/en/latest/) (как минимум для ручной конвертации блокнотов; см. ниже).
|
|
|
|
|
|
|
|
|
|
@@ -38,31 +38,25 @@
|
|
|
|
|
|
|
|
|
|
### Общий порядок
|
|
|
|
|
|
|
|
|
|
**Внимание**: Оптимальный порядок установки и конфигурации Jupyter для работы с проектом неоднозначен. См. обоснование выбранного здесь порядка работы с блокнотами Jupyter и возможные альтернативные варианты в `eda/docs/jupyter_workflow_motivation.md`.
|
|
|
|
|
**Внимание**: Оптимальный порядок установки и конфигурации Jupyter для работы с проектом неоднозначен. См. обоснование выбранного здесь порядка работы с блокнотами Jupyter и возможные альтернативные варианты в статье [Использование Jupyter с виртуальными окружениями Python](https://asrelo.hashnode.dev/using-jupyter-with-python-virtual-environments-ru).
|
|
|
|
|
|
|
|
|
|
1. Выполните установку общих зависимостей, если это ещё не выполнено, см. **Общие зависимости** в `README.md`.
|
|
|
|
|
|
|
|
|
|
2. Jupyter и дополнения должны быть установлены в систему, а НЕ в виртуальное окружение. При необходимости деактивируйте виртуальное окружение.
|
|
|
|
|
2. Jupyter и дополнения должны быть установлены в систему, а **не** в виртуальное окружение. При необходимости деактивируйте виртуальное окружение.
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
deactivate
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
3. [Установите Jupyter](https://jupyter.org/install) и Jupytext в систему (НЕ в виртуальное окружение).
|
|
|
|
|
3. [Установите Jupyter](https://jupyter.org/install) и Jupytext в систему (**не** в виртуальное окружение).
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
pip install -U notebook
|
|
|
|
|
pip install -U notebook jupytext
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
4. Установите Jupytext в систему (НЕ в виртуальное окружение).
|
|
|
|
|
Полная инструкция по установке Jupytext: [Installation — Jupytext documentation](https://jupytext.readthedocs.io/en/latest/install.html).
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
pip install -U jupytext
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Полная инструкция по установке: [Installation — Jupytext documentation](https://jupytext.readthedocs.io/en/latest/install.html).
|
|
|
|
|
|
|
|
|
|
5. **Опционально**, установите papermill в систему (НЕ в виртуальное окружение).
|
|
|
|
|
4. **Опционально**, установите papermill в систему (**не** в виртуальное окружение).
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
pip install -U papermill
|
|
|
|
|
@@ -70,55 +64,69 @@
|
|
|
|
|
|
|
|
|
|
Полная инструкция по установке: [Installation - papermill 2.4.0 documentation](https://papermill.readthedocs.io/en/stable/installation.html).
|
|
|
|
|
|
|
|
|
|
**Шаги 6–7** **необходимо** выполнить **только** если Вы желаете использовать что-то кроме расширения Jupyter для Visual Studio Code для работы с блокнотами **или собираетесь** коммитить писать блокноты под контроль версий.
|
|
|
|
|
5. Активируйте **виртуальное окружение** повторно.
|
|
|
|
|
|
|
|
|
|
6. Активируйте виртуальное окружение вновь.
|
|
|
|
|
|
|
|
|
|
7. Установите ядро Jupyter, связанное с данным виртуальным окружением, в систему. Используйте следующее имя для ядра: `mpei-iis-99040779`. (*Да, это странно, но это признано лучшим подходом на данный момент; см. обоснование в `docs/dev/jupyter_workflow_motivation.md`.*)
|
|
|
|
|
6. Установите ядро Jupyter, связанное с данным виртуальным окружением, в директорию этого виртуального окружения. Укажите следующее имя ядра: `python3_venv`.
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
ipython kernel install --user --name=mpei-iis-99040779
|
|
|
|
|
python -m ipykernel --sys-prefix --name python3_venv
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
(Эта команда устанавливает виртуальное окружение глобально для текущего пользователя; для установки глобально в систему, уберите флаг `--user`).
|
|
|
|
|
7. **Опционально**, **заранее** сохраните в переменную окружения `JUPYTER_PATH` путь к данным Jupyter в виртуальном окружении `<path>` — см. п. 1 в инструкции по использованию.
|
|
|
|
|
|
|
|
|
|
**Внимание**: На данном этапе могут отсутствовать пригодные для прямого редактирования блокноты `.ipynb` (например, если проект развёртывается с нуля). Об использовании спаренных блокнотов и конвертации форматов см. **Использование Jupytext**.
|
|
|
|
|
* Windows (PowerShell):
|
|
|
|
|
|
|
|
|
|
#### Удаление ядра из системы
|
|
|
|
|
```ps
|
|
|
|
|
[System.Environment]::SetEnvironmentVariable('JUPYTER_PATH', "<path>;$env:JUPYTER_PATH", 'User')
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Во избежание захламления системы ядро можно удалить из системы **позднее**, вызвав глобально установленный Jupyter (НЕ в виртуальном окружении) и передав имя ядра.
|
|
|
|
|
* Windows (cmd):
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
jupyter kernelspec uninstall mpei-iis-99040779
|
|
|
|
|
```
|
|
|
|
|
```bat
|
|
|
|
|
setx JUPYTER_PATH "<path>;%PATH%;JUPYTER_PATH"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Примечание**: Установленное ядро НЕ занимает значительные ресурсы хранилища. На самом деле в систему устанавливается крайне лёгкая *спецификация ядра*, ограниченная коротким текстовым файлом и иконками.
|
|
|
|
|
* UNIX (sh):
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
echo 'export JUPYTER_PATH="<path>:$JUPYTER_PATH"' >> ~/.profile
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Внимание**: На данном этапе могут отсутствовать пригодные для прямого использования блокноты `.ipynb` (например, если проект развёртывается с нуля). Об использовании спаренных блокнотов и конвертации форматов см. [Использование Jupytext](#использование-jupytext).
|
|
|
|
|
|
|
|
|
|
### Зависимости
|
|
|
|
|
|
|
|
|
|
Используемые непосредственно кодом проекта зависимости для разведочного анализа данных (EDA) (директория `eda/`) — пакеты Python — на данный момент включены в общие зависимости (см. выше).
|
|
|
|
|
|
|
|
|
|
### Использование 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 в виртуальном окружении.
|
|
|
|
|
|
|
|
|
|
## Работа с блокнотами Jupyter
|
|
|
|
|
|
|
|
|
|
### Jupyter
|
|
|
|
|
|
|
|
|
|
1. Запустите глобальный глобально установленный сервер Jupyter и приложение (НЕ из виртуального окружения).
|
|
|
|
|
1. **Если** при выполнении инструкции по установке Вы **не** сохранили в переменную окружения JUPYTER_PATH путь к данным Jupyter в виртуальном окружении, этот путь нужно добавить в переменную окружения сейчас.
|
|
|
|
|
|
|
|
|
|
* Например, запустите сервер Jupyter и веб-приложение Notebook в браузере:
|
|
|
|
|
Добавьте в переменную окружения `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
|
|
|
|
|
@@ -134,21 +142,34 @@ Jupytext довольно удобно работает в оригинальн
|
|
|
|
|
|
|
|
|
|
2. Используйте приложение для навигации по файловой системе (в частности, по каталогу `eda/`), редактирования и исполнения кода в блокнотах.
|
|
|
|
|
|
|
|
|
|
3. Если приложение Jupyter запрашивает **выбор ядра** Jupyter (**kernel**) или Вы сталкиваетесь с необъяснимыми **ошибками импортов**, выберите для текущего блокнота ядро с именем `mpei-iis-99040779` (которое Вы установили в систему раньше).
|
|
|
|
|
3. Если приложение Jupyter запрашивает **выбор ядра** Jupyter (**kernel**) или Вы сталкиваетесь с необъяснимыми **ошибками импортов**, выберите для текущего блокнота ядро с именем `python3_venv`.
|
|
|
|
|
|
|
|
|
|
* **Notebook**: Может понадобиться выбор вручную; кнопка для выбора ядра для открытого блокнота находится в верхнем правом углу веб-страницы.
|
|
|
|
|
* **Jupyter Notebook**: Может понадобиться выбор вручную; кнопка для выбора ядра для открытого блокнота находится в верхнем правом углу веб-страницы.
|
|
|
|
|
|
|
|
|
|
### Расширение Jupyter для Visual Studio Code
|
|
|
|
|
|
|
|
|
|
1. Запустите Visual Studio Code.
|
|
|
|
|
|
|
|
|
|
2. **Если** Вы НЕ установили ядро Jupyter, связанное с виртуальным окружением для проекта, в систему, обязательно откройте корневую директорию проекта в VS Code (*File* -> *Open Folder...*). **Иначе** это необязательный, но удобный шаг.
|
|
|
|
|
2. Откройте корневую директорию проекта в VS Code (*File* -> *Open Folder...*).
|
|
|
|
|
|
|
|
|
|
3. Если Вы открыли директорию проекта и VS Code запрашивает выбор автоматически обнаруженного виртуального окружения, согласитесь.
|
|
|
|
|
|
|
|
|
|
4. **При открытии любого блокнота** убедитесь, что выбрано корректное ядро Jupyter. (Кнопка для выбора ядра для открытого блокнота находится в верхнем правом углу области содержимого вкладки; если ядро не выборано, на кнопке написано *Select Kernel*.)
|
|
|
|
|
3. **Если** VS Code запрашивает выбор автоматически обнаруженного виртуального окружения, согласитесь.
|
|
|
|
|
|
|
|
|
|
* **Если** Вы установили ядро Jupyter в систему, рекомендуется выбрать установленное в систему ядро с именем `mpei-iis-99040779`.
|
|
|
|
|
* **Если** Вы совсем **не собираетесь** использовать Jupyter для работы с проектом **и не собираетесь** записывать блокноты под контроль версий, можно выбрать локальное ядро, связанное с виртуальным окружением (по умолчанию имеет название виртуального окружения — `.venv`).
|
|
|
|
|
**Иначе** [укажите](https://code.visualstudio.com/docs/python/environments#_working-with-python-interpreters) своё виртуальное окружение самостоятельно.
|
|
|
|
|
|
|
|
|
|
5. Используйте IDE с расширением для навигации по файловой системе (в частности, по каталогу `eda/`), редактирования и исполнения кода в блокнотах.
|
|
|
|
|
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 в виртуальном окружении.
|
|
|
|
|
|
