API для извлечения информации из баз данных Pubchem и дальнейшего взаимодействия с этими данными.

• Структура проекта
• Документация на Confluence
• Настройка виртуального окружения
• Разворачивание локальной базы данных MongoDB
• Настройка переменных окружения
• Консольная утилита для работы с данными Pubchem
• Схема локальной базы данных
• Документация API

• Описание проекта
• Что можно скачать из баз данных PubChem
• Как использовать molecad
• Как развернуть MongoDB локально на macOS
• Как и зачем использовать pyenv
• rdkit/mongo-rdkit и их зависимости

Перед тем как приступить к настройке виртуального окружения, убедитесь, что на вашем компьютере установлены pyenv и poetry, причем их пути должны быть добавлены в PATH. Подробнее об использовании pyenv и poetry читайте тут

Склонируйте репозиторий и запустите shell из директории, содержащей файл pyproject.toml.

В проекте используется Python версии 3.7.10, который вы можете установить, используя pyenv:

$ pyenv install 3.7.10
$ pyenv local 3.7.10

Создать виртуальное окружение и установить все зависимости проекта можно с помощью poetry:

$ poetry install

Вуаля! Все зависимости проекта установлены и никакой конды, вам не потребовалось.
Подробнее о реализации пути через conda можно почитать тут.

После настройки виртуальной среды, необходимо задать переменные окружения – это параметры для подключения к mongodb и запуска скрипта, выполняющего запросы к базам данных Pubchem.
Удобнее всего установить переменные один раз, создав файл .env – для тестовой базы данных и файл .env.prod– для основной базы из шаблона .env.sample.

В корневой директории найдите файл .env.sample, скопируйте его, заполните недостающие поля и переименуйте файл в .env; то же самое повторите для .env.prod.

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

Установите на свой компьютер сервер MongoDB: Community Server можно поставить с помощью менеджера пакетов для macOS - brew, а Enterprise Server - из архива .targz. Добавьте путь до исполняемого файла в PATH.

Ниже описаны основные шаги разворачивания локальной базы на примере Enterprise Server. Детальное описание процесса установки и инструкции для Community Server можно найти по ссылке.

Переходим в каталог с только что установленным сервером MongoDB и создаем в нем подкаталог для локальной базы, после чего запустим сервер.

$ mkdir -p ./data/db
$ mongod --dbpath ./data/db

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

$ mongo
MongoDB Enterprise> use admin
MongoDB Enterprise> db.createUser({ user: "superuser", pwd: "<pwd>", roles: [ "root" ] })

После того как пользователь будет создан, нужно выключить сервер и выйти в исходный shell.

MongoDB Enterprise> db.shutdownServer()
MongoDB Enterprise> exit

Теперь перезапускаем сервер mongod, но с параметром --auth для подключения по логину-паролю.

$ mongod --dbpath ./data/db --auth
$ mongo mongodb://superuser:<password>@127.0.0.1:27017/admin

Готово! Теперь вы можете использовать свою базу.

Данный проект предоставляет доступ к консольной утилите для извлечения информации о свойствах молекул с серверов Pubchem, подготовки и сохранения полученных данных в файлы формата JSON, а также загрузки содержимого в базу данных MongoDB.

Запуск команд утилиты рекомендуется производить из корневой директории проекта. Команды, которые непосредственно взаимодействуют с базой данных, требуют наличие запущенной службы mongod. Информация по настройке локальной базы указана в разделе: Как развернуть MongoDB локально на macOS

Справка по работе утилиты:

$ poetry run python -m molecad.cli --help  

Usage: python -m molecad.cli [OPTIONS] COMMAND [ARGS]...

  Консольная утилита для извлечения информации о свойствах молекул с серверов
  Pubchem, сохранения полученной информации в файлы формата JSON. Также с
  помощью утилиты можно загружать полученные данные в базу MongoDB и
  подготавливать их для поиска молекул.

Options:
  --database [PROD|DEV]  Опция позволяет выбирать конфигурационный файл,
                         содержащий переменные окружения и настройки базы
                         данных.
  --help                 Show this message and exit.

Commands:
  fetch     Извлекает и сохраняет информацию из базы данных Pubchem –...
  populate  Из указанной директории загружает файлы в коллекцию MongoDB.
  split     При использовании команды "db.collection.insert_many({...})"...

