Skip to content

Add examples to train-test split functions in various splitters #502

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
j-adamczyk merged 4 commits into from
Oct 31, 2025
Merged

Add examples to train-test split functions in various splitters #502

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a148b7f
Add examples to train-test split functions in various splitters
mjste Oct 28, 2025
46d8c42
Fix formatting of references in maxmin_split.py documentation
mjste Oct 28, 2025
727cadc
Remove unnecessarry lines, fix verbosity issue
mjste Oct 30, 2025
6bb0503
Simplify examples
j-adamczyk Oct 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions skfp/model_selection/splitters/butina_split.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,16 @@ def butina_train_test_split(
.. [6] `Leland McInnes
"PyNNDescent for fast Approximate Nearest Neighbors"
<https://pynndescent.readthedocs.io/en/latest/>`_

Examples
--------
>>> from skfp.model_selection.splitters import butina_train_test_split
>>> smiles = ['CCO', 'CCN', 'CCC', 'CCCl', 'CCBr', 'CCI', 'CCF', 'CC=O']
>>> train_smiles, test_smiles = butina_train_test_split(smiles, train_size=0.75, test_size=0.25)
>>> print('Train SMILES:', train_smiles)
Train SMILES: ['CCBr', 'CCI', 'CCF', 'CC=O', 'CCO', 'CCC']
>>> print('Test SMILES:', test_smiles)
Test SMILES: ['CCN', 'CCCl']
"""
train_size, test_size = validate_train_test_split_sizes(
train_size, test_size, len(data)
Expand Down Expand Up @@ -336,6 +346,20 @@ def butina_train_valid_test_split(
.. [6] `Leland McInnes
"PyNNDescent for fast Approximate Nearest Neighbors"
<https://pynndescent.readthedocs.io/en/latest/>`_

Examples
--------
>>> from skfp.model_selection.splitters import butina_train_valid_test_split
>>> smiles = ['CCO', 'CCN', 'CCC', 'CCCl', 'CCBr', 'CCI', 'CCF', 'CC=O']
>>> train_smiles, valid_smiles, test_smiles = butina_train_valid_test_split(
... smiles, train_size=0.5, valid_size=0.25, test_size=0.25
... )
>>> print('Train SMILES:', train_smiles)
Train SMILES: ['CCF', 'CC=O', 'CCO', 'CCC']
>>> print('Valid SMILES:', valid_smiles)
Valid SMILES: ['CCBr', 'CCI']
>>> print('Test SMILES:', test_smiles)
Test SMILES: ['CCN', 'CCCl']
"""
train_size, valid_size, test_size = validate_train_valid_test_split_sizes(
train_size, valid_size, test_size, len(data)
Expand Down
130 changes: 122 additions & 8 deletions skfp/model_selection/splitters/maxmin_split.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,18 +101,39 @@ def maxmin_train_test_split(
.. [1] `Mark Ashton et al.
"Identification of Diverse Database Subsets using Property-Based and Fragment-Based Molecular Descriptions"
Quant. Struct.-Act. Relat., 21: 598-604
<https://onlinelibrary.wiley.com/doi/10.1002/qsar.200290002>_`
<https://onlinelibrary.wiley.com/doi/10.1002/qsar.200290002>`_

.. [2] `Roger Sayle
"Improved RDKit implementation"
<https://github.com/rdkit/UGM_2017/blob/master/Presentations/Sayle_RDKitDiversity_Berlin17.pdf>_`
<https://github.com/rdkit/UGM_2017/blob/master/Presentations/Sayle_RDKitDiversity_Berlin17.pdf>`_

.. [3] `Tim Dudgeon
"Revisiting the MaxMinPicker"
<https://rdkit.org/docs/cppapi/classRDPickers_1_1MaxMinPicker.html>_`
<https://rdkit.org/docs/cppapi/classRDPickers_1_1MaxMinPicker.html>`_

.. [4] `Squonk - RDKit MaxMin Picker
<https://squonk.it/docs/cells/RDKit%20MaxMin%20Picker>_`
<https://squonk.it/docs/cells/RDKit%20MaxMin%20Picker>`_

Examples
--------
>>> from skfp.model_selection.splitters import maxmin_train_test_split
>>> smiles = ['CCO', 'CCN', 'CCC', 'CCCl', 'CCBr', 'CCI', 'CCF', 'CC=O']
>>> train_smiles, test_smiles = maxmin_train_test_split(
... smiles, train_size=0.75, test_size=0.25, random_state=42
... )
>>> print('Train SMILES:', train_smiles)
Train SMILES: ['CCO', 'CCN', 'CCCl', 'CCBr', 'CCI', 'CCF']
>>> print('Test SMILES:', test_smiles)
Test SMILES: ['CCC', 'CC=O']
>>> additional_names = ['ethanol', 'ethylamine', 'propane', 'chloroethane',
... 'bromoethane', 'iodoethane', 'fluoroethane', 'acetaldehyde']
>>> train_smiles, test_smiles, train_names, test_names = maxmin_train_test_split(
... smiles, additional_names, train_size=0.75, test_size=0.25, random_state=42
... )
>>> print('Train Names:', train_names)
Train Names: ['ethanol', 'ethylamine', 'chloroethane', 'bromoethane', 'iodoethane', 'fluoroethane']
>>> print('Test Names:', test_names)
Test Names: ['propane', 'acetaldehyde']
"""
data_size = len(data)
train_size, test_size = validate_train_test_split_sizes(
Expand Down Expand Up @@ -249,18 +270,46 @@ def maxmin_train_valid_test_split(
.. [1] `Mark Ashton et al.
"Identification of Diverse Database Subsets using Property-Based and Fragment-Based Molecular Descriptions"
Quant. Struct.-Act. Relat., 21: 598-604
<https://onlinelibrary.wiley.com/doi/10.1002/qsar.200290002>_`
<https://onlinelibrary.wiley.com/doi/10.1002/qsar.200290002>`_

.. [2] `Roger Sayle
"Improved RDKit implementation"
<https://github.com/rdkit/UGM_2017/blob/master/Presentations/Sayle_RDKitDiversity_Berlin17.pdf>_`
<https://github.com/rdkit/UGM_2017/blob/master/Presentations/Sayle_RDKitDiversity_Berlin17.pdf>`_

.. [3] `Tim Dudgeon
"Revisiting the MaxMinPicker"
<https://rdkit.org/docs/cppapi/classRDPickers_1_1MaxMinPicker.html>_`
<https://rdkit.org/docs/cppapi/classRDPickers_1_1MaxMinPicker.html>`_

.. [4] `Squonk - RDKit MaxMin Picker
<https://squonk.it/docs/cells/RDKit%20MaxMin%20Picker>_`
<https://squonk.it/docs/cells/RDKit%20MaxMin%20Picker>`_

Examples
--------
>>> from skfp.model_selection.splitters import maxmin_train_valid_test_split
>>> smiles = ['CCO', 'CCN', 'CCC', 'CCCl', 'CCBr', 'CCI', 'CCF', 'CC=O']
>>> train_smiles, valid_smiles, test_smiles = maxmin_train_valid_test_split(
... smiles, train_size=0.5, valid_size=0.25, test_size=0.25, random_state=42
... )
>>> print('Train SMILES:', train_smiles)
Train SMILES: ['CCCl', 'CCBr', 'CCI', 'CCF']
>>> print('Valid SMILES:', valid_smiles)
Valid SMILES: ['CCO', 'CCN']
>>> print('Test SMILES:', test_smiles)
Test SMILES: ['CCC', 'CC=O']
>>> additional_names = ['ethanol', 'ethylamine', 'propane', 'chloroethane',
... 'bromoethane', 'iodoethane', 'fluoroethane', 'acetaldehyde']
>>> train_smiles, valid_smiles, test_smiles, train_names, valid_names, test_names = (
... maxmin_train_valid_test_split(
... smiles, additional_names,
... train_size=0.5, valid_size=0.25, test_size=0.25, random_state=42
... )
... )
>>> print('Train Names:', train_names)
Train Names: ['chloroethane', 'bromoethane', 'iodoethane', 'fluoroethane']
>>> print('Valid Names:', valid_names)
Valid Names: ['ethanol', 'ethylamine']
>>> print('Test Names:', test_names)
Test Names: ['propane', 'acetaldehyde']
"""
data_size = len(data)
train_size, valid_size, test_size = validate_train_valid_test_split_sizes(
Expand Down Expand Up @@ -405,6 +454,34 @@ def maxmin_stratified_train_test_split(
See Also
--------
:func:`maxmin_train_test_split` : Regular MaxMin split.

Examples
--------
>>> from skfp.model_selection.splitters import maxmin_stratified_train_test_split
>>> smiles = ['CCO', 'CCN', 'CCC', 'CCCl', 'CCBr', 'CCI', 'CCF', 'CC=O']
>>> labels = [0, 0, 1, 1, 0, 1, 0, 1]
>>> train_smiles, test_smiles, train_labels, test_labels = maxmin_stratified_train_test_split(
... smiles, labels, train_size=0.75, test_size=0.25, random_state=42
... )
>>> print('Train SMILES:', train_smiles)
Train SMILES: ['CCO', 'CCBr', 'CCF', 'CCC', 'CCI', 'CC=O']
>>> print('Test SMILES:', test_smiles)
Test SMILES: ['CCN', 'CCCl']
>>> print('Train Labels:', train_labels)
Train Labels: [0 0 0 1 1 1]
>>> print('Test Labels:', test_labels)
Test Labels: [0 1]
>>> additional_names = ['ethanol', 'ethylamine', 'propane', 'chloroethane',
... 'bromoethane', 'iodoethane', 'fluoroethane', 'acetaldehyde']
>>> train_smiles, test_smiles, train_labels, test_labels, train_names, test_names = (
... maxmin_stratified_train_test_split(
... smiles, labels, additional_names, train_size=0.75, test_size=0.25, random_state=42
... )
... )
>>> print('Train Names:', train_names)
Train Names: ['ethanol', 'bromoethane', 'fluoroethane', 'propane', 'iodoethane', 'acetaldehyde']
>>> print('Test Names:', test_names)
Test Names: ['ethylamine', 'chloroethane']
"""
data_arr = np.array(data)
labels = np.array(labels, dtype=int)
Expand Down Expand Up @@ -561,6 +638,43 @@ def maxmin_stratified_train_valid_test_split(
See Also
--------
:func:`maxmin_train_valid_test_split` : Regular MaxMin split.

Examples
--------
>>> from skfp.model_selection.splitters import maxmin_stratified_train_valid_test_split
>>> smiles = ['CCO', 'CCN', 'CCC', 'CCCl', 'CCBr', 'CCI', 'CCF', 'CC=O']
>>> labels = [0, 0, 1, 1, 0, 1, 0, 1]
>>> train_smiles, valid_smiles, test_smiles, train_labels, valid_labels, test_labels = (
... maxmin_stratified_train_valid_test_split(
... smiles, labels, train_size=0.5, valid_size=0.25, test_size=0.25, random_state=42
... )
... )
>>> print('Train SMILES:', train_smiles)
Train SMILES: ['CCBr', 'CCF', 'CCC', 'CCI']
>>> print('Valid SMILES:', valid_smiles)
Valid SMILES: ['CCO', 'CC=O']
>>> print('Test SMILES:', test_smiles)
Test SMILES: ['CCN', 'CCCl']
>>> print('Train Labels:', train_labels)
Train Labels: [0 0 1 1]
>>> print('Valid Labels:', valid_labels)
Valid Labels: [0 1]
>>> print('Test Labels:', test_labels)
Test Labels: [0 1]
>>> additional_names = ['ethanol', 'ethylamine', 'propane', 'chloroethane',
... 'bromoethane', 'iodoethane', 'fluoroethane', 'acetaldehyde']
>>> res = maxmin_stratified_train_valid_test_split(
... smiles, labels, additional_names, train_size=0.5, valid_size=0.25, test_size=0.25, random_state=42
... )
>>> len(res)
9
>>> train_smiles, valid_smiles, test_smiles, train_labels, valid_labels, test_labels, train_names, valid_names, test_names = res
>>> print('Train Names:', train_names)
Train Names: ['bromoethane', 'fluoroethane', 'propane', 'iodoethane']
>>> print('Valid Names:', valid_names)
Valid Names: ['ethanol', 'acetaldehyde']
>>> print('Test Names:', test_names)
Test Names: ['ethylamine', 'chloroethane']
"""
data_arr = np.array(data)
labels = np.array(labels, dtype=int)
Expand Down
42 changes: 42 additions & 0 deletions skfp/model_selection/splitters/pubchem_split.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,26 @@ def pubchem_train_test_split(
"An update on PUG-REST: RESTful interface for programmatic access to PubChem."
Nucleic Acids Res. 2018 Jul 2;46(W1):W563-W570.
<https://doi.org/10.1093/nar/gky294>`_

Examples
--------
>>> from skfp.model_selection.splitters import pubchem_train_test_split
>>> smiles = ['CCO', 'CCN', 'CCC', 'CCCl', 'CCBr', 'CCI', 'CCF', 'CC=O']
>>> train_smiles, test_smiles = pubchem_train_test_split(
... smiles, train_size=0.75, test_size=0.25, n_jobs=1, n_retries=1, verbose=0
... )
CCO
CCN
CCC
CCCl
CCBr
CCI
CCF
CC=O
>>> print('Train SMILES:', train_smiles)
Train SMILES: ['CCCl', 'CCI', 'CCO', 'CCN', 'CCBr', 'CCC']
>>> print('Test SMILES:', test_smiles)
Test SMILES: ['CC=O', 'CCF']
"""
years = _get_pubchem_years(data, n_jobs, n_retries, verbose)

Expand Down Expand Up @@ -296,6 +316,28 @@ def pubchem_train_valid_test_split(
"An update on PUG-REST: RESTful interface for programmatic access to PubChem."
Nucleic Acids Res. 2018 Jul 2;46(W1):W563-W570.
<https://doi.org/10.1093/nar/gky294>`_

Examples
--------
>>> from skfp.model_selection.splitters import pubchem_train_valid_test_split
>>> smiles = ['CCO', 'CCN', 'CCC', 'CCCl', 'CCBr', 'CCI', 'CCF', 'CC=O']
>>> train_smiles, valid_smiles, test_smiles = pubchem_train_valid_test_split(
... smiles, train_size=0.5, valid_size=0.25, test_size=0.25, n_jobs=1, n_retries=1, verbose=0
... )
CCO
CCN
CCC
CCCl
CCBr
CCI
CCF
CC=O
>>> print('Train SMILES:', train_smiles)
Train SMILES: ['CCCl', 'CCI', 'CCO', 'CCN']
>>> print('Valid SMILES:', valid_smiles)
Valid SMILES: ['CCBr', 'CCC']
>>> print('Test SMILES:', test_smiles)
Test SMILES: ['CC=O', 'CCF']
"""
years = _get_pubchem_years(data, n_jobs, n_retries, verbose)

Expand Down
26 changes: 26 additions & 0 deletions skfp/model_selection/splitters/randomized_scaffold_split.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,18 @@ def randomized_scaffold_train_test_split(
"Does GNN Pretraining Help Molecular Representation?"
Advances in Neural Information Processing Systems 35 (NeurIPS 2022).
<https://proceedings.neurips.cc/paper_files/paper/2022/hash/4ec360efb3f52643ac43fda570ec0118-Abstract-Conference.html>`_

Examples
--------
>>> from skfp.model_selection.splitters import randomized_scaffold_train_test_split
>>> smiles = ['c1ccccc1', 'C1CCCCC1', 'CCO', 'CCN', 'CCCl', 'CCBr', 'CCI', 'CCF']
>>> train_smiles, test_smiles = randomized_scaffold_train_test_split(
... smiles, train_size=6, test_size=2, random_state=42
... )
>>> print('Train SMILES:', train_smiles)
Train SMILES: ['C1CCCCC1', 'c1ccccc1']
>>> print('Test SMILES:', test_smiles)
Test SMILES: ['CCO', 'CCN', 'CCCl', 'CCBr', 'CCI', 'CCF']
"""
train_size, test_size = validate_train_test_split_sizes(
train_size, test_size, len(data)
Expand Down Expand Up @@ -289,6 +301,20 @@ def randomized_scaffold_train_valid_test_split(
"Does GNN Pretraining Help Molecular Representation?"
Advances in Neural Information Processing Systems 35 (NeurIPS 2022).
<https://proceedings.neurips.cc/paper_files/paper/2022/hash/4ec360efb3f52643ac43fda570ec0118-Abstract-Conference.html>`_

Examples
--------
>>> from skfp.model_selection.splitters import randomized_scaffold_train_valid_test_split
>>> smiles = ['c1ccccc1', 'C1CCCCC1', 'CCO', 'CCN', 'CCCl', 'CCBr', 'CCI', 'CCF']
>>> train_smiles, valid_smiles, test_smiles = randomized_scaffold_train_valid_test_split(
... smiles, train_size=6, valid_size=1, test_size=1, random_state=42
... )
>>> print('Train SMILES:', train_smiles)
Train SMILES: ['c1ccccc1']
>>> print('Valid SMILES:', valid_smiles)
Valid SMILES: ['C1CCCCC1']
>>> print('Test SMILES:', test_smiles)
Test SMILES: ['CCO', 'CCN', 'CCCl', 'CCBr', 'CCI', 'CCF']
"""
train_size, valid_size, test_size = validate_train_valid_test_split_sizes(
train_size, valid_size, test_size, len(data)
Expand Down
24 changes: 24 additions & 0 deletions skfp/model_selection/splitters/scaffold_split.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,16 @@ def scaffold_train_test_split(

.. [3] ` Bemis-Murcko scaffolds and their variants
<https://github.com/rdkit/rdkit/discussions/6844>`_

Examples
--------
>>> from skfp.model_selection.splitters import scaffold_train_test_split
>>> smiles = ['c1ccccc1', 'C1CCCCC1', 'CCO', 'CCN', 'CCCl', 'CCBr', 'CCI', 'CCF']
>>> train_smiles, test_smiles = scaffold_train_test_split(smiles, train_size=6, test_size=2)
>>> print('Train SMILES:', train_smiles)
Train SMILES: ['CCO', 'CCN', 'CCCl', 'CCBr', 'CCI', 'CCF']
>>> print('Test SMILES:', test_smiles)
Test SMILES: ['c1ccccc1', 'C1CCCCC1']
"""
train_size, test_size = validate_train_test_split_sizes(
train_size, test_size, len(data)
Expand Down Expand Up @@ -272,6 +282,20 @@ def scaffold_train_valid_test_split(

.. [3] ` Bemis-Murcko scaffolds and their variants
<https://github.com/rdkit/rdkit/discussions/6844>`_

Examples
--------
>>> from skfp.model_selection.splitters import scaffold_train_valid_test_split
>>> smiles = ['c1ccccc1', 'C1CCCCC1', 'CCO', 'CCN', 'CCCl', 'CCBr', 'CCI', 'CCF']
>>> train_smiles, valid_smiles, test_smiles = scaffold_train_valid_test_split(
... smiles, train_size=6, valid_size=1, test_size=1
... )
>>> print('Train SMILES:', train_smiles)
Train SMILES: ['CCO', 'CCN', 'CCCl', 'CCBr', 'CCI', 'CCF']
>>> print('Valid SMILES:', valid_smiles)
Valid SMILES: ['C1CCCCC1']
>>> print('Test SMILES:', test_smiles)
Test SMILES: ['c1ccccc1']
"""
train_size, valid_size, test_size = validate_train_valid_test_split_sizes(
train_size, valid_size, test_size, len(data)
Expand Down