lpce 0.1.0
Ligand-protein complex extraction
Requires Python: >=3.11

# LPCE: Ligand Processing and Cleaning Engine

Проект LPCE предназначен для очистки и обработки структур PDB с целью извлечения и фильтрации лигандов, а также удаления ненужных компонентов, таких как молекулы воды и мусорные лиганды.

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

```
├── README.md             <- Основной README-файл для разработчиков.
│
├── data                  <- Дополнительные данные.
│   ├── grouped_complexes.json          <- Группированные по цепям комплексы лигандов.
│   ├── site_info.json                  <- Информация о сайтах связывания лигандов.
│   ├── removed_ligands_summary.json    <- Сводка по удаленным лигандам.
│   ├── removed_files.json              <- Сводка по удаленным комплексам.
│   ├── trash_ligands.json              <- Список мусорных лигандов для удаления.
│   └── trash_ligands_mini.json         <- Сокращенный список мусорных лигандов для тестов.
│
├── lpce                  <- Исходный код проекта.
│   ├── cleanup           <- Скрипты для очистки PDB-файлов от ненужных компонентов.
│   │   ├── __init__.py
│   │   ├── filter_ligands.py           <- Скрипт для фильтрации лигандов.
│   │   ├── remove_dna_rna.py           <- Скрипт для удаления ДНК и РНК из PDB-файлов.
│   │   ├── remove_empty_structures.py  <- Скрипт для удаления пустых структур.
│   │   ├── remove_junk_ligands.py      <- Скрипт для удаления мусорных лигандов из PDB-файлов.
│   │   ├── remove_multiple_models.py   <- Скрипт для удаления моделей с несколькими конфигурациями.
│   │   ├── remove_water.c              <- Программа на C для удаления молекул воды.
│   │   └── remove_water.py             <- Python-обертка для удаления молекул воды.
│   │
│   ├── config            <- Настройки и конфигурации проекта.
│   │   ├── config.yaml                 <- Основной файл конфигурации.
│   │   └── config_trash_mini.yaml      <- Альтернативный конфиг для мини-набора данных.
│   │
│   ├── extraction        <- Скрипты для извлечения PDB-файлов и данных лигандов.
│   │   ├── __init__.py
│   │   ├── convert_pdb_to_smiles_sdf.py <- Конвертирует PDB в SMILES и SDF форматы.
│   │   ├── decompress_files.py          <- Распаковывает PDB-файлы.
│   │   ├── extract_complexes.py         <- Извлекает комплексы из PDB-файлов.
│   │   └── parse_dict.py                <- Создает словари и структурирует данные.
│   │
│   ├── pdb_manipulations <- Скрипты для манипуляции с PDB-файлами.
│   │   ├── __init__.py
│   │   ├── add_h_to_ligands.py         <- Добавляет атомы водорода к лигандам.
│   │   ├── foldseek.py                 <- Ищет дубликаты структур с помощью Foldseek.
│   │   ├── protein_ligand_separator.py <- Разделяет белки и лиганды в PDB-файлах.
│   │   ├── remove_not_buried_ligands.py <- Удаляет лиганды, не погруженные в белок.
│   │   ├── remove_similar_structures.py <- Удаляет похожие структуры.
│   │   └── split_bioml.py              <- Разделяет биологические сборки в PDB-файлах.
│   │
│   ├── tests             <- Тесты для проверки функциональности проекта.
│   │   ├── conftest.py                  <- Конфигурационный файл для pytest.
│   │   └── test_pipeline.py             <- Скрипт для запуска тестового конвейера обработки.
│   │
│   ├── utils             <- Утилиты и вспомогательные функции.
│   │   ├── __init__.py
│   │   ├── calc_descriptors.py         <- Вычисляет химические дескрипторы.
│   │   ├── clean_names.py              <- Очищает имена файлов и директорий.
│   │   ├── sdf2df.py                   <- Конвертирует SDF-файлы в DataFrame.
│   │   ├── send_email.py               <- Отправляет уведомления по электронной почте.
│   │   ├── smi2df.py                   <- Конвертирует SMILES в DataFrame.
│   │   └── utils.py                    <- Общие вспомогательные функции.
│   │
│   └── run_full_pipeline.py             <- Скрипт для запуска полного конвейера обработки.
│
├── notebook              <- Jupyter ноутбуки для анализа и визуализации данных.
│
├── Makefile              <- Скрипты для автоматизации сборки и запуска.
├── environment.yml       <- Описание зависимостей для создания окружения.
├── pyproject.toml        <- Конфигурационный файл проекта.
└── README.md             <- Этот файл.

```

## Описание основных модулей

### lpce/pdb_manipulations