Для получения данных о свойствах молекул из баз данных Pubchem нужно запустить команду fetch консольной утилиты с обязательными параметрами start и stop, которые задают диапазон интересуемых молекул по их идентификаторам (CID). Запрос на сервер отсылается порциями идентификаторов; размер порции указывается параметром --size, который по умолчанию равен 100. Не рекомендуется уменьшать параметр, так как это приведет к значительному увеличению времени работы программы, в то же время не рекомендуется его увеличивать, так как это может привести к превышению ограничения на количество символов в строке генерируемого URL-адреса. В ходе работы команды fetch консольной утилиты, программа не ждет пока выполнятся все запросы для того, чтобы сохранить все данные в файл, а пишет результаты по мере выполнения: в директории ./data/fetch/ создается поддиректория, называемая в соответствии с параметрами start и stop; в созданную поддиректорию сохраняются файлы, имеющие названия, составленные из крайних значений диапазонов идентификаторов сохраняемого файла. Размер диапазона задается при вызове команды fetch с опцией --f-size.

Справка по команде fetch:

$ poetry run python -m molecad.cli fetch --help

Usage: python -m molecad.cli fetch [OPTIONS]

  Извлекает и сохраняет информацию из базы данных Pubchem – 'Compound'. Для
  совершения запроса к серверу необходимо уточнить диапазон идентификаторов
  интересуемых соединений - 'CID'. Данные извлекаются путем отправления
  запроса на сгенерированный URL. Из-за ограничения на количество символов в
  строке URL, отправка запроса, включающего все желаемые идентификаторы, может
  привести к ошибке, поэтому рекомендуется использовать опцию `--size`,
  которая по умолчанию равна `100`. Полученные данные сохраняются в файл,
  причем имеется возможность сохранять файл порциями до окончания работы
  программы, указав в качестве опции `--f-size` желаемое количество
  идентификаторов в сохраняемом файле, которое по умолчанию равна `1000`.

Options:
  --start INTEGER   Первое значение из запрашиваемых CID.  [required]
  --stop INTEGER    Последнее значение из запрашиваемых CID.  [required]
  --size INTEGER    Максимальное число идентификаторов в одном запросе, по
                    умолчанию равно 100.  [default: 100]
  --f-size INTEGER  Максимальное число идентификаторов в сохраняемом файле, по
                    умолчанию равно 1000.  [default: 1000]
  --help            Show this message and exit.

Пример запуска команды fetch:

$ poetry run python -m molecad.cli fetch --start 1 \
                                         --stop 1000000 \
                                         --size 100 \
                                         --f-size 1000  

Так как MongoDB имеет ограничение на количество создаваемых документов при разовой загрузке в базу из файла, то дальнейший план будет определяться длинной списка, который находится в этом файле. Если длина списка (число запрошенных идентификаторов) < 100000, то этот файл можно сразу загрузить в локальную базу данных MongoDB, используя команду populate. Иначе перед загрузкой потребуется его разделение на chunked-файлы меньшего размера с помощью команды split. Для выполнения команды split требуется указать параметр --file, который является путем до разделяемого файла, и параметр --f-size для указания числа элементов в выходных файлах; по умолчанию – 1000.

Справка по команде split:

$ poetry run python -m molecad.data.console split --help

Usage: python -m molecad.cli split [OPTIONS]

  При использовании команды "db.collection.insert_many({...})" имеется
  ограничение на максимально допустимое количество добавляемых документов за
  один раз равное 100000. Данная функция служит для того, чтобы разрезать
  JSON-файлы, превышающие указанное выше ограничение, на файлы меньшего
  размера.

Options:
  --file PATH       Файл не подходящий под критерии загрузки файлов в MongoDB.
                    [required]
  --f-size INTEGER  Максимальное число идентификаторов в сохраняемом файле, по
                    умолчанию равно 1000.  [default: 1000]
  --help            Show this message and exit.

Пример запуска команды split:

Пример запуска команды:
$ poetry run python -m molecad.cli split --file <path/to/file>.json \
                                         --f-size 1000

Файлы, которые содержат в себе до 100000 документов, можно загрузить в локальную базу с помощью команды populate. Данная операция требует, чтобы на момент запуска команды утилиты сервер mongod был запущен, что можно сделать при помощи команды:

mongod [--dbpath <path_to_mongodb./data/db>] --auth

Выбор базы осуществляется с помощью указания опции --setup для выбора настроек "PROD" или "DEV" окружения, по умолчанию будет использовано DEV-окружение. Для запуска команды populate необходимо указать директорию, в которой расположены файлы формата *.json с помощью опции --f-dir, причем в качестве этого параметра может быть указана родительская директория для обхода всех поддиректорий, содержащих файлы данного формата. Если требуется сбросить базу, то требуется указать опцию --drop, после чего все существующие коллекции будут удалены и вновь созданы, причем на коллекциях "properties" и "molecules" создаются уникальные индексы, которые не позволяют повторно загрузить данные по уже имеющимся молекулам в базу.

