Message Passing Neural Networks for Molecule Property Prediction
This is the final release of chemprop v1. All future development will be done on chemprop v2. The development team is still happy to answer questions about v1, but no new feature requests or PRs for v1 will be accepted. Users who identify bugs in v1 are still encouraged to open issues to report them - they will be tagged as v1-wontfix to signify that we won't be publishing fixes for them in official chemprop releases, but the bugs can still be open to community discussion.
We encourage all users to try migrating their workflows over to chemprop v2 (available now as a release candidate, stable version planned to be released within the next week) and let us know of any issues you encounter. All v1 releases will remain available on PyPI, and the v1 source code will remain available in this GitHub organization.
uncal_vars for atom/bond property prediction by @shihchengli in https://github.com/chemprop/chemprop/pull/712
if to use correct upstream branch name by @JacksonBurns in https://github.com/chemprop/chemprop/pull/723
Full Changelog: https://github.com/chemprop/chemprop/compare/v1.7.0...v1.7.1
This is a release candidate for Chemprop v2.0.0, to be released in April 2024.
The primary objectives of v2.0.0 are making Chemprop more usable from within Python scripts, more modular, easier to maintain and develop, more compute/memory efficient, and usable with PyTorch Lightning. Some features will not be migrated from v1 to v2 (e.g. web, sklearn). Some v1 features will be added in later versions of v2 (v2.1+) (e.g. uncertainty, interpret, atom- and bond-targets); see milestones here. The new version also has substantially faster featurization speeds and much higher unit test coverage, enables training on multiple GPUs, and works on Windows (in addition to Linux and Mac). Finally, the incorporation of a batch normalization layer is expected to result in smoother training and improved predictions. The label as a “release candidate” reflects its availability to be downloaded via PyPI and that only minor changes are expected for the Python API before the final release. We expect most remaining changes before the release of v2.0.0 in April to be focused on additional improvements to the command line interface (CLI), which does not yet have feature parity with v1. We encourage all Chemprop users to try using v2.0.0-rc.1 to see how it can improve their workflows.
The v2 documentation can be found here.
There are tutorial notebooks for v2 in the examples/ directory.
A helpful transition guide from v1 to v2 can be found here. This includes a side-by-side comparison of CLI argument options, a list of which arguments will be implemented in later versions of v2, and a list of changes to default hyperparameters.
You can subscribe to our development status and notes for this version: https://github.com/chemprop/chemprop/issues/517.
Ongoing work for this version is available on the v2/dev branch.
Please let us know of any bugs you find by opening an issue.
todo.md by @davidegraff in https://github.com/chemprop/chemprop/pull/492
CITATIONS.bib by @JacksonBurns in https://github.com/chemprop/chemprop/pull/627
flask Version in v1 by @JacksonBurns in https://github.com/chemprop/chemprop/pull/628
Full Changelog: https://github.com/chemprop/chemprop/compare/v1.6.1...v1.7.0
PR #383 unexpectedly broke the atom mapping for reaction mode. The issue is described in Issue #426 and fixed by PR #427.
gilbrat Issue by @JacksonBurns in https://github.com/chemprop/chemprop/pull/431
Full Changelog: https://github.com/chemprop/chemprop/compare/v1.6.0...v1.6.1
rdkit and git install in setup.py by @JacksonBurns in https://github.com/chemprop/chemprop/pull/364
make_predictions fails if option --individual_ensemble_predictions is on. by @piotr-semenov in https://github.com/chemprop/chemprop/pull/354
Full Changelog: https://github.com/chemprop/chemprop/compare/v1.5.2...v1.6.0
The parameters to be included in hyperparameter optimization can now be selected using the argument --search_parameter_kewords {list-of-keywords}. The parameters supported are: activation, aggregation, aggregation_norm, batch_size, depth, dropout, ffn_hidden_size, ffn_num_layers, final_lr, hidden_size, init_lr, max_lr, warmup_epochs. Some special kewords are also included for groups of keywords or different search behavior: basic, learning_rate, all, linked_hidden_size.
PR #299
Added capabilities to the uncertainty calibration and evaluation methods to allow them to handle missing target values in multitask jobs. This capability was already included in the normal training of models, now implemented in uncertainty calibration and evaluation. PR #295 Issue #292
When evaluation metrics tend to scale with the magnitude of a task (e.g., rmse), averaging metrics between tasks has been replaced with a geometric mean function. This makes the average metric in multitask regression jobs be less dominated by large magnitude targets. This was previously an issue for hyperparameter optimization and the evaluation of optimal epoch during model training, though the calculation of loss for gradient descent is on scaled targets and was already not scale dependent. PR #290
An empty test split can now be used during training. This was previously possible only using the cv-no-test split method, but now it is available more widely when specifying split sizes, for example with --split_sizes 0.8 0.2 0.
PR #284, #260 related
Issue #279
Conda environment building will now prefer to use the pytorch channel over the conda-forge channel. The Dockerfile has been updated to use micromamba, allowing for faster environment solves than conda and removing a potential licensing issue. PR #276
Corrected a calculation problem in the loss function that was returning infinite loss inappropriately. Also adopted the convention of returning loss of zero when infinite loss is returned, as often happens in very unbalanced datasets. Added appropriate unit testing. PR #309 Issue #306
Corrects an error in the ence uncertainty evaluation method that made that method unusable. Bug was introduced during PR #305. PR #302 Issue #301
Corrected the link to the MoleculeNet benchmark dataset website in the readme, following MoleculeNet migrating to a new site location. PR #296
Previously, this method only worked for single task jobs, now has been extended to work for multitask models as well. PR #291
Version tracking in Chemprop no longer uses the version.py file and it was removed. PR #283
Corrected a typo where the number of classes used in multiclass regression should have been indicated as --multiclass_num_classes.
PR #281
Refactoring of prediction file during the addition of uncertainty functions disabled the option to return the individual predictions of each member of an ensemble of models. Option is now available again. PR #274
Fixed a bug in uncertainty evaluation where the uncertainty evaluator was using the path name originally used to train a checkpoint. This made the uncertainty evaluator only work in the case that the test data and training data used in initial model training had the same path.
Tools added for uncertainty quantification, calibration, and evaluation as part of the chemprop predict function. Uncertainty predictions are saved as part of the predictions file. Uncertainty functions and outputs are triggered using the arguments --uncertainty_method {method}.
Uncertainty outputs can be calibrated using an outside dataset (evaluation set from training is often suitable) in order to have better uncertainty estimates on new predictions. Can be activated using --calibration_method {method} and --calibration_path {path-to-csv}. For the regression dataset type, a calibrated output can provide either a standard deviation or one-sided interval bound, as set with the options --regression_calibrator_metric {stdev-or-interval} and --calibration_interval_percentile {int}.
If the data file containing smiles for the test path also contains target values, the uncertainty performance can be evaluated using various metrics, activated with the option --evaluation_methods {list-of-methods}.
Internally, this PR creates several classes for carrying out prediction tasks: UncertaintyEstimator, UncertaintyPredictor, UncertaintyCalibrator, UncertaintyEvaluator. Loss functions have been added that have auxiliary uncertainty outputs, mve and evidential for regression.
PR #267
PR #269
Gives the option to train a chemprop model using one reaction and one molecule for each datapoint. Active when used with the option --reaction_solvent. Options for making the solvent mpnn use different parameters than that for the reaction are possible using --bias_solvent, --hidden_size_solvent {int}, and --depth_solvent {int}.
PR #246
Added some new changes for fingerprint functions with multiple molecules. Models trained with a "shared-mpn" between two molecules can return a MPN fingerprint with only one molecule provided. Also, when multiple molecule models are used for MPN fingerprint generation, the output will indicate which molecule each element belongs to. PR #242 Issue #236
Created a Jupyter notebook that runs examples of Chemprop jobs, specifically as the functions can be used in python. Good resource for new users, demonstrations, or tutorials. Linked to Google Colab so that it can be run remotely, not requiring any local install of Chemprop. PR #239 PR #273
Previously, loss functions were selected automatically based on the dataset type being used in model training. Now the loss function can be selected with --loss_function {function}. Some new specialty loss functions have been added with this capability.
mcc) is a loss function for classification and multiclass that considers True Positives, True Negatives, False Positives, False Negatives separately in the loss function, avoiding domination by one class and making it well suited to unbalanced training sets.bounded_mse) is a regression loss function that allows for training targets expressed as inequalities, e.g. ">5.0". Intended for use with experimental data with delimited ranges.mve) and evidential loss are regression loss functions that maximize the likelihood of the target on an estimated uncertainty distribution. When used as loss functions, the outputs of these functions can be used in uncertainty estimation.
Appropriate metrics have been added along with these loss functions.
PR #238
PR #267Added a CONTRIBUTING.md file with guidelines for how users can contribute to Chemprop. New templates are now available for issue submission that distinguish between different issue types: bug report, feature request, and questions. New templates also suggested for PRs. Templates stored in the .github directory.
PR #241
Part of an ongoing effort to include a more complete set of automated tests for Chemprop. Unit tests added for data utils, uncertainty-related loss functions, and the uncertainty evaluation metrics. PR #232 PR #267 PR #269
Ongoing effort to standardize the formatting of incoming code. New PRs now request/require the new code to be flake8 compliant in formatting. The utils module and files significantly associated with the new uncertainty function are flake8 compliant. PR #241 PR #258 PR #267
Changed the way that version numbers are stored and updated throughout the code. PR #247
Removed many of the assertion errors throughout Chemprop and replaced them with more easily interpretable error types and messages. PR #257
Changed the way that random seeds are passed into hyperopt during hyperparameter optimization to avoid an error where hyperopt stopped supporting a previously supported way of passing numpy seeds. PR #245 Issue #243 Issue #254 Issue #264
Default model behavior is to treat H atoms implicity with their neighbors. With the previously existing argument --explicit_h, explicit H atoms included in the SMILES string would be considered during message passing. This PR adds a new argument --adding_h, which would make all H atoms treated explicitly during message-passing.
PR #225 and #227
The data-splitting methods scaffold_balanced and random_with_repeated_smiles can only consider one molecule per datapoint in adhering to the constraints of which data must share splits with each other. This PR creates an argument --split_key_molecule {int}, which is used to select which molecule in multi-molecule datasets will be used for the splitting determination.
PR #230
Previously, the split fractions for training/validation were hardcoded as 80/20 when test data was provided via --separate_test_path. Split fractions can now be specified in this case using --split_sizes as normal.
PR #230
This change affects usage of make_predictions as a python function, rather than in the whole Chemprop workflow. When used as a python function, make_predictions would return the predictions for a set of SMILES, but would skip the invalid SMILES without indicating which ones were skipped. Now this function has two new option arguments: 1) return_invalid_smiles that includes invalid SMILES in the output but with "Invalid SMILES" as the prediction value and 2) return_index_dict that returns predictions of the model in a dictionary keyed to the original data indices.
PR #235
New functions have been added to chemprop/data/utils.py to allow users to identify datapoints that have invalid SMILES. These functions are get_invalid_smiles_from_file and get_invalid_smiles_from_list.
PR #235
Bug prevented using extra atom features and extra bond features at the same time and has been resolved. PR #215 Issue #213
Newer versions of pip failed to install some some chemprop dependencies properly. These dependencies (flake8, pytest, parameterized) were moved to an installation as part of the conda environment rather than by pip. Also, environment build for testing was changed from conda to mamba for better install speed. PR #215 and #216
Tutorial file changed to show the proper list of lists format for SMILES. PR #218
When making a prediction for an improper SMILES in a multiclass model, an error would be triggered instead of returning a prediction of "Invalid SMILES". This has been corrected for this case and the parallel case of improper SMILES used with --individual_ensemble_predictions.
PR #229
Molecule fingerprints could not be predicted when extra atom features were provided as part of the model. This and the parallel issue with extra bond features have been addressed. PR #234 Issue #233
Introduces spectra as a new dataset type available for training, in which each target in a multitarget regression refers to a positive intensity value in one position of a spectrum. Training methods are consistent with https://github.com/gfm-collab/chemprop-IR. Default loss function is spectral information divergence (SID), but Wasserstein loss (earthmover distance) is also supported with --metric wasserstein --alternative_loss_function wasserstein.
PR #197
Refactored the make_predictions into smaller functions for better capability to use chemprop functions as a python library. Refactoring specficially designed to allow for the loading of a model using the function chemprop.train.load_model a single time and then using it for multiple instances of predictions by feeding that model as an argument to chemprop.train.make_predictions.
PR #200
Added several new features to hyperparameter optimization, many related to hyperparameter checkpoints saved in the location specified by --hyperopt_checkpoint_dir <dir_path>. The new functionalities:
train.py using -manual_trial_dirs <list-of-directories>.--startup_random_iters <int, default=10>.
PR #208When making predictions from an ensemble of models, returns the mean prediction but also the individual predictions from the individual models when --individual_ensemble_predictions is specified.
PR #190
Allows for the calculation of latent fingerprints from an ensemble of models by concatenating them together. Also allows for the return of either a latent representation from the MPNN output or from the next-to-last FFN layer using the argument --fingerprint_type <MPN or last_FFN>.
PR #193
Sklearn multitask training cannot proceed with missing targets among the data, previously would have needed to be run as multiple singletask models. This PR introduces target imputation for missing data to allow multitask sklearn training even when some data is missing with the argument --impute_mode <model/linear/median/mean/frequent> indicating which method to use for imputation.
PR #210
Issue #211
Adds options in reaction training for how to handle situations where reactants and products are not balanced. The argument --reaction_mode now also has the options reac_diff_balance, prod_diff_balance, and reac_prod_balance (in addition to the current options reac_diff, prod_diff, and reac_prod). Also fixes an error where atomic numbers are incorrect when an atom is present in the products but not in the reactants.
PR #212
Issue #204
Resolves a problem with TAP (typed-argument-parser) where running Chemprop from inside a different git repo would trigger an error related to the generation of a reproducibility hash. In this situation the reproducibility hash is not generated, but it logs the issue and does not stop Chemprop from running. PR #195
Changes the way that global variables related to model construction and feature vector size are handled. Resolves a problem in pytest where these variables wouldn't reset between runs. PR #206