Metadata-Version: 2.1
Name: sloyka
Version: 0.0.7
Summary: Library for city identity analysis from social media posts and comments
Author: sandrro, georgekontsevik
Requires-Python: >=3.10.6,<4.0.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: autodocsumm (==0.2.11)
Requires-Dist: bertopic (==0.15.0)
Requires-Dist: black (==23.1.0)
Requires-Dist: flair (==0.12.2)
Requires-Dist: flake8 (==6.0.0)
Requires-Dist: fuzzywuzzy (==0.18.0)
Requires-Dist: geopandas (==0.12.2)
Requires-Dist: geopy (==2.3.0)
Requires-Dist: isort (==5.12.0)
Requires-Dist: keybert (==0.8.3)
Requires-Dist: loguru (==0.7.2)
Requires-Dist: matplotlib (==3.7.0)
Requires-Dist: natasha (==1.6.0)
Requires-Dist: networkx (==3.1)
Requires-Dist: nltk (==3.8.1)
Requires-Dist: numpy (==1.25.2)
Requires-Dist: osm2geojson (==0.2.3)
Requires-Dist: osmnx (==1.5.1)
Requires-Dist: pandarallel (==1.6.5)
Requires-Dist: pandas (==1.5.3)
Requires-Dist: pyarrow (==15.0.0)
Requires-Dist: pylint (==3.0.2)
Requires-Dist: pymorphy2 (==0.9.1)
Requires-Dist: pymorphy2-dicts-ru (==2.4.417127.4579844)
Requires-Dist: pymorphy3 (==2.0.1)
Requires-Dist: scikit-learn (==1.2.1)
Requires-Dist: seaborn (==0.12.2)
Requires-Dist: shapely (==2.0.1)
Requires-Dist: spacy (==3.5.0)
Requires-Dist: sphinx (==7.1.2)
Requires-Dist: sphinx-rtd-theme (==1.3.0rc1)
Requires-Dist: torch (==2.1.1)
Requires-Dist: tqdm (==4.64.1)
Requires-Dist: transformers (==4.30.2)
Requires-Dist: vk-api (==11.9.9)
Description-Content-Type: text/markdown