Справка по команде populate:

$ poetry run python -m molecad.cli --database DEV populate --help
           
  Из указанной директории загружает файлы в коллекцию MongoDB. Количество
  документов в файле не должно превышать 100000, иначе данный файл будет
  пропущен при загрузке. При указании опции "--drop" удаляет все коллекции в
  базе, после чего создает их заново и устанавливает уникальный индекс "CID" и
  индекс "index" на коллекциях "properties" и "molecules". 

Options:
  --f-dir PATH  Путь до директории, содержащей chunked-файлы, каждый из
                которых представляет собой список длиной до 100000 элементов.
                [required]
  --drop        Если опция "--drop" указана, то база будет очищена.
  --help        Show this message and exit.

Пример запуска команды populate:

$ poetry run python -m molecad.cli --setup="PROD" populate --f-dir <path_to_dir> --drop 

Исторически сложилось, что mongo-rdkit и просто rdkit используют виртуальное окружение conda для разрешения своих зависимостей. Но в данном проекте было решено реализовать управление зависимостями этих библиотек с использованием poetry.
Если вы хотите использовать окружение конды и вам хочется узнать, как установить conda рядом с pyenv наиболее безболезненно – читайте тут.

После того как мы настроили окружение, его переменные, развернули MongoDB и загрузили все скачанные данные в локальную базу – можно приступать к рассмотрению задачи о подструктурном поиске. Перед этим нужно отметить несколько ключевых моментов, которые были учтены при выполнении команды populate:

• По причине того что поиск производится по smiles молекул, каждый документ должен содержать поле CanonicalSMILES. В противном случае такие документы будут удалены из коллекции.
• rdkit или mongo-rdkit не генерирует схемы для металлогранических соединений, поэтому документы из коллекции properties, которые не имеют документов-схем в коллекции molecules, также удаляются из коллекции properties.
• При загрузке в локальную базу данных, извлеченных из Pubchem, первичный индекс _id документов каждый раз генерируется MongoDB. Это может повлечь за собой создание дублирующих документов, отличающихся по сгенерированному _id, при повторной загрузке файла с помощью команды populate без опции --drop. Во избежание подобных ситуаций на коллекциях properties и molecules создаются уникальные индексы CID и index.
• Во избежание путаницы для каждого документа из коллекции properties поле CID копируется в коллекцию molecules, а поле index из коллекции molecules – в коллекцию properties.

Пакет mongo-rdkit имеет два модуля: Database и Search. С помощью модуля Database команда populate, получая SMILES молекулы из коллекции properties, создает в коллекции molecules документы, являющиеся представлением молекул в соответствии с генерируемой схемой. В нашем случае экземпляры MolDocScheme включают в себя бинарное представление молекулы, имя схемы, index, smiles, hashes (smiles, inchi), fingerprints и value_data, и эта информация используется при создании документов в коллекции molecules. Второй модуль – Search – используется API для подготовки данных и выполнения подструктурного поиска по локальной базе на основе предоставленного SMILES. Подготовка данных производится на этапе загрузки данных в базу при помощи команды populate.

Данный проект предоставляет API для выполнения подструктурного поиска по локальной базе данных со свойствами химических соединений, которые были извлечены из Pubchem и загружены в локальную базу с помощью консольной утилиты molecad.cli.

Для проведения подструктурного поиска по локальной базе данных, нужно удостовериться, что на локальной машине запущен сервер mongod, и запустить сервер API с помощью следующей команды:

$ poetry run uvicorn molecad.api:app --reload

В данной версии сервиса API имеет два эндпоинта:

• /v0/compound – проводит поиск по подструктуре, после чего выводит результаты в соответствии с переданными параметрами пагинации;
• /v0/compound/summary – проводит поиск по подструктуре, после чего группирует результаты и считает для всех численных величин среднее значение и среднее отклонение среди помножества полученных результатов.

При запуске модуля molecad.front.main произойдет старт сервера, который выполняет роль клиента, предоставляющего пользователю возможность рисовать структурные формулы органических соединений в окне браузера. После того как молекула нарисована, ее необходимо выделить и задать параметры для интересуемого типа поиска, после чего нажать кнопку RUN. В результате этих действий пользователь получит ответ не покидая окна браузера в виде таблицы результатов, которые были предоставлены с помощью выше описанного API.

mongod --config /etc/mongod.conf
mongod -f /etc/mongod.conf

ps aux | grep -v grep | grep mongod