Package: fastprop
Fast Molecular Property Prediction withmordredcommunityAnnouncement - Open Beta!fastpropis currently in the version 3 open beta (1.0.0b3)!
Please tryfastpropon your datasets and let us know what you think.
Feature requests and bug reports areveryappreciated!Check out the demo notebook for quick intro tofastpropvia Google Colab - runs in your browser, GPU included, no install required!Installingfastpropfastpropsupports Mac, Windows, and Linux on Python versions 3.8 to 3.11 (except 3.11 on Windows).
As dependencies gradually begin to support Python 3.12 it will be added.
Installing frompiporcondais the best way to getfastprop, but if you need to check out a specific GitHub branch or you want to contribute tofastpropa source installation is recommended.pip[recommended]fastpropis available via PyPI withpip install fastprop.To make extendingfastpropeasier and keep the installation size down, dependencies required for hyperparameter optimization and SHAP analysis areoptional.
They can be installed withpip install fastprop[hopt],pip install fastprop[shap], orpip install fastprop[shap,hopt]to install them both.
If you want to usefastpropbut not write new code on top of it, you may want to install these now - you can always do so later, however, andfastpropwill remind you.conda-coming soon!fastpropis available fromconda-forgewithconda install -c conda-forge fastprop.SourceTo installfastpropfrom GitHub directly you can:Runpip install https://github.com/JacksonBurns/fastprop.git@mainto install from themainbranch (or specify any other branch you like)Clone the repository withgit clone https://github.com/JacksonBurns/fastprop.git, navigate tofastpropwithcd fastprop, and runpip install .To contribute tofastpropplease followthis tutorial(or something similar) to set up a forked version offastpropand open a pull request (similar to above option 2).
All contributions are appreciated!
SeeDevelopingfastpropfor more details.Aboutfastpropfastpropis a package for performing deep-QSPR (Quantitative Structure-Property Relationship) with minimal user intervention.
By passing in a list of SMILES strings,fastpropwill automatically generate and cache a set of molecular descriptors usingmordredcommunityand train an FNN to predict the corresponding properties.
See theexamplesandbenchmarksdirectories to see how to run training - the rest of this documentation will focus on how you can run, configure, and customizefastprop.PaperAn academic paper has been prepared which describes thefastpropapproach and walks through thebenchmarksin greater detail.
See thepaperdirectory for more information.fastpropFrameworkThere are four distinct steps infastpropthat define its framework:Featurization - transform the input molecules (as SMILES strings) into an array of molecular descriptors which are savedPreprocessing - clean the descriptors by removing or imputing missing values then rescaling the remainderTraining - send the processed input to the neural network, which is a sample FNN (sequential fully-connected layers with an activation function between)Prediction - save the trained model for future useConfigurable ParametersFeaturizationInput CSV file: comma separated values (CSV) file (with headers) containing SMILES strings representing the molecules and the targetsSMILES column name: name of the column containing the SMILES stringsTarget column name(s): name(s) of the columns containing the targetsandWhichmordreddescriptors to calculate: 'all' or 'optimized' (a smaller set of descriptors; faster, but less accurate).Enable/Disable caching of calculated descriptors:fastpropwill 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 flyorLoad precomputed descriptors: filepath to where descriptors are already cached either manually or byfastpropPreprocessingEnable/Disable dropping of zero-variance parameters (disabled by default; faster, but often less accurate)- Enable/Disable dropping of co-linear descriptors (disabled by default; faster, decreased accuracy)WIPnot configurable:fastpropwill always rescale input features, drop columns with no values, and impute missing values with the per-feature meanTrainingNumber of Repeats: How many times to split/train/test on the dataset (increments random seed by 1 each time).andNumber of FNN layers (default 2; repeated fully connected layers of hidden size)Hidden Size: number of neurons per FNN layer (default 1800)orHyperparameter optimization: runs hyperparameter optimization identify the optimal number of layers and hidden sizegeneric NN training parametersOutput DirectoryLearning rateBatch size- Checkpoint file to resume from (optional)WIPProblem type (one of: regression, binary, multiclass (start labels from 0), multilabel)PredictionInput SMILES: either a single SMILES or a CSV fileOutput format: filepath to write the results or nothing, defaults to stdoutCheckpoints directory: directory where previously trained model(s) areRelationship to ChempropIn addition to having a similar name,fastpropand 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->Chemprop and vice versa).fastpropfeelsa lot like Chemprop but without a lot of the clutter.
Thefastinfastprop(both in usage and execution time) comes from the basic architecture, the use of caching, and the reduced configurability offastprop(i.e. I hope you like MSE loss for regression tasks, because that's the only training metricfastpropwill use).Usingfastpropfastpropcan be run from the command line or as a Python module.
Regardless of the method of use the parameters described inConfigurable Parameterscan be modified.
Some system-specific configuration options can be specified in a.fastpropconfigfile - see theexample file.Command LineAfter installation,fastpropis accessible from the command line viafastprop subcommand, wheresubcommandis eithertrain,predict, orshap.traintakes in the parameters described inConfigurable Parameterssections 1, 2, and 3 (featurization, preproccessing, and training) and trainsfastpropmodel(s) on the input data.predictuses the output of a call totrainto make prediction on arbitrary SMILES strings.shapperforms SHAP analysis on a trained model to determine which of the input features are important.Tryfastprop --helporfastprop subcommand --helpfor more information and see below.Configuration File [recommended]Seeexamples/example_fastprop_train_config.yamlfor configuration files that show all options that can be configured during training.
It is everything shown in theConfigurable Parameterssection.ArgumentsAll of the options shown in theConfiguration Filesection 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 100Seefastprop train --helporfastprop predict --helpfor more information.fastprop shapandfastprop predicthave only a couple arguments and so do not use configuration files.Python ModuleThis section documents where the various modules and functions used infastpropare located.
Check each file listed for more information, as each contains additional inline documentation useful for development as a Python module.
To use the corefastpropmodel and dataloaders in your own work, consider looking atshap.pyortrain.pywhich show how to import and instantiate the relevant classes.fastpropdefaults: contains the functioninit_loggerused to initialize loggers in different submodules, as well as the default configuration for training.fastprop_core: the model itself and convenience functions.hopt: hyperparameter optimization using Optuna and Ray[tune], used by the CLI.train: performs model training, used by the CLI.predict: loads models from their checkpoint and config files and runs inference, used by the CLI.shap: performs SHAP analysis on a previously trained model, used by the CLI.preprocessing: performs all of the preprocessing described above.fastprop.utilscalculate_descriptors: wraps themordredcommunitydescriptor calculator.linear_baseline: trains a basic linear model on the same inputs tofastpropto act as a baseline.descriptor_lists: hardcoded lists of all of the descriptors implemented inmordredcommunity.select_descriptors: the script to retrieve themordredcommunitymodules based on the strings in the above file (mordredcommunityhas a weird interface; thus, it is wrapped).load_data: short wrappers topandasCSV loading utility, but specialized for the output frommordredcommunityandfastprop.validate_config:WIPvalidate the input from the command line.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.BenchmarksThebenchmarksdirectory contains the scripts needed to perform the studies (seebenchmarks/README.mdfor more detail, they are a great way to learn how to usefastprop).
To just see the results, checkoutpaper/paper.pdf(orpaper/paper.mdfor the plain text version).DevelopingfastpropBug reports, feature requests, and pull requests are welcome and encouraged!
Followthis tutorial from GitHubto get started.fastpropis built around PyTorch lightning, which defines a rigid API for implementing models that is followed here.
See thesection on the package layoutfor 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 thepyproject.tomldefines optionaldevandbmarkpackages, which will get you setup with the same dependencies used for CI and benchmarking.