| Install | Docker | Tutorials | Features | Pipeline parameters | Docs |

ATOM Modeling PipeLine (AMPL) for Drug Discovery

An open-source, end-to-end software pipeline for data curation, model building, and molecular property prediction to advance in silico drug discovery.

Created by the Accelerating Therapeutics for Opportunities in Medicine (ATOM) Consortium

Check out our new tutorial series that walks through AMPL's end-to-end modeling pipeline to build a machine learning model! View them in our docs or as Jupyter notebooks in our repo.

The ATOM Modeling PipeLine (AMPL) extends the functionality of DeepChem and supports an array of machine learning and molecular featurization tools to predict key potency, safety and pharmacokinetic-relevant parameters. AMPL has been benchmarked on a large collection of pharmaceutical datasets covering a wide range of parameters. This is a living software project with active development. Check back for continued updates. Feedback is welcomed and appreciated, and the project is open to contributions! An article describing the AMPL project was published in JCIM. For those without access to JCIM, a preprint of the article is available on ArXiv. Documentation is available here.

Table of contents

• Install
  • Quick Install
  • Jupyter kernel
  • Docker
  • Uninstall
• AMPL Features
• Running AMPL
• Tests
• Advanced AMPL usage
• Advanced testing
• Tutorials
• Development
• Project information
• Suggestions or Report Issues

Useful links

• Pipeline parameters (options)

• Library documentation

  Install

  AMPL 1.6 supports Python 3.9 CPU or CUDA-enabled machines using CUDA 11.8 on Linux. All other systems are experimental. For a quick install summary, see here. We do not support other CUDA versions because there are multiple ML package dependency conflicts that can occur. For more information you can look at DeepChem, TensorFlow, PyTorch, DGL or Jax.

Create pip environment

1. Create a virtual env with Python 3.9

Make sure to create your virtual env in a convenient directory that has at least 12Gb space.

Go to the directory where the new environment directory be installed in. Define an environment variable - "ENVROOT".

export ENVROOT=~/workspace # for LLNL LC users, use your workspace
or
export ENVROOT=~ # or the directory as your environment root
cd $ENVROOT

We use "workspace" and "atomsci-env" as an example here.

# LLNL only: 
# module load python/3.9.12
cd $ENVROOT
python3.9 -m venv atomsci-env

2. Activate the environment

source $ENVROOT/atomsci-env/bin/activate

3. Update pip

pip install pip --upgrade

4. Clone AMPL repository

git clone https://github.com/ATOMScience-org/AMPL.git 

5. Install pip requirements

Depending on system performance, creating the environment can take some time.

Note: Based on which environment (CPU or CUDA) to run on, only run one of the following:

• CPU-only installation:

  cd AMPL/pip
  pip install -r cpu_requirements.txt

• CUDA installation:

First load the CUDA module. Then run cuda specific package install.

cd AMPL/pip
# LLNL only: 
# module load cuda/11.8
pip install -r cuda_requirements.txt

If you get out of memory errors, try setting these environment variables:

export LD_LIBRARY_PATH=<your_env>/lib:$LD_LIBRARY_PATH
export PYTHONUSERBASE=<your_env>
export OPENBLAS_NUM_THREADS=1
export OMP_NUM_THREADS=48
export PYTORCH_HIP_ALLOC_CONF=gargage_collection_threshold:0.9,max_split_size_mb:128
export TF_FORCE_GPU_ALLOW_GROWTH=true

6. (Optional) LLNL LC only: if you use model_tracker, install atomsci.clients

# LLNL only: required for ATOM model_tracker
pip install -r clients_requirements.txt

Install AMPL

Run the following to build the "atomsci" modules. This is required.

# return to AMPL parent directory
cd ..
./build.sh
pip install -e .

Installation Quick Summary

export ENVROOT=~/workspace           # set ENVROOT example
cd $ENVROOT                          # go to a convenient home directory
# LLNL only:
# module load python/3.9.12

