main

main

Tools for reaction yield prediction and analysis.

Classes:

Name	Description
Config	Configuration for training and evaluating models on reaction analysis data.

Functions:

Name	Description
data_splits	Splits the data into training and testing sets.
save_cv_errors_to_file	Saves errors from k-fold cross-validation to a file.
save_errors_to_file	Saves errors from a single model to a file.
feature_importance_analysis	Analyzes feature importance using the trained model. Supports CatBoostRegressor and
fit_model	Trains a single machine learning model (e.g., CatBoost, Lasso, MLP, XGBoost,
kfold_prediction	Performs k-fold cross-validation with CatBoostRegressor or other models to obtain
optimise_model	Optimizes model hyperparameters using Optuna with k-fold cross-validation.
plot_results	Plots the results of the model, including reference vs. predicted values and
convert_back_from_01	Maps logit prediction back to range (0, 100).
convert_to_01	Maps y in (0, 100) to (-inf, inf).
get_data	Loads reference values of the chosen property together with descriptors and
get_data_latent	Loads experimental data (experimental conditions) together with latent descriptors.
prediction_run	Trains a reaction analysis property prediction model using the specified
model_training_pipeline	Trains a reaction analysis property prediction model, with optional transfer

Attributes:

Name	Type	Description
parser
args

Attributes

parser module-attribute

parser = ArgumentParser()

args module-attribute

args = parse_args()

Classes

Config dataclass

Config(prop: str = 'conv', prop_str: str = '', prop_unit: str = '', prop_log: bool = False, output_folder: str = '', db_path: str = '../../../examples/reaction_analysis/database/fr5_init_reaction_data_20250506.db', db_type: str = 'experimental', y_col_id: int = 1, model_params_path: str = '../../../examples/mof_properties/co2_uptake/best_params.json', opt_model: bool = False, optuna_params: dict[str, Any] = dict(), opt_ntrials: int = 100, opt_nsplits: int = 5, cross_valid_nsplits: int = 5, model_train_size: float = 0.8, model_test_size: float = 0.2, model_early_stopping_rounds: int = 50, pressure_max: float = 10000000000.0, pressure_min: float = 0.1, feature_importance_analysis: bool = False, save_train_set: bool = False, save_test_set: bool = False, plot_include_train_set: bool = False, il_species: list[str] = (lambda: ['cation', 'anion'])(), il_descr_type: list[str] = (lambda: ['mordred', 'rdkit', 'morgan', 'maccs'])(), split_by_mof_col_name: str = 'mof_name', split_by_mof: bool = False, transform_01: bool = False, model_type: str = 'catboost', tl: bool = False, include_fr5_data: bool = False, init_model_path: str | None = None, fr5_ils: list[str] = list(), bo_conv: bool = False, latent_descriptor: bool = False)

Configuration for training and evaluating models on reaction analysis data.

Attributes:

Name	Type	Description
prop	str	Target property to predict (e.g., 'conv').
prop_str	str	String for displaying the property (can include LaTeX formatting).
prop_unit	str	Unit of the property for display purposes.
prop_log	bool	Whether to apply a logarithmic transform to the target property.
output_folder	str	Folder to save model outputs, plots, and logs.
db_path	str	Path to SQLite database containing reaction data.
db_type	str	Type of database to use (e.g., 'experimental').
y_col_id	int	Column index of the target property in the database (0-based).
model_params_path	str	Path to the JSON file containing model parameters for CatBoostRegressor.
opt_model	bool	Whether to perform hyperparameter optimization with Optuna.
optuna_params	Dict[str, Any]	Dictionary of Optuna optimization parameters.
opt_ntrials	int	Number of Optuna trials to perform if opt_model is True.
opt_nsplits	int	Number of cross-validation splits used during Optuna tuning.
cross_valid_nsplits	int	Number of splits for final model cross-validation.
model_train_size	float	Fraction of data used for training the final model.
model_test_size	float	Fraction of data held out for testing.
model_early_stopping_rounds	int	Number of early stopping rounds used in model training.
pressure_max	float	Maximum pressure in Pa for the training set.
pressure_min	float	Minimum pressure in Pa for the training set.
feature_importance_analysis	bool	Whether to perform feature importance analysis.
save_train_set	bool	Whether to save the training set to a .npz file.
save_test_set	bool	Whether to save the test set to a .npz file.
plot_include_train_set	bool	Whether to include the training set in plots.
il_species	list[str]	List of ionic liquid species to include in the model (e.g., ['cation', 'anion']).
il_descr_type	list[str]	List of types of molecular descriptors to use for model input.
split_by_mof_col_name	str	Column name for splitting the dataset by MOF.
split_by_mof	bool	Whether to split the data by MOF or randomly.
transform_01	bool	Whether to transform the target property to a 0-1 scale.
model_type	str	Type of model to use for training (e.g., 'catboost', 'lasso', 'mlp', 'xgboost', 'lightgbm').
tl	bool	Whether to use transfer learning.
include_fr5_data	bool	Whether to include FR5 experimental data in the model.
init_model_path	Optional[str]	Path of the initial model, used when tl=True.
fr5_ils	list[str]	List of ionic liquids to include from the FR5 dataset.
bo_conv	bool	Whether to use Bayesian optimization for conversion.
latent_descriptor	bool	Whether to use latent descriptors for the model.

Methods:

Name	Description
from_json	Loads a Config object from a JSON file.

Attributes

prop class-attribute instance-attribute

prop: str = 'conv'

prop_str class-attribute instance-attribute

prop_str: str = ''

prop_unit class-attribute instance-attribute

prop_unit: str = ''

prop_log class-attribute instance-attribute

prop_log: bool = False

output_folder class-attribute instance-attribute

output_folder: str = ''

db_path class-attribute instance-attribute

db_path: str = '../../../examples/reaction_analysis/database/fr5_init_reaction_data_20250506.db'

db_type class-attribute instance-attribute

db_type: str = 'experimental'

y_col_id class-attribute instance-attribute

y_col_id: int = 1

model_params_path class-attribute instance-attribute

model_params_path: str = '../../../examples/mof_properties/co2_uptake/best_params.json'

opt_model class-attribute instance-attribute

opt_model: bool = False

optuna_params class-attribute instance-attribute

optuna_params: dict[str, Any] = field(default_factory=dict)

opt_ntrials class-attribute instance-attribute

opt_ntrials: int = 100

opt_nsplits class-attribute instance-attribute

opt_nsplits: int = 5

cross_valid_nsplits class-attribute instance-attribute

cross_valid_nsplits: int = 5

model_train_size class-attribute instance-attribute

model_train_size: float = 0.8

model_test_size class-attribute instance-attribute

model_test_size: float = 0.2

model_early_stopping_rounds class-attribute instance-attribute

model_early_stopping_rounds: int = 50

pressure_max class-attribute instance-attribute

pressure_max: float = 10000000000.0

pressure_min class-attribute instance-attribute

pressure_min: float = 0.1

feature_importance_analysis class-attribute instance-attribute

feature_importance_analysis: bool = False

save_train_set class-attribute instance-attribute

save_train_set: bool = False

save_test_set class-attribute instance-attribute

save_test_set: bool = False

plot_include_train_set class-attribute instance-attribute

plot_include_train_set: bool = False

il_species class-attribute instance-attribute

il_species: list[str] = field(default_factory=lambda: ['cation', 'anion'])

il_descr_type class-attribute instance-attribute

il_descr_type: list[str] = field(default_factory=lambda: ['mordred', 'rdkit', 'morgan', 'maccs'])

split_by_mof_col_name class-attribute instance-attribute

split_by_mof_col_name: str = 'mof_name'

split_by_mof class-attribute instance-attribute

split_by_mof: bool = False

transform_01 class-attribute instance-attribute

transform_01: bool = False

model_type class-attribute instance-attribute

model_type: str = 'catboost'

tl class-attribute instance-attribute

tl: bool = False

include_fr5_data class-attribute instance-attribute

include_fr5_data: bool = False

init_model_path class-attribute instance-attribute

init_model_path: str | None = None

fr5_ils class-attribute instance-attribute

fr5_ils: list[str] = field(default_factory=list)

bo_conv class-attribute instance-attribute

bo_conv: bool = False

latent_descriptor class-attribute instance-attribute

latent_descriptor: bool = False

Functions

from_json staticmethod

from_json(path: str | Path) -> Config

Loads a Config object from a JSON file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the JSON file containing configuration parameters.	required

Returns:

Name	Type	Description
Config	Config	An instance of the Config class populated with parameters from the JSON file.

Functions

data_splits

data_splits(df: DataFrame, y_col_id: int, train_size: float, test_size: float, group_split=False, split_col_name='mof_name') -> tuple

Splits the data into training and testing sets.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the data.	required
y_col_id	int	Index of the column containing the target variable.	required
train_size	float	Proportion of the data to include in the training set.	required
test_size	float	Proportion of the data to include in the testing set.	required
group_split	bool	If True, the data will be split by groups (e.g., MOFs) so a group in the test set won't appear in the training set. Defaults to False.	False
split_col_name	str	Name of the column to use for grouping when group_split is True. Defaults to "mof_name".	'mof_name'

Returns:

Name	Type	Description
tuple	tuple	Tuple containing the training and testing sets (X_train, X_test, y_train, y_test).

save_cv_errors_to_file

save_cv_errors_to_file(file_path: str, prop: str, results: list[list[list[float]]], log: bool = False) -> None

Saves errors from k-fold cross-validation to a file.

Parameters:

Name	Type	Description	Default
file_path	str	Path to the output file.	required
prop	str	Property name (e.g., "viscosity", "density", "co2_solubility", "co2_uptake").	required
results	list[list[list[float]]]	Results from k-fold cross-validation.	required
log	bool	Whether to apply log transformation. Defaults to False.	False

save_errors_to_file

save_errors_to_file(file_path: str, prop: str, y_ref: list[float] | NDArray[Any], y_pred: list[float] | NDArray[Any], log: bool = False, set_type: str = 'test', sd: list[float] | NDArray[Any] | None = None) -> None

Saves errors from a single model to a file.

Parameters:

Name	Type	Description	Default
file_path	str	Path to the output file.	required
prop	str	Property name (e.g., "viscosity", "density", "co2_solubility", "co2_uptake").	required
y_ref	list[float] | NDArray[Any]	Reference property values.	required
y_pred	list[float] | NDArray[Any]	Predicted property values.	required
log	bool	Whether to apply log transformation. Defaults to False.	False
set_type	str	Type of set ("train", "test", or "valid"). Defaults to "test".	'test'

feature_importance_analysis

feature_importance_analysis(model: Any, X_train: NDArray[Any], y_train: NDArray[Any], feature_names: list[str], output_path: str, save_to_csv: bool = True, plotting: bool = True, plot_output_path: str = '', model_type: str = 'catboost') -> DataFrame

Analyzes feature importance using the trained model. Supports CatBoostRegressor and models with feature_importances_ attribute.

Parameters:

Name	Type	Description	Default
model	Any	The trained model.	required
X_train	NDArray[Any]	The training data used for the model.	required
y_train	NDArray[Any]	The target values for the training data.	required
feature_names	list[str]	List of feature names corresponding to the columns in X_train.	required
output_path	str	Path to save the feature importance results.	required
save_to_csv	bool	Whether to save the feature importance to a CSV file. Defaults to True.	True
plotting	bool	Whether to plot the feature importance. Defaults to True.	True
plot_output_path	str	Path to save the plot of feature importance. Defaults to "".	''
model_type	str	Type of model. Defaults to "catboost".	'catboost'

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame containing feature names and their importance scores.

fit_model

fit_model(X_train: NDArray[Any], y_train: NDArray[Any], params: dict[str, Any], config: Any, path_out: str, loss_function='RMSE', save_model: bool = True, is_transf_learn: bool = False, cv: int | None = None) -> Any

Trains a single machine learning model (e.g., CatBoost, Lasso, MLP, XGBoost, LightGBM).

Parameters:

Name	Type	Description	Default
X_train	NDArray[Any]	Input feature values for training.	required
y_train	NDArray[Any]	Output/target values for training.	required
params	Dict[str, Any]	Model parameters.	required
config	Any	Configuration object containing all settings.	required
path_out	str	Path to the output folder.	required
loss_function	str	Loss function for the model. Defaults to "RMSE".	'RMSE'
save_model	bool	Whether to save the model. Defaults to True.	True
is_transf_learn	bool	Whether to perform transfer learning. Defaults to False.	False
cv	Optional[int]	Cross-validation split id for saving the model. Defaults to None.	None

Returns:

Name	Type	Description
Any	Any	Trained model instance.

kfold_prediction

kfold_prediction(X: list[NDArray[Any]], y: list[NDArray[Any]], params: dict[str, Any], config: Any, path_out_model: str, save_models: bool = False, mof_names_grouping: list[str] | None = None, is_transf_learn: bool = False) -> list[list[list[float]]]

Performs k-fold cross-validation with CatBoostRegressor or other models to obtain statistical results.

Parameters:

Name	Type	Description	Default
X	list[NDArray[Any]]	Input feature values.	required
y	list[NDArray[Any]]	Output/target values.	required
params	Dict[str, Any]	Model parameters.	required
config	Any	Configuration object containing all settings.	required
path_out_model	str	Path to the output folder for models.	required
save_models	bool	Whether to save models. Defaults to False.	False
mof_names_grouping	Optional[List[str]]	List of MOF names for grouping (for grouped CV). Defaults to None.	None
is_transf_learn	bool	Whether to perform transfer learning. Defaults to False.	False

Returns:

Type	Description
list[list[list[float]]]	list[list[list[float]]]: List of vectors containing reference and predicted values for the test sets of ensemble of nsplits models.

optimise_model

optimise_model(X_train: NDArray[Any], y_train: NDArray[Any], search_space: Dict[str, Dict[str, Any]], nsplits: int, ntrials: int, model_type: str = 'catboost') -> Dict[str, Any]

Optimizes model hyperparameters using Optuna with k-fold cross-validation.

Parameters:

Name	Type	Description	Default
X_train	NDArray[Any]	Input values of training set.	required
y_train	NDArray[Any]	Output values of training set.	required
search_space	Dict[str, Dict[str, Any]]	Ranges of parameters for optimization.	required
nsplits	int	Number of splits for cross-validation.	required
ntrials	int	Number of trials for Optuna optimization.	required
model_type	str	Type of model to optimize. Defaults to "catboost".	'catboost'

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Best parameters found by Optuna optimization.

plot_results

plot_results(y_test: list[float] | NDArray[Any], y_pred: list[float] | NDArray[Any], axis_label_prop: str = '', axis_label_unit: str = '', prop_cur: str = 'Property', prop_log: bool = False, path_fig: str = '.', y_train: list[float] | NDArray[Any] | None = None, y_train_pred: list[float] | NDArray[Any] | None = None, catalyst_types: list[str] | None = None, ids_test: list[int] | None = None, sd_test: list[float] | NDArray[Any] | None = None, sd_train: list[float] | NDArray[Any] | None = None, show_error_bars: bool = True) -> None

Plots the results of the model, including reference vs. predicted values and optional training/catalyst information.

Parameters:

Name	Type	Description	Default
y_test	list[float] | NDArray[Any]	Reference values.	required
y_pred	list[float] | NDArray[Any]	Predicted values.	required
axis_label_prop	str	Property name for the plot axis label.	''
axis_label_unit	str	Property unit string for the plot axis label.	''
prop_cur	str	Property name (e.g., "viscosity", "density", etc.).	'Property'
prop_log	bool	Whether to apply a logarithmic transform to the target property.	False
path_fig	str	Path to the output figure.	'.'
y_train	list[float] | NDArray[Any] | None	Training set reference values. Defaults to None.	None
y_train_pred	list[float] | NDArray[Any] | None	Training set predicted values. Defaults to None.	None
catalyst_types	list[str] | None	List of catalyst types for the test set. Defaults to None.	None
ids_test	list[int] | None	List of test set IDs. Defaults to None.	None
sd_test	list[float] | NDArray[Any] | None	Standard deviations for test set predictions. Defaults to None.	None
sd_train	list[float] | NDArray[Any] | None	Standard deviations for training set predictions. Defaults to None.	None
show_error_bars	bool	Whether to show error bars for the predictions.	True

convert_back_from_01

convert_back_from_01(y_logit)

Maps logit prediction back to range (0, 100).

convert_to_01

convert_to_01(y)

Maps y in (0, 100) to (-inf, inf).

get_data

get_data(db_path: str, il_descr_type: list[str] | None = None, il_species: list[str] | None = None, descr_type: list[str] | None = None, species: list[str] | None = None, prop: str = 'conversion_perc', include_fr5_data: bool = False, fr5_data_only: bool = False, const_time_h: float | None = None, const_temp_K: float | None = None, const_pressure_Pa: float | None = None, const_il_mmol_substr_mmol: float | None = None, const_mof_mg_substr_mmol: float | None = None, const_model_pred: bool = False, const_model_pred_conv: bool = False, fr5_ils: list[str] = [], group_by: str | None = None) -> tuple[DataFrame, DataFrame]

Loads reference values of the chosen property together with descriptors and experimental conditions.

Parameters:

Name	Type	Description	Default
db_path	str	Path to the database.	required
descr_type	list[str]	List of descriptor types. Supported: "mordred", "rdkit", "morgan", "maccs".	None
species	list[str]	List of species for generating descriptors. Use "cat" for cation, "an" for anion.	None
prop	str	Property name. Can be "conversion_perc". Defaults to "conversion_perc".	'conversion_perc'
include_fr5_data	bool	Whether to include FR5 data. Defaults to False.	False
fr5_data_only	bool	Whether to use only FR5 data. Defaults to False.	False
const_time_h	Optional[float]	If provided, filter data to this constant time (in hours). Defaults to None.	None
const_temp_K	Optional[float]	If provided, filter data to this constant temperature (in Kelvin). Defaults to None.	None
const_pressure_Pa	Optional[float]	If provided, filter data to this constant pressure (in Pascal). Defaults to None.	None
const_il_mmol_substr_mmol	Optional[float]	If provided, filter data to this constant IL/substrate ratio. Defaults to None.	None
const_mof_mg_substr_mmol	Optional[float]	If provided, filter data to this constant MOF/substrate ratio. Defaults to None.	None
const_model_pred	bool	If True, include model predictions for ILs and MOFs. Defaults to False.	False
const_model_pred_conv	bool	If True, include model predictions for conversion. Defaults to False.	False
fr5_ils	list[str]	List of FR5 ionic liquids to include. Defaults to [].	[]
group_by	Optional[str]	If provided, group data by this column. Defaults to None.	None

Returns:

Type	Description
tuple[DataFrame, DataFrame]	tuple[pd.DataFrame, pd.DataFrame]: - DataFrame with the selected data (descriptors/features). - DataFrame with experimental conditions or additional information (labels).

get_data_latent

get_data_latent(db_path: str, prop: str = 'conversion') -> tuple[DataFrame, DataFrame]

Loads experimental data (experimental conditions) together with latent descriptors.

Parameters:

Name	Type	Description	Default
db_path	str	Path to the database.	required
prop	str	Property name. Can be "conversion". Defaults to "conversion".	'conversion'

Returns:

Type	Description
tuple[DataFrame, DataFrame]	tuple[pd.DataFrame, pd.DataFrame]: - DataFrame with the selected data (descriptors/features). - DataFrame with experimental conditions or additional information (labels).

prediction_run

prediction_run(config_path: str) -> None

Trains a reaction analysis property prediction model using the specified configuration file.

Parameters:

Name	Type	Description	Default
config_path	str	Path to the config JSON file.	required

Returns:

Type	Description
None	None

model_training_pipeline

model_training_pipeline(config: Config, is_transf_learn: bool) -> None

Trains a reaction analysis property prediction model, with optional transfer learning.

Parameters:

Name	Type	Description	Default
config	Config	Configuration object containing all settings.	required
is_transf_learn	bool	Whether to perform transfer learning on higher fidelity data.	required

Returns:

Type	Description
None	None