nfdi4chem/sherlock repository overview

⁠Sherlock

Web services for Computer-Assisted Structure Elucidation (CASE).

A graphical user interface⁠ and publication⁠ are available.

⁠Core Features

• Dereplication
• Elucidation
• Retrieval of previously generated results

The dereplication, chemical shift prediction and statistical detection of structural constraints are enabled by using entries from spectral knowledge bases, such as NMRShiftDB⁠, containing both structural and spectral properties.

casekit⁠ serves as computational library in Sherlock.

PyLSD⁠ is used for structure generation.

⁠Docker and Databases

This project uses Docker containers (https://www.docker.com⁠) and starts them via docker compose. Make sure that docker compose is installed.

NOTE: It is recommended to set the accessible RAM to 8 GB or higher and the number of available CPU cores to four or higher. For example, this can be done in the Docker Desktop application, see here⁠.

⁠Download

Clone this repository and change the directory:

git clone https://github.com/NFDI4Chem/sherlock && \
cd sherlock && \
cp env.dist .env

⁠Steps for Data Import and Statistics

In order to fill the database with datasets and to create different statistics, databases in specific SD format, e.g. NMRShiftDB⁠, can be imported into Sherlock's backend system.

The directory data/nmrshiftdb (default) may contain the NMRShiftDB file but ending with .sdf, such as nmrshiftdb.sdf. The directory data/acd_labs_predictions (default) may contain database with predicted spectra produced by ACD/Labs. Each file should not contain more than 125.000 entries, due to potential in-memory issues. Multiple files with subsets are possible, e.g. from LOTUS⁠ or COCONUT, e.g. lotus_1.sdf, lotus_2.sdf etc.

The directory data/lsd/filters (default) may contain molecular fragments in LSD format, such as the filter examples in the data/lsd/PyLSD/LSD/Filters folder, which then will be applied as structural constraints (badlist) to not allow such fragments during the structure generation process.

Uncomment und modify DATASET_NMRSHIFTDB_PATH, DATASET_ACD_LABS_PREDICTIONS_PATH or CUSTOM_FILTERS_PATH in the .env file if another folder than the default ones should be mounted and used by Docker.

After starting via docker compose, run the following script to delete previous database records, load-in the spectral data and to build the statistics.

sh scripts/fill_DBs.sh

After the dataset import, this script continues with building different statitics, such as about hybridisation states or HOSE codes. The progress of that process can be tracked via console logging or via a API endpoint with login data, which can be adjusted in the .env file:

curl -X 'GET' 'http://localhost:8080/database/buildStatistics/status' -u 'admin:password'

⁠Start

Start the docker compose with pre-built images in detached mode:

docker compose up -d

Or to re-build the images, download PyLSD⁠ and make sure that the unpacked folder is located in the data/lsd/ folder and is re-named to "PyLSD". Copy the two modified files from the data/lsd/PyLSD_Variant_mod folder into the data/lsd/PyLSD/Variant folder and overwrite the two existing files there.

To build and start the services in detached mode use:

docker compose up -d --build

The following URL leads to the Swagger UI and offers an overview of what REST endpoints are available, both public or internal (private with login only) ones:

http://localhost:8080/swagger-ui.html

To access the generated OpenAPI JSON file just visit or fetch:

http://localhost:8080/api-docs

⁠Stop

To shutdown the services and to remove the docker compose network use:

docker compose down -v