python3.9 -m venv atomsci-env        # create environment with Python 3.9
source $ENVROOT/atomsci-env/bin/activate 
pip install pip --upgrade               

git clone https://github.com/ATOMScience-org/AMPL.git # clone AMPL
cd AMPL/pip    
# LLNL only:
# If use CUDA: 
# module load cuda/11.8                         
pip install -r cpu_requirements.txt    # install cpu_requirements.txt OR cuda_requirements.txt  

# LLNL only: required for ATOM model_tracker
# pip install -r clients_requirements.txt

cd ..                                   
./build.sh                            
pip install -e .                        

Create jupyter notebook kernel (optional)

To run AMPL from Jupyter Notebook, with your environment activated. To setup a new kernel:

python -m ipykernel install --user --name atomsci-env

Install with Docker

• Download and install Docker Desktop.
  • https://www.docker.com/get-started
• Create a workspace folder to mount with Docker environment and transfer files.
• Get the Docker image and run it.

  docker pull atomsci/atomsci-ampl
  docker run -it -p 8888:8888 -v </local_workspace_folder>:</directory_in_docker> atomsci/atomsci-ampl
  #inside docker environment
  jupyter-notebook --ip=0.0.0.0 --allow-root --port=8888 &
  # -OR-
  jupyter-lab --ip=0.0.0.0 --allow-root --port=8888 &

• Visit the provided URL in your browser, ie
  • http://d33b0faf6bc9:8888/?token=656b8597498b18db2213b1ec9a00e9d738dfe112bbe7566d
  • Replace the "d33b0faf6bc9" with "localhost"
  • If this doesn't work, exit the container and change port from 8888 to some other number such as 7777 or 8899 (in all 3 places it's written), then rerun both commands
• From the notebook, you may need to set the kernel that atomsci is installed ("atomsci-venv") in order to acccess the atomsci package.

Note: Be sure to save any work you want to be permanent in your workspace folder. If the container is shut down, you'll lose anything not in that folder.

Uninstall

To remove AMPL from a pip environment use:

pip uninstall atomsci-ampl

To remove an entire virtual environment named "atomsci-env":

rm -rf $ENVROOT/atomsci-env

To remove cached packages and clear space:

pip cache purge

AMPL Features

Details of running specific features are within the parameter (options) documentation. More detailed documentation is in the library documentation.

Running AMPL

AMPL can be run from the command line or by importing into Python scripts and Jupyter notebooks.

Python scripts and Jupyter notebooks

AMPL can be used to fit and predict molecular activities and properties by importing the appropriate modules. See the examples for more descriptions on how to fit and make predictions using AMPL.

Pipeline parameters

AMPL includes many parameters to run various model fitting and prediction tasks.

• Pipeline options (parameters) can be set within JSON files containing a parameter list.
• The parameter list with detailed explanations of each option can be found at atomsci/ddm/docs/PARAMETERS.md.
• Example pipeline JSON files can be found in the tests directory and the example directory.

Library documentation

AMPL includes detailed docstrings and comments to explain the modules. Full HTML documentation of the Python library is available with the package at https://ampl.readthedocs.io/en/latest/.

More information on AMPL usage

• More information on AMPL usage can be found in Advanced AMPL usage

Tests

AMPL includes a suite of software tests. This section explains how to run a very simple test that is fast to run. The Python test fits a random forest model using Mordred descriptors on a set of compounds from Delaney, et al with solubility data. A molecular scaffold-based split is used to create the training and test sets. In addition, an external holdout set is used to demonstrate how to make predictions on new compounds.

To run the Delaney Python script that curates a dataset, fits a model, and makes predictions, run the following commands:

source $ENVROOT/atomsci-env/bin/activate # activate your pip environment.
cd atomsci/ddm/test/integrative/delaney_RF
pytest

Note: This test generally takes a few minutes on a modern system

