BLOX2
BLOX2 is an improved version of BLOX1. The original implementations are available at https://github.com/tsudalab/BLOX.
Installation (with tutorials)
- Clone the repository
- Install uv: https://docs.astral.sh/uv/getting-started/installation/
- Restart the shell
- Move to the repository root (e.g., cd BLOX2)
- Run the following commands:
uv venv --python 3.11.11
source .venv/bin/activate
uv pip install blox2 numpy==2.4.1 pandas==2.3.3 matplotlib==3.10.8 scikit-learn==1.7.2 lightgbm==4.6.0 ipykernel==7.1.0
Installation (package only)
uv pip install blox2 numpy==2.4.1 pandas==2.3.3 matplotlib==3.10.8 scikit-learn==1.7.2 lightgbm==4.6.0
Tutorial
For a quick start, see example_usage.ipynb.
Parameters
SteinNoveltySelector
SteinNoveltySelector selects candidates based on Stein novelty in the predicted objective space.
It can optionally incorporate predictive uncertainty, input-space novelty, distributional predictions, and batch diversity penalties.
Required inputs
observed_features, observed_values, and unobserved_features can be provided as either np.ndarray or pd.DataFrame.
| Parameter | Description |
|---|---|
observed_features |
Feature values of already observed samples |
observed_values |
Objective/property values of already observed samples. |
unobserved_features |
Feature values of candidate samples to be selected from. |
predictor |
Predictor used to estimate objective/property values for unobserved candidates. |
Normalization and prediction settings
| Parameter | Default | Description |
|---|---|---|
normalize_features |
True |
Whether to normalize input features before prediction. |
value_normalization |
"before_pred" |
How objective/property values are normalized. Options: "before_pred", "after_pred", "mixed", or "disable". |
pred_clip |
None |
Valid ranges for predicted objective values, given as a list of (min, max) tuples. Cannot be used with value_normalization="before_pred". |
sigma |
1.0 |
Gaussian kernel bandwidth used for Stein novelty calculation in objective space. |
n_obs_samples |
None |
If the number of observed samples exceeds this value, a subset of observed samples is used for Stein novelty calculation. |
Uncertainty-aware selection
| Parameter | Default | Description |
|---|---|---|
use_uncertainty |
False |
Whether to combine predictive uncertainty with Stein novelty. |
uncertainty_ratio |
0.5 |
Weight of the uncertainty score. The final score is (1 - uncertainty_ratio) * standardized Stein novelty + uncertainty_ratio * standardized uncertainty. |
uncertainty_aggregation_type |
"mean" |
How to aggregate uncertainty over objectives/features. Options: "mean", "max", or "l2". |
print_uncertainty |
False |
Whether to print uncertainty information during selection. |
Input-space Stein novelty
| Parameter | Default | Description |
|---|---|---|
use_input_stein_novelty |
False |
Whether to also use Stein novelty in the input feature space. |
input_stein_novelty_ratio |
0.5 |
Weight of input-space Stein novelty. The final score is (1 - input_stein_novelty_ratio) * output-space Stein novelty + input_stein_novelty_ratio * input-space Stein novelty. |
input_stein_pca_dim |
None |
If set to a positive integer, PCA is applied to the processed input features before input-space Stein novelty or Stein-based batch penalty calculation. |
input_stein_sigma |
"auto" |
Gaussian kernel bandwidth for input-space Stein novelty. If "auto", the mean pairwise distance is used. |
input_stein_auto_n_samples |
10**5 |
Maximum number of sample pairs used to estimate the mean pairwise distance when input_stein_sigma="auto". |
Batch diversity penalty
| Parameter | Default | Description |
|---|---|---|
use_batch_penalty |
False |
Whether to penalize candidates that are too close to already selected candidates in the same batch. |
batch_penalty_ratio |
0.5 |
Weight of the batch penalty. The batch score is (1 - batch_penalty_ratio) * standardized base score - batch_penalty_ratio * standardized batch penalty. |
batch_penalty_type |
"stein" |
Type of batch penalty. Options: "stein", "distance", "simhash", or "simhash_min_hamming". |
batch_penalty_cutoff_ratio |
0.0 |
Skips batch-penalty calculation for low-scoring candidates within each chunk. |
batch_penalty_simhash_bits |
8 |
Number of SimHash bits used when batch_penalty_type is "simhash" or "simhash_min_hamming". Must be at most 64. |
Distributional prediction
| Parameter | Default | Description |
|---|---|---|
use_distribution |
False |
Whether to use predictive distributions from predictor.pred_samples(). |
distribution_pooling_type |
"mean" |
How to aggregate Stein novelty scores over predicted samples. Options: "mean" or "max". |
Misc
| Parameter | Default | Description |
|---|---|---|
chunk_size |
256 |
Number of candidates processed in one chunk during chunked Stein novelty calculation. |
verbose_plot_dir |
None |
If set, saves diagnostic plots of predicted values and selected candidates at each selection step. |
Predictor
Although LightGBMPredictor was mainly used in our experiments, BLOX2 is not limited to LightGBM. Any predictor can be used by implementing the Predictor class. The package also includes sklearn-based predictor implementations, such as RandomForestPredictor and SVRPredictor, although these implementations do not support uncertainty estimation. When using these predictors, the lightgbm dependency can be omitted.
License
The BLOX2 source code is licensed under the MIT License.
The files under data/ are provided for reproducibility and are not covered by the MIT License. See data/README.md for the corresponding attribution and license information.
-
Terayama, K. and Sumita, M. and Tamura, R. and Payne, D. T. and Chahal, M. K. and Ishihara, S. and Tsuda, K. (2020). Pushing property limits in materials discovery via boundless objective-free exploration. Chemical Science https://doi.org/10.1039/D0SC00982B ↩
1 maintainer
Metadata
1 maintainer
Release files for blox2 1.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| blox2-1.1.1.tar.gz | 25.9 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| blox2-1.1.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 55.9 kB
Release files / blox2-1.1.1.tar.gz
| Download URL | blox2-1.1.1.tar.gz |
|---|---|
| Size | 25.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9141a94834198a85b5d327c1d481d7e516315b0a3e762db59d369e3392b353dc
|
|
BLAKE2b-256 checksum How to use checksums |
8770b8970c57594e851319a91df36cf45b6488d66f612bc1e6985dfa9705e5be
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.11
|
Release files / blox2-1.1.1-py3-none-any.whl
| Download URL | blox2-1.1.1-py3-none-any.whl |
|---|---|
| Size | 30.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b5978a78f8ebd24712fd5d2356049e00eacf553b7c5eaae70d05a11e34aff640
|
|
BLAKE2b-256 checksum How to use checksums |
0e23525793a50f38b7624209d1f3ed5022be36f9245c0fbe7e3f3755f3a01412
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.11
|
Security for blox2 1.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