# SLOYKA
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![Documentation Status](https://readthedocs.org/projects/soika/badge/?version=latest)](https://soika.readthedocs.io/en/latest/?badge=latest)
[![PythonVersion](https://img.shields.io/badge/python-3.10-blue)](https://pypi.org/project/scikit-learn/)
[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Tests](https://github.com/GeorgeKontsevik/sloyka/actions/workflows/tests.yml/badge.svg?branch=dev)](https://github.com/GeorgeKontsevik/sloyka/actions/workflows/tests.yml)

[![sloyka_community_chat](https://img.shields.io/badge/-community-blue?logo=telegram)](https://t.me/sloyka_community)
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1wCUJAqlq9GMKw1wpTsWrzYwr10pWDeHv?usp=sharing)

<img align="right" src="logo/logo.png" alt="Your Banner" width="30%">

**SLOYKA** - это библиотека, нацеленная на обогащение цифровых моделей городов данными, получаемыми из текстовых данных цифрового следа горожан, 
а также на моделирование вернакулярной оценки качества городской среды.

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

SLOYKA включает в себя две группы методов: методы для генерации пространственно-семантического графа и методы для моделирования
социальных процессов с его помощью.

Схематичное описание работы библиотеки:
<!-- ![block](https://github.com/GeorgeKontsevik/sloyka/blob/dev/images/Схема_Слойки.png) -->

<div align="center">
  <img src="images/Схема_Слойки.png" alt="scheme" width="100%">
</div>

**Модуль генерации пространственного-семантического графа**

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

Пространственный граф строится по следующему алгоритму:
1. Пользователь подает на вход набор текстов и указание на территорию;
2. Из OSM загружается сеть УДС в виде графа и именованные сущности;
3. От именованных сущностей строится евклидово расстояние до ближайшего узла графа, оно пишется в новое ребро;
4. В текстах выявляются урбанонимы (городские названия). Процесс выполняется при помощи дообученной
[модели](https://huggingface.co/Geor111y/flair-ner-addresses-extractor) RuBert и набора эвристик для геокодирования без использования сторонних сервисов
5. Сначала они геокодируются по адресной системе, потом по названиям объектов

Семантический граф строится по следующему алгоритму:
1. Пользователь подает на вход набор текстов
2. Извлекаются урбанонимы, и далее тексты группируются по ним.
3. Из текстов по каждому урбанониму извлекаются ключевые сущности: явления, акторы, действия, объекты городской среды.
4. На основе опорных узлов-урбанонимов и соответствующих ключевых сущностей формируется семантический граф.
5. Определяется семантическая близость сущностей, между наиболее близкими формируются дополнительные ребра.
<!-- 
![Semantic graph](/data/photo_2024-01-11_20-31-29.jpg) -->

**Модуль моделирования социальных процессов с помощью пространственного-семантического графа**
- В процессе разработки -

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

## Особенности SLOYKA

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

<!-- Сравнение результата геокодирования с существующим решением:
![Geocoder comparison](/images/Сравнение_эффективности_извлечения_адреса_3.png)

Выделение комьюнити на основе жалоб горожан по различным тематикам:
![Spatial graph communities](/images/photo_2023-12-25_01-44-15.jpg)

Процентное соотношение жалоб по категориям среди выделенных комьюнити:
![Spatial graph communities](/images/photo_2023-12-25_01-44-14.jpg) -->


<!-- Сравнение результата геокодирования с существующим решением:
![Geocoder comparison](/data/Сравнение_эффективности_извлечения_адреса_3.png) -->
<!-- 
## Installation

- В разработке -->

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

Последняя стабильная версия библиотеки SLOYKA находится в [master branch](https://github.com/GeorgeKontsevik/sloyka/tree/master). 

<!-- Репозиторий включает в себя следующие директории:

* Пакет [core](https://github.com/GeorgeKontsevik/sloyka/tree/master/factfinder)  содержит основные классы и скрипты. Это *ядро* SLOYKA;
* Пакет [examples](https://github.com/GeorgeKontsevik/sloyka/tree/master/examples) включает в себя несколько *how-to-use кейсов*, где вы можете разобраться в принципах работы SLOYKA;
* All *unit and integration tests* can be observed in the [test]() directory;
* The sources of the documentation are in the [docs](https://github.com/GeorgeKontsevik/sloyka/tree/master/docs)  -->
                                                        
<!-- ## Examples
Вы можете использовать свои собственные данные, но они должны соответствовать спецификации. Следующие примеры помогут освоиться с библиотекой:

1. [Geocoder](examples/geocoder_example.ipynb) - как извлечь топонимы и получить их координаты -->

<!-- ## Документация

- В разработке

## Разработка

Чтобы начать разработку библиотеки, необходимо выполнить следующие действия:

1. Клонировать репозиторий (`git clone https://github.com/GeorgeKontsevik/sloyka.git`);
2. Создайте виртуальную среду, так как для библиотеки требуются точные версии пакетов, и активировать ее: `python -m venv venv`;
3. Установить библиотеку в редактируемом режиме: `python -m pip install -e '.[dev]' --config-settings editable_mode=strict`;
4. Установить pre-commit hooks: `pre-commit install`;
5. Создать новую ветку на основе **develop**: `git checkout -b develop <new_branch_name>`;
6. Внести изменения в код;
7. Сделайте коммит, переместите новую ветку и создайте запрос на мердж **develop**.

Редактируемая установка позволяет свести количество переустановок к минимуму. Разработчику необходимо повторить шаг 3 в случае добавления новых файлов в библиотеку.

A more detailed guide to contributing is available in the [documentation](docs/source/contribution.rst). -->

## Лицензия

Проект имеет лицензию [MIT License](./LICENSE).

## Контакты

- [НЦКР](https://actcognitive.org/o-tsentre/kontakty) - Национальный Центр Когнитивных Разработок.
- [ИДУ](https://idu.itmo.ru/en/contacts/contacts.htm) - Институт Дизайна и Урбанистики.
- Если у вас есть вопросы или предложения, вы можете связаться с нами по следующему адресу: asantonov@itmo.ru (Александр Антонов).

## Цитирование

---



