Исследование датасета 2015 Street Tree Census - Tree Data (https://data.cityofnewyork.us/Environment/2015-Street-Tree-Census-Tree-Data/uvpi-gqnh/about_data) и визуализация геоданных.
Проект для домашнего задания курса MLOps и production в DS исследованиях 3.0.
Important
Разработка проекта ведётся по методологии GitHub-flow. Подробенее в CONTRIBUTING.md.
Warning
Проект и документация в стадии разработки.
Датасет содержит информацию о деревьях, растущих на улицах Нью-Йорка, собранную в рамках проекта 2015 Street Tree Census волонтёрами и сотрудниками NYC Parks & Recreation и партнёрских организаций.
Собранные данные включают в себя информацию о видах деревьев, диаметре ствола и оценку здоровья растения. Доступны сопроводительные данные, показывающие статус сбора и публикации данных по всему городу.
Подробнее о датасете можно узнать на его сайте.
Цель - выполнить исследовательский анализ данных и отработать следующие приёмы:
- визуализация сложных данных,
- сборка Docker-образов,
- работа с CI/CD конвейерами,
- работа с документацией - сборка и публикаций с
quarto
и GitHub Pages, - сборка и публикация артефактов исследования.
Исследовательский анализ данных содержит следующие пункты:
- превью данных - таблица с небольшой выборкой из датасета,
- оценка количества пропусков в столбцах с помощью библиотеки
missingno
, - диаграмма попарного распределения признаков,
- матрица попарной корреляции между вещественными признаками,
- карта расположения деревьев из датасета
и другие разделы.
Проект и среда разработки запакованы в Docker-контейнер. Для того, чтобы развернуть их на локальной машине или сервере необходимо выполнить следующие шаги:
- Установить Docker.
- Клонировать репозиторий.
- Предоставить необходимые ключи (подробнее в разделе. Ключи).
- Собрать образы контейнеров и запустить их. Для сборки и запуска пользователю
предлагается использовать следующие скрипты:
- build.sh - сборка образа базов контейнера и контейнера со средой разработки.
- start.sh - запуск контейнера со средой разработки в
интерактивном режиме с использованием
/bin/bash
, - jupyter.sh - запуск контейнера со средой разработки с запущенным сервером Jupyter Notebook,
- gh_actions_runner/build_runner.sh - сборка контейнера с self-hosted runner для GitHub Actions,
- gh_actions_runner/start_runner.sh - запуск контейнера с self-hosted runner для GitHub Actions и самого ранера.
Подробнее о развёртывании и запуске в CONTRIBUTING.md и разделах Среда разработки, CI/CD конвейер GihHub Actions.
Применяемые в проекте инструменты автоматизации описаны в разделе Инструменты автоматизации.
Для полноценной работы с проектом необходимо предоставить следующие ключи:
/.dev_env_pat
- файл с PAT для доступа к репозиторию из среды разработки в контейнере./.runner_secret_token
- Временный токен для работы self-hosted runner с GitHub Actions (подробнее).
Документация и отчёты разделены на несколько разделов, размещённых в отдельных файлах:
- Отчёты содержат подробное описание исследования и моделей и собраны в каталоге reports
- Документация, содержащая описание данных и техническую информацию, собрана в
каталоге docs:
- Описание исходных данных
- Среда разработки - Сборка и запуск среды разработки.
- CI/CD конвейер GihHub Actions - Сборка, запуск и регистрация self-hosted runner для GitHub Actions.
В проекте используются следующие инструменты автоматизации (CI/CD):
- Docker - основной инструмент автоматизации сборки и изоляции окружений;
- Git - система контроля версий кода;
- GitHub Actions - инструмент CI/CD;
- Poetry - менеджер пакетов Python;
- Cookiecutter - утилита для шаблонизации проектов, с помощью которой была создана структура каталогов и файлов данного репозитория;
- Pre-commit - утилита для автоматического запуска проверок при каждом коммите.
- Ruff - автоформатер и линтер для проверки выполнения требований стандартов оформления кода.
- Mypy - линтер для проверки типов.
├── src <- Каталог с python-модулями проекта.
│ ├── data <- Скрипты для загрузки и обработки данных.
│ ├── features <- Скрипты, создающие из сырых данных признаки, пригодные для передачи модели.
│ ├── logs <- Каталог с модулями для организации и настройки логирования.
│ ├── models <- Модули, реализующие работу с разными моделями. Для каждой модели свой модуль.
│ └── visualization <- Скрипты для генерации графиков.
|
├── data
│ ├── external <- Данные, полученные из внешних источников, например открытых API в интернете.
│ ├── interim <- Промежуточные данные, полученные после предобработки сырых данных и данных из
| | внешних источников, а также данные, полученные после промежуточных шагов
| | обработки.
│ ├── processed <- Подготовленные данные, пригодные для отправки модели.
│ └── raw <- Сырые исходные данные, полученные из первоисточника.
|
├── docs <- Документация проекта.
│ └── figures <- Иллюстрации для документации.
|
├── .dev_env_pat <- файл с PAT для доступа к удалённому репозиторию GitHub из среды разработки в
| контейнере.
|
├── gh_actions_runner <- Каталог со скриптами и файлами для работы с self-hosted runner
| | (GitHub Actions).
│ ├── build_runner.sh <- Скрипт, собирающий образ контейнера с ранером из Dockerfile в этом же каталоге.
│ ├── Dockerfile <- Dockerfile для сборки контейнера с ранером.
│ ├── remove_runner.sh <- Скрипт аннулирует регистрацию ранера в GitHub Actions, что вызывает остановку
| | работающего ранера.
│ ├── .secret_token <- Временный токен для регистрации ранера в GitHub Actions.
│ └── start_runner.sh <- Скрипт, запускающий контейнер с ранером. После запуска контейнера Скрипт
| также регистрирует и запускает ранер.
├── .github
│ └── workflows <- Каталог с описанием CI/CD конвейеров GitHub Actions в формате yaml.
|
├── logs <- Каталог для логов.
|
├── models <- Каталог с сохранёнными обученными моделями.
|
├── notebooks <- Каталог с тетрадками Jupyter
│ ├── exploratory <- Notebook-и с первичными исследованиями и экспериментами.
| | В них допустимо большое количество кода.
│ └── reports <- Более тщательно оформленные тетрадки, служащие основой для отчётов.
|
├── references <- Дополнительные сторонние материалы и руководства.
|
├── reports <- Каталог с отчётами. Отчёты содержат информацию об основных этапах
| исследования, разработке модели и полученных результатах. Для остальных
| разделов, например описания окружения разработки и процесса его
| развёртывания есть документация (каталог docs).
|
├── build.sh <- Скрипт, собирающий образ базового контейнера из Dockerfile и образ контейнера
| непосредственно с окружением разработки из Dockerfile_dev_env.
├── Dockerfile <- Dockerfile базового контейнера.
├── Dockerfile_dev_env <- Dockerfile контейнера со средой разработки.
├── .dockerignore <- Аналог .gitignore для Docker. Docker не будет копировать и обрабатывать всё,
| что перечислено в этом файле.
├── .env <- Файл с переменными окружения, которые могут быть импортированы в среду
| разработки.
├── .gitignore
├── jupyter.sh <- Скрипт для запуска контейнера среды разработки с запущенным сервером
| Jupyter Notebook.
├── LICENSE <- лицензия MIT.
├── poetry.lock <- Файл с зафиксированными зависимостями Poetry.
├── pyproject.toml <- Файл с описанием пакетов, устанавливаемых в виртуальное окружение, и
| параметрами линтеров и автоформатеров.
├── requirements.txt <- Файл с зафиксированными зависимостями Poetry, экспортированный в формате для
| других менеджеров пакетов.
├── README.md <- README.md верхнего уровня, отображающийся на заглавной странице репозитория.
├── CONTRIBUTING.md <- Руководство для новых участников проекта.
└── start.sh <- Скрипт для запуска контейнера среды разработки. Предоставляет доступ к
/bin/bash в контейнере.