- **add_h_to_ligands.py**: Добавляет атомы водорода к лигандам с использованием Open Babel.
- **foldseek.py**: Использует инструмент Foldseek для поиска дубликатов и схожих структур среди PDB-файлов.
- **protein_ligand_separator.py**: Разделяет белки и лиганды в PDB-файлах, выделяя комплексы для дальнейшего анализа.
- **remove_not_buried_ligands.py**: Удаляет лиганды, которые не взаимодействуют с белком на заданном уровне (не "погружены" в белок).
- **remove_similar_structures.py**: Удаляет похожие структуры на основе последовательности и разрешения, оставляя наиболее качественные.
- **split_bioml.py**: Разделяет биологические сборки в PDB-файлах на отдельные единицы для индивидуального анализа.

### lpce/tests

- **conftest.py**: Конфигурационный файл для pytest, содержит общие фикстуры и настройки тестирования.
- **test_pipeline.py**: Скрипт для запуска полного конвейера обработки на тестовых данных, проверяет корректность работы всех модулей.

### lpce/utils

- **calc_descriptors.py**: Вычисляет химические дескрипторы для лигандов, необходимые для дальнейшего анализа.
- **clean_names.py**: Очищает и стандартизирует имена файлов и директорий.
- **sdf2df.py**: Преобразует файлы SDF в формат pandas DataFrame для удобства обработки.
- **send_email.py**: Отправляет уведомления по электронной почте о статусе выполнения конвейера или возникновении ошибок.
- **smi2df.py**: Конвертирует SMILES-формат лигандов в pandas DataFrame.
- **utils.py**: Содержит вспомогательные функции, используемые в различных модулях проекта.

### lpce/cleanup

- **filter_ligands.py**: Фильтрует лиганды по заданным критериям (например, по размеру или составу).
- **remove_dna_rna.py**: Удаляет ДНК и РНК из PDB-файлов, оставляя только белки и лиганды.
- **remove_empty_structures.py**: Удаляет PDB-файлы, не содержащие необходимых компонентов после очистки.
- **remove_junk_ligands.py**: Удаляет нежелательные или "мусорные" лиганды, указанные в списке.
- **remove_multiple_models.py**: Удаляет дополнительные модели в PDB-файлах, оставляя только первую модель.
- **remove_water.c**: Программа на языке C для эффективного удаления молекул воды из PDB-файлов.
- **remove_water.py**: Python-обертка для взаимодействия с `remove_water.c`.

### lpce/extraction

- **convert_pdb_to_smiles_sdf.py**: Конвертирует PDB-файлы в форматы SMILES и SDF для химического анализа.
- **decompress_files.py**: Распаковывает сжатые PDB-файлы для последующей обработки.
- **extract_complexes.py**: Извлекает комплексы белок-лиганд из PDB-файлов.
- **parse_dict.py**: Создает словари и структуры данных для удобства доступа к информации о лигандах и комплексах.

### notebook

- **ligand_eda.ipynb**: Проводит разведочный анализ данных (EDA) по лигандам, визуализирует различные свойства.
- **misato.ipynb**: Содержит дополнительные исследования и анализы (детали могут быть специфичными для проекта).
- **pdb_fix.ipynb**: Демонстрирует методы исправления и проверки PDB-файлов на ошибки и несоответствия.
- **protein_ligand_separator.ipynb**: Визуализирует процесс разделения белков и лигандов из комплексных структур.
- **remove_similar.ipynb**: Анализирует и визуализирует процесс удаления похожих структур из набора данных.

## Установка

Для работы с проектом LPCE вам необходимо активировать виртуальное окружение. Убедитесь, что файл `environment.yml` находится в корне проекта, затем выполните следующие шаги:

1. **Установка окружения**:

   В терминале выполните команду для создания окружения на основе существующего файла `environment.yml`:

   ```bash
   conda env create -f environment.yml
   ```

2. **Активация окружения**:

   После успешного создания окружения активируйте его с помощью команды:

   ```bash
   conda activate lpce
   ```

Теперь ваше окружение готово к использованию, и вы можете запускать скрипты проекта, находясь в этом окружении.

## Сборка `remove_water.c`

Если бинарный файл `remove_water` уже присутствует и совместим с вашей системой, сборка не требуется.

### Сборка на новом ПК

Если бинарный файл отсутствует или несовместим:

1. Перейдите в директорию с `remove_water.c`:

   ```bash
   cd lpce/cleanup
   ```

2. Скомпилируйте:

   ```bash
   gcc -o remove_water remove_water.c
   ```

Это создаст исполняемый файл `remove_water` для использования в проекте.

## Конфигурация

Основные параметры проекта, такие как пути к директориям и переменные окружения, настраиваются в `lpce/config/`.

## Запуск

### Полный запуск всех этапов обработки данных

Для запуска полной обработки данных выполните:

```bash
make tmux
```

Этот скрипт выполнит последовательную обработку, очистку и извлечение лигандов, а также отправит уведомление о завершении работы.