The important files for this test are listed below:

• test_delany_RF.py: This script loads and curates the dataset, generates a model pipeline object, and fits a model. The model is reloaded from the filesystem and then used to predict solubilities for a new dataset.
• config_delaney_fit_RF.json: Basic parameter file for fitting
• config_delaney_predict_RF.json: Basic parameter file for predicting

More example and test information

• More details on examples and tests can be found in Advanced testing.

Advanced AMPL usage

Command line

AMPL can fit models from the command line with:

python model_pipeline.py --config_file filename.json # [filename].json is the name of the config file

To get more info on an AMPL config file, please refer to:

• AMPL Features
• Running AMPL
• AMPL Tutorials

Hyperparameter optimization

Advanced testing

Running all tests

To run the full set of tests, use Pytest from the test directory:

source $ENVROOT/atomsci-env/bin/activate # activate your pip environment. "atomsci" is an example here.
cd atomsci/ddm/test
pytest

Running SLURM tests

Running tests without internet access

AMPL tutorials

Please follow link, "atomsci/ddm/examples/tutorials", to access a collection of AMPL tutorial notebooks. The tutorial notebooks give an exhaustive coverage of AMPL features. The AMPL team has prepared the tutorials to help beginners understand the basics to advanced AMPL features, and a reference for advanced AMPL users.

Development

Installing the AMPL for development

Using "pip install -e ." will create a namespace package in your environment directory that points back to your git working directory, so every time you reimport a module you'll be in sync with your working code. Since site-packages is already in your sys.path, you won't have to fuss with PYTHONPATH or setting sys.path in your notebooks.

Code Push Policy

It's recommended to use a development branch to do the work. After each release, there will be a branch opened for development.

The policy is

1. Create a branch based off a development ("1.6.0 "for example) or "master" branch
2. Create a pull request. Assign a reviewer to approve the code changes

Note: Step 2 is required for pushing directly to "master". For a development branch, this step is recommended but not required.

Docstring format

The "Google docstring" format is used in the AMPL code. When writing new code, please use the same Docstring style. Refer here and here for examples.

Versioning

Versions are managed through GitHub tags on this repository.

Built with

• DeepChem: A rich repository of chemistry-specific model types and utilities
• RDKit: Molecular informatics library
• Mordred: Chemical descriptors
• Other Python package dependencies

Project information

Authors

The Accelerating Therapeutics for Opportunities in Medicine (ATOM) Consortium

• Amanda J. Minnich ₍₁₎
• Kevin McLoughlin ₍₁₎
• Margaret Tse ₍₂₎
• Jason Deng ₍₂₎
• Andrew Weber ₍₂₎
• Neha Murad ₍₂₎
• Benjamin D. Madej ₍₃₎
• Bharath Ramsundar ₍₄₎
• Tom Rush ₍₂₎
• Stacie Calad-Thomson ₍₂₎
• Jim Brase ₍₁₎
• Jonathan E. Allen ₍₁₎  

Contributors

• Amanda Paulson ₍₅₎
• Stewart He ₍₁₎
• Da Shi ₍₆₎
• Ravichandran Sarangan ₍₇₎
• Jessica Mauvais ₍₁₎

_{1. Lawrence Livermore National Laboratory}\ _{2. GlaxoSmithKline Inc.}\ _{3. Frederick National Laboratory for Cancer Research}\ _{4. Computable}\ _{5. University of California, San Francisco}\ _{6. Schrodinger}\ _{7. Leidos}  

Support, Suggestions or Report Issues

• If you have suggestions or like to report issues, please click here.  

Contributing

Thank you for contributing to AMPL!

• Contributions must be submitted through pull requests.
• All new contributions must adhere to the MIT license.
   

Release

AMPL is distributed under the terms of the MIT license. All new contributions must be made under this license.

See MIT license and NOTICE for more details.

• LLNL-CODE-795635
• CRADA TC02264