Metadata-Version: 2.1
Name: RealEstate-package
Version: 1.5.0
Summary: МЛ-модель, предсказывающая стоимость недвижимости по её параметрам.
Home-page: https://github.com/Lada-Rom/RealEstate_package
Author: Клейменов А., Толстенко Л.
Author-email: notmy@gmail.com
License: BSD-3
Project-URL: Documentation, https://github.com/Lada-Rom/RealEstate_package
Keywords: lightgbm python real_estate price
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.8
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: anyio (==3.6.2)
Requires-Dist: click (==8.1.3)
Requires-Dist: fastapi (==0.95.2)
Requires-Dist: h11 (==0.14.0)
Requires-Dist: idna (==3.4)
Requires-Dist: joblib (==1.2.0)
Requires-Dist: lightgbm (==3.3.5)
Requires-Dist: numpy (==1.24.3)
Requires-Dist: pandas (==2.0.1)
Requires-Dist: pydantic (==1.10.7)
Requires-Dist: python-dateutil (==2.8.2)
Requires-Dist: pytz (==2023.3)
Requires-Dist: scikit-learn (==1.2.2)
Requires-Dist: scipy (==1.10.1)
Requires-Dist: six (==1.16.0)
Requires-Dist: sniffio (==1.3.0)
Requires-Dist: starlette (==0.27.0)
Requires-Dist: strictyaml (==1.7.3)
Requires-Dist: threadpoolctl (==3.1.0)
Requires-Dist: typing-extensions (==4.5.0)
Requires-Dist: tzdata (==2023.3)
Requires-Dist: uvicorn (==0.22.0)

# Структура проекта

- `real_estate_model/` содержит весь основной код пакета: `train.py`, `predict.py`, `config.py` (загрузка параметров обучения и предсказания из файла `config.yml`). Здесь же находится директория `trained_models/`, куда при обучении будут попадать веса новых моделей, и в которой уже есть одна обученная модель.
- `requirements/` содержит все необходимые зависимости для использования (`requirements.txt`) и тестирования (`test_requirements.txt`) пакета.
- `tests/` содержит код тестов, запускаемый при помощи pytest.
- `webapp/` содержит код веб-интерфейса.

`predict.py` имеет функционал для загрузки состояния модели из конфига (`load_model`), предсказания с помощью предзагруженной модели (`predict_raw`) и предсказания моделью, автоматически загружаемой из файла, прописанном в конфиге (`predict`).

`config.py` имеет функции `fetch_config_from_yaml` для полного считывания параметров конфига и `set_config_field` для изменения значения конкретного параметра (не поддерживает списки).


# Установка

Пакет опубликован на [PyPI](https://pypi.org/project/RealEstate-package/) и устанавливается командой:

```
pip install RealEstate-package
```


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

Код запускается и тестируется при помощи tox. Параметры обучения и предсказания находятся в `real_estate_model/config.yml`.


## Обучение

Перед началом обучения:

- НЕОБХОДИМО скачать [датасет](https://www.kaggle.com/datasets/mrdaniilak/russia-real-estate-20182021) и прописать абсолютный путь к csv-файлу в конфиге в поле `dataset` (можно сделать это программно с помощью функции `config.set_config_field`);
- ОПЦИОНАЛЬНО настроить другие параметры обучения:
    + `trained_model_path`: относительный путь сохранения обученных моделей, по умолчанию `./trained_models/` (имя генерируется с помощью timestamp);
    + `variables_to_drop`: список переменных, не учитываемых при обучении (проект рассчитан на предсказание стоимости недвижимости, поэтому она игнорируется автоматически);
    + `random_state`;
    + `test_size`: доля тестовой выборки для функции `train_test_split`;
    + `num_boost_round`: внутренний параметр модели, отвечающий за количество раундов (итераций);
    + `early_stopping_rounds`: внутренний параметр модели, отвечающий за раннюю остановку обучения, если качество не улучшалось в течение указанного количества раундов;
    + `verbose_eval`: внутренний параметр модели, отвечающий за частоту вывода информации об обучении (в количестве раундов);
    + `metric`: внутренний параметр модели функции оценки качества, по умолчанию `rmse`, прочие метрики доступны по [ссылке](https://lightgbm.readthedocs.io/en/latest/Parameters.html#metric).

Обучение запускается из корневой директории проекта командой:

```
tox -e train
```


## Предсказание

Для предсказания в конфиге указывается путь к весам обученной модели (по умолчанию `trained_models/lgb_model.txt`) в поле `predict_model` и список переменных, на которых она обучалась (`predictors`).

```
tox -e predict
```


# Веб-приложение

Основной функционал доступен в веб-приложении, которое запускается командой:

```
tox -e webapp
```

Предоставляется возможность:
- предсказать значение стоимости недвижимости по некоторым параметрам во вкладке `/predict`;
- обучить новую модель во вкладке `/train` (параметры обучения будут взяты из конфига). По окончании обучения будет выведена информация об абсолютном и относительном путях сохранённой модели и о её качестве на train- и test-выборках (R2-score).
- изменить модель для предсказания в `/change_model`, передав относительный путь к файлу с весами на вход.


# Датасет

Для обучения существующей модели использовался датасет:
https://www.kaggle.com/datasets/mrdaniilak/russia-real-estate-20182021


