The fastprop
paper is freely available online at arxiv.org/abs/2404.02058 and we are conducting open source peer review on alphaXiv - comments are appreciated!
The source for the paper is stored in this repository under the paper
directory.
fastprop
version 1 is officially released, meaning the API is now stable and ready for production use!
Please try fastprop
on your datasets and let us know what you think.
Feature requests and bug reports are very appreciated!
fastprop
fastprop
supports Mac, Windows, and Linux on Python versions 3.8 to 3.12.
Installing from pip
is the best way to get fastprop
, but if you need to check out a specific GitHub branch or you want to contribute to fastprop
a source installation is recommended.
Pending interest from users, a conda
package will be added.
Check out the demo notebook for quick intro to fastprop
via Google Colab - runs in your browser, GPU included, no install required:
pip
[recommended]fastprop
is available via PyPI with pip install fastprop
.
To make extending fastprop
easier and keep the installation size down, dependencies required for hyperparameter optimization and SHAP analysis are optional.
They can be installed with pip install fastprop[hopt]
, pip install fastprop[shap]
, or pip install fastprop[shap,hopt]
to install them both.
If you want to use fastprop
but not write new code on top of it, you may want to install these now - you can always do so later, however, and fastprop
will remind you.
To install fastprop
from GitHub directly you can:
pip install https://github.com/JacksonBurns/fastprop.git@main
to install from the main
branch (or specify any other branch you like).git clone https://github.com/JacksonBurns/fastprop.git
, navigate to fastprop
with cd fastprop
, and run pip install .
To contribute to fastprop
please follow this tutorial (or something similar) to set up a forked version of fastprop
and open a pull request (similar to above option 2).
All contributions are appreciated!
See Developing fastprop
for more details.
fastprop
fastprop
is a package for performing deep-QSPR (Quantitative Structure-Property Relationship) with minimal user intervention.
By passing in a list of SMILES strings, fastprop
will automatically generate and cache a set of molecular descriptors using mordredcommunity
and train an FNN to predict the corresponding properties.
See the examples
and benchmarks
directories to see how to run training - the rest of this documentation will focus on how you can run, configure, and customize fastprop
.
fastprop
FrameworkThere are four distinct steps in fastprop
that define its framework:
and
mordred
descriptors to calculate: ‘all’ or ‘optimized’ (a smaller set of descriptors; faster, but less accurate).fastprop
will by default cache calculated descriptors based on the input filename and warn the user when it loads descriptors from the file rather than calculating on-the-flyor
fastprop
fastprop
will always rescale input features, set invariant and missing features to zero, and impute missing values with the per-feature meanand
or
generic NN training parameters
fastprop
fastprop
can be run from the command line or as a Python module.
Regardless of the method of use the parameters described in Configurable Parameters can be modified.
After installation, fastprop
is accessible from the command line via fastprop subcommand
, where subcommand
is either train
, predict
, or shap
.
train
takes in the parameters described in Configurable Parameters sections 1, 2, and 3 (featurization, preproccessing, and training) and trains fastprop
model(s) on the input data.predict
uses the output of a call to train
to make prediction on arbitrary SMILES strings.shap
performs SHAP analysis on a trained model to determine which of the input features are important.Try fastprop --help
or fastprop subcommand --help
for more information and see below.
See examples/example_fastprop_train_config.yaml
for configuration files that show all options that can be configured during training.
It is everything shown in the Configurable Parameters section.
All of the options shown in the Configuration File section can also be passed as command line flags instead of written to a file.
When passing the arguments, replace all _
(underscore) with -
(hyphen), i.e. fastprop train --number-epochs 100
See fastprop train --help
or fastprop predict --help
for more information.
fastprop shap
and fastprop predict
have only a couple arguments and so do not use configuration files.
See examples/fastprop_computational_adme_demo.ipynb
, benchmarks/quantumscents/quantumscents.py
, and benchmarks/fubrain/delta_fubrain.py
.
This section documents where the various modules and functions used in fastprop
are located.
Check each file listed for more information, as each contains additional inline documentation useful for development as a Python module.
To use the core fastprop
model and dataloaders in your own work, consider looking at shap.py
or train.py
which show how to import and instantiate the relevant classes.
fastprop
defaults
: contains the function init_logger
used to initialize loggers in different submodules, as well as the default configuration for training.model
: the model itself and a convenience function for training.metrics
: wraps a number of common loss and score functions.descriptors
: functions for calculating descriptors.data
: functions for cleaning and scaling data.io
: functions for loading data from files.fastprop.cli
fastprop_cli
` contains all the CLI code which is likely not useful in use from a script.
If you wish to extend the CLI, check the inline documentation there.
The benchmarks
directory contains the scripts needed to perform the studies (see benchmarks/README.md
for more detail, they are a great way to learn how to use fastprop
).
To just see the results, checkout paper/paper.pdf
(or paper/paper.md
for the plain text version).
In addition to having a similar name, fastprop
and Chemprop do a similar things: map chemical structures to their corresponding properties in a user-friendly way using machine learning.
I (@JacksonBurns) am also a developer of Chemprop so some code is inevitably shared between the two (fastprop
to Chemprop and vice versa).
fastprop
feels a lot like Chemprop but without a lot of the clutter.
The fast
in fastprop
(both in usage and execution time) comes from the basic architecture, the use of caching, and the reduced configurability of fastprop
(i.e. I hope you like MSE loss for regression tasks, because that’s the only training metric fastprop
will use via the CLI).
fastprop
Bug reports, feature requests, and pull requests are welcome and encouraged! Follow this tutorial from GitHub to get started.
fastprop
is built around PyTorch lightning, which defines a rigid API for implementing models that is followed here.
See the section on the package layout for information on where all the other functions are, and check out the docstrings and inline comments in each file for more information on what each does.
Note that the pyproject.toml
defines optional dev
and bmark
packages, which will get you setup with the same dependencies used for CI and benchmarking.