### Install FastProp from Source

Source: https://github.com/jacksonburns/fastprop/blob/main/README.md

Install FastProp directly from GitHub or by cloning the repository and running a local installation. This method is useful for checking out specific branches or contributing to the project.

```bash
pip install https://github.com/JacksonBurns/fastprop.git@main
```

```bash
git clone https://github.com/JacksonBurns/fastprop.git
cd fastprop
pip install .
```

--------------------------------

### Install FastProp with Pip

Source: https://github.com/jacksonburns/fastprop/blob/main/README.md

Recommended installation method for FastProp using pip. Optional dependencies for hyperparameter optimization and SHAP analysis can be installed with package extras.

```bash
pip install fastprop
```

```bash
pip install fastprop[hopt]
```

```bash
pip install fastprop[shap]
```

```bash
pip install fastprop[shap,hopt]
```

--------------------------------

### Install Fastprop from Source

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

Installs fastprop from its GitHub repository, including optional dependencies for hyperparameter optimization and SHAP. This is useful when you need the latest features or want to contribute to the project. Ensure you have Git and pip installed.

```python
%%capture
%cd /content
# remove existing code, if it exists
!rm -rf fastprop || true
!git clone https://github.com/JacksonBurns/fastprop
%cd /content/fastprop
!pip install .[hopt,shap]
# for showing the repository layout
!sudo apt-get install tree
```

--------------------------------

### Load `polaris` Benchmark Data

Source: https://github.com/jacksonburns/fastprop/blob/main/examples/fastprop_polaris_classification_demo.ipynb

Loads a specified benchmark dataset from `polaris` and splits it into training and testing sets. Requires `polaris` to be installed and logged in.

```python
import polaris as po

benchmark = po.load_benchmark("polaris/pkis2-egfr-wt-c-1")
train, test = benchmark.get_train_test_split()
```

--------------------------------

### Direct Model Instantiation and Data Preparation

Source: https://context7.com/jacksonburns/fastprop/llms.txt

Instantiate the `fastprop` PyTorch Lightning module directly for custom training loops or fine-tuning. It handles feature/target scaling internally when scaling tensors are provided. This example shows synthetic data generation and splitting.

```python
import torch
from fastprop.model import fastprop, train_and_test
from fastprop.data import fastpropDataset, fastpropDataLoader, standard_scale, split

# --- Build synthetic dataset ---
n_samples, n_features, n_targets = 500, 947, 1
X = torch.randn(n_samples, n_features)
y = torch.randn(n_samples, n_targets)
smiles = [f"C{'C'*i}" for i in range(n_samples)]  # dummy SMILES for splitting

train_idx, val_idx, test_idx = split(smiles, random_seed=42, train_size=0.8, val_size=0.1, test_size=0.1)

```

--------------------------------

### Get Help for fastprop predict

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

Displays the help message for the `fastprop predict` command, outlining available arguments and options for making predictions.

```bash
!fastprop predict --help
```

--------------------------------

### Get Help for fastprop shap

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

Displays the help message for the `fastprop shap` command, detailing arguments for SHAP analysis, including checkpoint directory, cached descriptors, and importance threshold.

```bash
!fastprop shap --help
```

--------------------------------

### CSV Input for Benzene Properties

Source: https://github.com/jacksonburns/fastprop/blob/main/paper/paper.md

Example of input data in CSV format, specifying properties for benzene. This format is compatible with spreadsheet editors and is platform-independent.

```csv
compound,smiles,log_p,retention_index,boiling_point_c,acentric_factor
Benzene,C1=CC=CC=C1,2.04,979,80,0.21
```

--------------------------------

### CLI `fastprop shap`

Source: https://context7.com/jacksonburns/fastprop/llms.txt

Computes SHAP values using `shap.DeepExplainer`, saves beeswarm plots as PNG files. Requires `pip install fastprop[shap]`.

```APIDOC
## CLI `fastprop shap` — Feature importance analysis

`fastprop shap` computes SHAP (SHapley Additive exPlanations) values using `shap.DeepExplainer` across all model replicates and saves beeswarm plots as PNG files. Requires `pip install fastprop[shap]`.

```bash
fastprop shap \
  --checkpoints-dir ./lipo_output/fastprop_1700000000/checkpoints \
  --cached-descriptors ./lipo_output/cached_lipophilicity_optimized_*.csv \
  --descriptor-set optimized \
  --importance-threshold 0.75   # include features with SHAP ≥ 75% of the top feature

# Output: task_0_feature_importance_beeswarm.png
# Lookup descriptor meanings at:
# https://jacksonburns.github.io/mordred-community/descriptors.html
```
```

--------------------------------

### CLI: Compute SHAP values for feature importance

Source: https://context7.com/jacksonburns/fastprop/llms.txt

Use `fastprop shap` to compute SHAP values for feature importance analysis. It requires installing `fastprop[shap]` and can use cached descriptors. Features below a specified threshold are excluded from plotting.

```bash
fastprop shap \
  --checkpoints-dir ./lipo_output/fastprop_1700000000/checkpoints \
  --cached-descriptors ./lipo_output/cached_lipophilicity_optimized_*.csv \
  --descriptor-set optimized \
  --importance-threshold 0.75   # include features with SHAP ≥ 75% of the top feature

# Output: task_0_feature_importance_beeswarm.png
# Lookup descriptor meanings at:
# https://jacksonburns.github.io/mordred-community/descriptors.html
```

--------------------------------

### Initialize Fastprop DataLoaders

Source: https://github.com/jacksonburns/fastprop/blob/main/examples/fastprop_polaris_classification_demo.ipynb

Sets up data loaders for training, validation, and testing using Fastprop's DataLoader. Ensure descriptors and targets are correctly formatted.

```python
train_dataloader = fastpropDataLoader(TensorDataset(train_descriptors, train_targets), shuffle=True, batch_size=16)
val_dataloader = fastpropDataLoader(TensorDataset(val_descriptors, val_targets), batch_size=1024)
test_dataloader = fastpropDataLoader(TensorDataset(test_descriptors), batch_size=1024)
```

--------------------------------

### Show `fastprop train` command-line arguments

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

Execute `fastprop train --help` to display all available command-line options for training a model. This includes arguments for input files, target columns, caching, model architecture, and training parameters.

```python
!fastprop train --help
```

--------------------------------

### Set up PyTorch Lightning Trainer and Callbacks

Source: https://github.com/jacksonburns/fastprop/blob/main/examples/fastprop_polaris_classification_demo.ipynb

Configures a PyTorch Lightning Trainer with TensorBoard logging, early stopping based on validation AUROC, and model checkpointing to save the best model.

```python
from pathlib import Path

outdir = Path("demo_output")
```

```python
from pytorch_lightning import Trainer
from pytorch_lightning.loggers import TensorBoardLogger
from pytorch_lightning.callbacks import EarlyStopping, ModelCheckpoint


tensorboard_logger = TensorBoardLogger(
    outdir,
    name="tensorboard_logs",
    default_hp_metric=False,
)
callbacks = [
    EarlyStopping(
        monitor="validation_binary_auroc",
        mode="max",
        verbose=False,
        patience=5,
    ),
    ModelCheckpoint(
        monitor="validation_binary_auroc",
        save_top_k=1,
        mode="max",
        dirpath=outdir / "checkpoints",
    ),
]
trainer = Trainer(
    max_epochs=50,
    logger=tensorboard_logger,
    log_every_n_steps=1,
    enable_checkpointing=True,
    check_val_every_n_epoch=1,
    callbacks=callbacks,
)
```

--------------------------------

### Train Fastprop Model

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

Initiates the training process for a Fastprop model using a specified YAML configuration file. Ensure the configuration file is correctly set up with necessary parameters like SMILES column and target columns.

```bash
!fastprop train pah/pah.yml
```

--------------------------------

### Fastprop Configuration File (YAML)

Source: https://github.com/jacksonburns/fastprop/blob/main/paper/paper.md

A sample YAML configuration file for fastprop. This file specifies parameters for training, featurization, and preprocessing, such as input files, target columns, and model training settings.

```yaml
# pah.yml
# generic args
output_directory: pah
random_seed: 55
problem_type: regression
# featurization
input_file: pah/arockiaraj_pah_data.csv
target_columns: log_p
smiles_column: smiles
descriptor_set: all
# preprocessing
clamp_input: True
# training
number_repeats: 4
number_epochs: 100
batch_size: 64
patience: 15
train_size: 0.8
val_size: 0.1
test_size: 0.1
sampler: random
```

--------------------------------

### Setup Custom Pearson Correlation Metric

Source: https://github.com/jacksonburns/fastprop/blob/main/examples/fastprop_computational_adme_demo.ipynb

Adapts `torchmetrics.functional.regression.pearson_corrcoef` to create a custom scoring function `r_score` for regression tasks. This custom metric is then added to `fastprop`'s `SCORE_LOOKUP` dictionary.

```python
import torch
from fastprop.metrics import SCORE_LOOKUP
from torchmetrics.functional.regression import pearson_corrcoef


def r_score(truth: torch.Tensor, prediction: torch.Tensor, ignored: None, multitask: bool = False):
    return pearson_corrcoef(prediction, truth)


SCORE_LOOKUP["regression"] = (r_score,) + SCORE_LOOKUP["regression"]
```

--------------------------------

### Build Fastprop Data Loaders

Source: https://context7.com/jacksonburns/fastprop/llms.txt

Creates data loaders for training, validation, and testing using fastpropDataset and fastpropDataLoader. Training data is shuffled.

```python
train_dl = fastpropDataLoader(fastpropDataset(X[train_idx], y[train_idx]), shuffle=True)
val_dl   = fastpropDataLoader(fastpropDataset(X[val_idx],   y[val_idx]))
test_dl  = fastpropDataLoader(fastpropDataset(X[test_idx],  y[test_idx]))
```

--------------------------------

### Instantiate Fastprop Model

Source: https://context7.com/jacksonburns/fastprop/llms.txt

Instantiates a fastprop model with specified input, hidden, and readout sizes, along with learning rate and network layer configurations. Includes feature and target scaling parameters.

```python
model = fastprop(
    input_size=n_features,
    hidden_size=1800,
    readout_size=n_targets,
    num_tasks=n_targets,
    learning_rate=0.0001,
    fnn_layers=2,
    clamp_input=False,
    problem_type="regression",
    target_names=["logP"],
    feature_means=feat_means,
    feature_vars=feat_vars,
    target_means=tgt_means,
    target_vars=tgt_vars,
)
```

--------------------------------

### Prepare TeX File for arXiv Submission

Source: https://github.com/jacksonburns/fastprop/blob/main/paper/paper.md

This command prepares the TeX file for arXiv submission, outputting to a specified directory. Manual fixing of image filepaths may be required.

```bash
pandoc --citeproc -s paper.md -o paper.pdf --template default.latex \
    --pdf-engine=pdflatex --pdf-engine-opt=-output-directory=foo
```

--------------------------------

### Initialize Fastprop Model

Source: https://github.com/jacksonburns/fastprop/blob/main/examples/fastprop_polaris_classification_demo.ipynb

Initializes a Fastprop model for binary classification. Key parameters include problem type, target names, input clamping (winsorization), network architecture (fnn_layers, hidden_size), feature statistics (feature_means, feature_vars), and learning rate.

```python
model = fastprop(
    problem_type="binary",
    target_names=list(benchmark.target_cols),
    clamp_input=True,  # winsorization
    fnn_layers=2,
    hidden_size=1_800,
    feature_means=feature_means,
    feature_vars=feature_vars,
    learning_rate=0.00001,
)
```

--------------------------------

### Create Data Loaders and Fastprop Models

Source: https://github.com/jacksonburns/fastprop/blob/main/examples/fastprop_computational_adme_demo.ipynb

This function handles data scaling, dataloader preparation, and model instantiation. It creates both a linear baseline and a feed-forward neural network model. Ensure data is pre-split into train, validation, and test sets before calling.

```python
from fastprop.model import fastprop
from fastprop.data import fastpropDataLoader, fastpropDataset, standard_scale


def create_loaders_and_models(descriptors, targets, train_indexes, val_indexes, test_indexes):
    # re-scale the features and the targets
    descriptors[train_indexes], feature_means, feature_vars = standard_scale(descriptors[train_indexes])
    descriptors[val_indexes] = standard_scale(descriptors[val_indexes], feature_means, feature_vars)
    descriptors[test_indexes] = standard_scale(descriptors[test_indexes], feature_means, feature_vars)
    targets[train_indexes], targets_means, targets_vars = standard_scale(targets[train_indexes])
    targets[val_indexes] = standard_scale(targets[val_indexes], targets_means, targets_vars)
    targets[test_indexes] = standard_scale(targets[test_indexes], targets_means, targets_vars)

    # initialize dataloaders and model, then train
    train_dataloader = fastpropDataLoader(fastpropDataset(descriptors[train_indexes], targets[train_indexes]), shuffle=True, batch_size=32)
    val_dataloader = fastpropDataLoader(fastpropDataset(descriptors[val_indexes], targets[val_indexes]))
    test_dataloader = fastpropDataLoader(fastpropDataset(descriptors[test_indexes], targets[test_indexes]), batch_size=1024)

    # train a linear baseline _and_ a 'real' model
    baseline_model = fastprop(
        fnn_layers=0,
        hidden_size=1_613,
        feature_means=feature_means,
        feature_vars=feature_vars,
        target_means=targets_means,
        target_vars=targets_vars,
        learning_rate=0.0001,
    )
    real_model = fastprop(
        clamp_input=True,
        fnn_layers=2,
        hidden_size=1_800,
        feature_means=feature_means,
        feature_vars=feature_vars,
        target_means=targets_means,
        target_vars=targets_vars,
        learning_rate=0.0001,
    )
    return baseline_model, real_model, train_dataloader, val_dataloader, test_dataloader
```

--------------------------------

### Display `fastprop` output directory structure

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

Use the `tree` command to visualize the directory structure created by `fastprop train`. This helps in locating output files like cached descriptors, logs, and model checkpoints.

```python
!tree pah
```

--------------------------------

### Access Default Training Configuration

Source: https://context7.com/jacksonburns/fastprop/llms.txt

Imports and displays the `DEFAULT_TRAINING_CONFIG`, an immutable dictionary containing all default hyperparameter values for Fastprop training. This serves as a reference for valid configuration keys and their defaults.

```python
from fastprop import DEFAULT_TRAINING_CONFIG

print(dict(DEFAULT_TRAINING_CONFIG))
# {
#   'descriptor_set': 'all',        # 'all' (1613), 'optimized' (947), or 'debug' (9)
#   'enable_cache': True,
# }
```

--------------------------------

### Explore Benchmark Data Directory

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

Uses the `tree` command to display the directory structure of the PAH benchmark dataset. This helps in understanding the organization of configuration files and data.

```bash
%cd /content/fastprop/benchmarks
!tree pah
```

--------------------------------

### Compile Additional File for arXiv

Source: https://github.com/jacksonburns/fastprop/blob/main/paper/paper.md

Compile an additional Markdown file to PDF for arXiv submission, similar to the main paper compilation. Requires specifying the output directory.

```bash
pandoc --citeproc -s additional_file_1.md -o additional_file_1.pdf --template default.latex \
      --pdf-engine=pdflatex --pdf-engine-opt=-output-directory=foo
```

--------------------------------

### Train fastprop using CLI

Source: https://context7.com/jacksonburns/fastprop/llms.txt

The `fastprop train` CLI command allows training configuration via a YAML file or explicit flags. Logs and model checkpoints are written to the specified output directory. Use this for command-line execution of training pipelines.

```bash
# --- Using a YAML config file (recommended) ---
cat > my_config.yml << 'EOF'
output_directory: ./lipo_output
input_file: lipophilicity.csv
smiles_column: smiles
target_columns: logP
descriptor_set: optimized
problem_type: regression
number_epochs: 200
number_repeats: 1
patience: 15
hidden_size: 1800
fnn_layers: 2
learning_rate: 0.0001
batch_size: 2048
train_size: 0.8
val_size: 0.1
test_size: 0.1
sampler: random
enable_cache: true
standardize: false
clamp_input: false
EOF

fastprop train --config my_config.yml

# --- Or pass all arguments inline ---
fastprop train \
  --output-directory ./lipo_output \
  --input-file lipophilicity.csv \
  --smiles-column smiles \
  --target-columns logP \
  --descriptor-set optimized \
  --problem-type regression \
  --number-epochs 200 \
  --patience 15 \
  --hidden-size 1800 \
  --fnn-layers 2 \
  --sampler scaffold

# Monitor training progress in real time
tensorboard --logdir ./lipo_output/fastprop_*/tensorboard_logs

```

--------------------------------

### Train fastprop using Python API

Source: https://context7.com/jacksonburns/fastprop/llms.txt

Orchestrates the entire training pipeline by loading data, computing descriptors, splitting data, instantiating the model, and running independent train/validate/test cycles. Use this function to configure training parameters programmatically.

```python
from fastprop.cli.train import train_fastprop
from fastprop import DEFAULT_TRAINING_CONFIG

# Override only the fields you care about; all other values come from DEFAULT_TRAINING_CONFIG
cfg = dict(DEFAULT_TRAINING_CONFIG)
cfg.update(
    output_directory="./output",
    input_file="lipophilicity.csv",   # CSV with 'smiles' and 'logP' columns
    smiles_column="smiles",
    target_columns=["logP"],
    descriptor_set="optimized",       # 947-descriptor subset; faster than 'all'
    problem_type="regression",
    number_epochs=100,
    number_repeats=3,                 # train 3 independent replicates
    patience=10,
    hidden_size=1800,
    fnn_layers=2,
    learning_rate=0.0001,
    batch_size=2048,
    train_size=0.8,
    val_size=0.1,
    test_size=0.1,
    sampler="scaffold",               # chemically-aware split
    random_seed=42,
    enable_cache=True,
    precomputed=None,
    clamp_input=False,
    standardize=False,
    hopt=False,
)

validation_df, test_df = train_fastprop(**cfg)
# validation_df and test_df are pandas DataFrames with one row per replicate
# Columns include e.g. 'validation_mse_scaled_loss', 'test_r2_score', etc.
print(test_df.describe())
# Expected output (truncated):
#        test_mse_scaled_loss  test_r2_score  test_rmse  test_mae ...
# mean              0.042           0.912      0.204    0.152 ...
# std               0.003           0.008      0.007    0.005 ...

```

--------------------------------

### Display Configuration File Content

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

Prints the content of the `pah.yml` configuration file using the `cat` command. This file specifies parameters for fastprop, such as output directory, random seed, problem type, input file, target columns, SMILES column, and descriptor set.

```bash
!cat pah/pah.yml
```

--------------------------------

### Fastprop Training Summary Statistics

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

This output provides summary statistics for the validation metrics across all repetitions. It includes count, mean, standard deviation, and various quantiles for each metric.

```python
[04/19/2024 07:34:03 PM fastprop.cli.train] INFO: Displaying validation results:
                                                          count      mean  std       min       25%       50%       75%       max
validation_mse_loss                                         1.0  0.039866  NaN  0.039866  0.039866  0.039866  0.039866  0.039866
validation_r2_score                                         1.0  0.872485  NaN  0.872485  0.872485  0.872485  0.872485  0.872485
validation_mean_absolute_percentage_error_score             1.0  0.044972  NaN  0.044972  0.044972  0.044972  0.044972  0.044972
validation_weighted_mean_absolute_percentage_error_score    1.0  0.048963  NaN  0.048963  0.048963  0.048963  0.048963  0.048963
validation_mean_absolute_error_score                        1.0  0.358413  NaN  0.358413  0.358413  0.358413  0.358413  0.358413
validation_root_mean_squared_error_loss                     1.0  0.463780  NaN  0.463780  0.463780  0.463780  0.463780  0.463780
```

--------------------------------

### Prepare Data for Plotting

Source: https://github.com/jacksonburns/fastprop/blob/main/examples/fastprop_computational_adme_demo.ipynb

Imports necessary libraries and prepares data for plotting ADME prediction results. Includes optional import for 'scienceplots' for enhanced visualization.

```python
import matplotlib.pyplot as plt
try:
    # this package makes nice plots but is a _pain_ to get working
    # make the import optional
    import scienceplots

    plt.style.use("science")
except:
    pass

data = {
    "Linear": linear_interpolation,
    "fastprop": fastprop_interpolation,
    "RF": [0.62, 0.73, 0.57, 0.65, 0.75, 0.69],
    "MPNN": [0.68, 0.78, 0.59, 0.74, 0.77, 0.70],
}
```

--------------------------------

### Display First Few Lines of CSV Data

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

Shows the initial rows of the PAH dataset CSV file using the `head` command. This is helpful for understanding the data format, including SMILES strings and target columns.

```bash
!head -n 4 pah/arockiaraj_pah_data.csv
```

--------------------------------

### Train and Evaluate Fastprop Model

Source: https://context7.com/jacksonburns/fastprop/llms.txt

Trains and evaluates a fastprop model using provided data loaders and saves results to a specified output directory. Includes early stopping via patience.

```python
test_results, val_results = train_and_test(
    output_directory="./custom_output",
    fastprop_model=model,
    train_dataloader=train_dl,
    val_dataloader=val_dl,
    test_dataloader=test_dl,
    number_epochs=50,
    patience=5,
)
```

--------------------------------

### Compile Paper to PDF with Pandoc

Source: https://github.com/jacksonburns/fastprop/blob/main/paper/paper.md

Use this command to compile the paper to PDF with author affiliations and ORCIDs correctly rendered. Requires Pandoc version 3.1.6 or a custom LaTeX template.

```bash
pandoc --citeproc -s paper.md -o paper.pdf --template default.latex
```

--------------------------------

### Fastprop Testing Summary Statistics

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

This output presents summary statistics for the testing metrics. It provides a consolidated view of the model's performance on the test set, including count, mean, and other statistical measures.

```python
[04/19/2024 07:34:03 PM fastprop.cli.train] INFO: Displaying testing results:
                                                    count      mean  std       min       25%       50%       75%       max
test_mse_loss                                         1.0  0.079504  NaN  0.079504  0.079504  0.079504  0.079504  0.079504
test_r2_score                                         1.0  0.690164  NaN  0.690164  0.690164  0.690164  0.690164  0.690164
test_mean_absolute_percentage_error_score             1.0  0.079382  NaN  0.079382  0.079382  0.079382  0.079382  0.079382
test_weighted_mean_absolute_percentage_error_score    1.0  0.077446  NaN  0.077446  0.077446  0.077446  0.077446  0.077446
test_mean_absolute_error_score                        1.0  0.570651  NaN  0.570651  0.570651  0.570651  0.570651  0.570651
test_root_mean_squared_error_loss                     1.0  0.654945  NaN  0.654945  0.654945  0.654945  0.654945  0.654945
```

--------------------------------

### Reload Best Checkpoint and Run Inference

Source: https://context7.com/jacksonburns/fastprop/llms.txt

Loads the best model checkpoint and performs inference on new data. The predict_step method returns unscaled predictions.

```python
best_ckpt = "./custom_output/checkpoints/repetition-1-epoch=10-val_loss=0.42.ckpt"
loaded_model = fastprop.load_from_checkpoint(best_ckpt)
new_X = torch.randn(10, n_features)
preds = loaded_model.predict_step((new_X,), rescale=True)  # returns unscaled predictions
print(preds.shape)  # torch.Size([10, 1])
```

--------------------------------

### Fastprop Training and Validation Output

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

This output shows the progress of the DataLoader during training and the validation metrics obtained after each repetition. It includes MSE loss, R2 score, and various error metrics.

```python
Testing DataLoader 0: 100% 1/1 [00:00<00:00, 49.66it/s]
[04/19/2024 07:34:03 PM fastprop.model] INFO: Displaying validation results for repetition 1:
                                                             value
validation_mse_loss                                       0.039866
validation_r2_score                                       0.872485
validation_mean_absolute_percentage_error_score           0.044972
validation_weighted_mean_absolute_percentage_error_score  0.048963
validation_mean_absolute_error_score                      0.358413
validation_root_mean_squared_error_loss                   0.463780
```

--------------------------------

### Train the Fastprop Model

Source: https://github.com/jacksonburns/fastprop/blob/main/examples/fastprop_polaris_classification_demo.ipynb

Trains the initialized Fastprop model using the configured PyTorch Lightning Trainer and data loaders. It then reloads the best model from the saved checkpoint.

```python
trainer.fit(model, train_dataloader, val_dataloader)
ckpt_path = trainer.checkpoint_callback.best_model_path
print(f"Reloading best model from checkpoint file: {ckpt_path}")
model = model.__class__.load_from_checkpoint(ckpt_path)
```

--------------------------------

### fastpropDataset and fastpropDataLoader

Source: https://context7.com/jacksonburns/fastprop/llms.txt

PyTorch Dataset and DataLoader utilities for efficient data handling in Fastprop.

```APIDOC
## `fastpropDataset` and `fastpropDataLoader` — PyTorch data utilities

`fastpropDataset` (in `fastprop.data`) wraps descriptor and target tensors into a standard PyTorch `Dataset`. `fastpropDataLoader` sets sensible defaults (`batch_size=128`, `persistent_workers=True`) for efficient multi-worker loading.

```python
import torch
from fastprop.data import fastpropDataset, fastpropDataLoader

features = torch.randn(1000, 947)   # 1000 molecules × 947 descriptors
targets  = torch.randn(1000, 1)     # 1000 regression targets

dataset = fastpropDataset(features, targets)
print(len(dataset))                 # 1000
feat_batch, tgt_batch = dataset[0]  # single item access
print(feat_batch.shape, tgt_batch.shape)  # torch.Size([947]) torch.Size([1])

# Training loader (shuffled)
train_loader = fastpropDataLoader(dataset, batch_size=256, shuffle=True, num_workers=4)

# Validation/test loader (not shuffled)
eval_loader = fastpropDataLoader(dataset, batch_size=512, shuffle=False)

for X_batch, y_batch in train_loader:
    print(X_batch.shape)   # torch.Size([256, 947])
    print(y_batch.shape)   # torch.Size([256, 1])
    break
```
```

--------------------------------

### Load ADME Dataset with `fastprop`

Source: https://github.com/jacksonburns/fastprop/blob/main/examples/fastprop_computational_adme_demo.ipynb

Loads the Computational ADME dataset directly from a GitHub URL using `fastprop.io.read_input_csv`. Ensure the SMILES column and target names are correctly specified.

```python
from fastprop.io import read_input_csv

target_names = {
    "HLM": "LOG HLM_CLint (mL/min/kg)",
    "MDR1-MDCK ER": "LOG MDR1-MDCK ER (B-A/A-B)",
    "Solubility": "LOG SOLUBILITY PH 6.8 (ug/mL)",
    "RLM": "LOG RLM_CLint (mL/min/kg)",
    "hPPB": "LOG PLASMA PROTEIN BINDING (HUMAN) (% unbound)",
    "rPPB": "LOG PLASMA PROTEIN BINDING (RAT) (% unbound)",
}

targets, smiles = read_input_csv(
    "https://raw.githubusercontent.com/molecularinformatics/Computational-ADME/main/ADME_public_set_3521.csv",
    "SMILES",
    target_names.values(),  # this function will read the columns in the order that we ask
)
```

--------------------------------

### Train Fastprop with Replicates

Source: https://github.com/jacksonburns/fastprop/blob/main/examples/fastprop_computational_adme_demo.ipynb

Use this function to train and test Fastprop models with replicates. It handles data splitting, model creation, and training within a loop to average results over multiple runs.

```python
from fastprop.model import train_and_test
from astartes.molecules import train_val_test_split_molecules
import pandas as pd


def replicate_fastprop(
    smiles_arr: np.ndarray,
    descriptors_arr: np.ndarray,
    targets_arr: np.ndarray,
    outdir: str,
):
    baseline_results, fastprop_results = [], []
    for i in range(5):
        # get a fresh copy of the input data for re-scaling
        descriptors = torch.tensor(descriptors_arr, dtype=torch.float32)
        targets = torch.tensor(targets_arr, dtype=torch.float32)

        # split the data using kmeans clustering on the molecular fingerprint
        *_, train_indexes, val_indexes, test_indexes = train_val_test_split_molecules(
            smiles_arr,
            train_size=0.8,
            val_size=0.1,
            test_size=0.1,
            sampler="kmeans",
            random_state=42 + i,
            return_indices=True,
        )

        baseline_model, real_model, train_dataloader, val_dataloader, test_dataloader = create_loaders_and_models(
            descriptors, targets, train_indexes, val_indexes, test_indexes
        )
        test_results, validation_results = train_and_test(outdir, baseline_model, train_dataloader, val_dataloader, test_dataloader, quiet=True)
        baseline_results.append(test_results[0])
        test_results, validation_results = train_and_test(outdir, real_model, train_dataloader, val_dataloader, test_dataloader, quiet=True)
        fastprop_results.append(test_results[0])
    return (
        pd.DataFrame.from_records(fastprop_results).describe().loc["mean", "test_r_score"],
        pd.DataFrame.from_records(baseline_results).describe().loc["mean", "test_r_score"],
    )
```

--------------------------------

### Evaluate and Configure Predictions with Polaris

Source: https://github.com/jacksonburns/fastprop/blob/main/examples/fastprop_polaris_classification_demo.ipynb

Evaluates predictions using the polaris library and configures the results object with metadata for uploading. Ensure predictions are binary (0 or 1) before evaluation.

```python
results = benchmark.evaluate(predictions > 0.5, predictions)
results.name = "fastprop"
results.github_url = "https://github.com/JacksonBurns/fastprop/blob/main/examples/fastprop_polaris_classification_demo.ipynb"
results.paper_url = "https://github.com/JacksonBurns/fastprop/blob/main/paper/paper.pdf"
results.description = "fastprop-based FNN model"
results.tags = ["mordred", "mordredcommunity", "fastprop", "fnn"]
results.user_attributes = {"Framework": "fastprop"}
results
```

--------------------------------

### CLI: Predict molecular properties from SMILES

Source: https://context7.com/jacksonburns/fastprop/llms.txt

Use `fastprop predict` to load checkpoints and run inference on single or multiple SMILES strings, or from a file. It can also use precomputed descriptors to speed up the process.

```bash
fastprop predict \
  --checkpoints-dir ./lipo_output/fastprop_1700000000/checkpoints \
  --smiles "CCO" "c1ccccc1" "CC(=O)O" \
  --descriptor-set optimized
```

```bash
fastprop predict \
  --checkpoints-dir ./lipo_output/fastprop_1700000000/checkpoints \
  --smiles-file my_molecules.smi \
  --descriptor-set optimized \
  --output predictions.csv
```

```bash
fastprop predict \
  --checkpoints-dir ./lipo_output/fastprop_1700000000/checkpoints \
  --precomputed-descriptors cached_descriptors.csv \
  --descriptor-set optimized
```

--------------------------------

### Configure Training Parameters for Fastprop

Source: https://context7.com/jacksonburns/fastprop/llms.txt

Override default training configuration values to customize model training. This is useful for adjusting problem type, training duration, and repetition count.

```python
# Use as a base and override specific fields
config = dict(DEFAULT_TRAINING_CONFIG)
config.update(problem_type="binary", number_epochs=200, number_repeats=5)
```

--------------------------------

### Fastprop PyTorch Dataset and DataLoader

Source: https://context7.com/jacksonburns/fastprop/llms.txt

Provides `fastpropDataset` for wrapping feature and target tensors into a PyTorch `Dataset` and `fastpropDataLoader` for efficient batch loading with sensible defaults for training and evaluation.

```python
import torch
from fastprop.data import fastpropDataset, fastpropDataLoader

features = torch.randn(1000, 947)   # 1000 molecules × 947 descriptors
targets  = torch.randn(1000, 1)     # 1000 regression targets

dataset = fastpropDataset(features, targets)
print(len(dataset))                 # 1000
feat_batch, tgt_batch = dataset[0]  # single item access
print(feat_batch.shape, tgt_batch.shape)  # torch.Size([947]) torch.Size([1])

# Training loader (shuffled)
train_loader = fastpropDataLoader(dataset, batch_size=256, shuffle=True, num_workers=4)

# Validation/test loader (not shuffled)
eval_loader = fastpropDataLoader(dataset, batch_size=512, shuffle=False)

for X_batch, y_batch in train_loader:
    print(X_batch.shape)   # torch.Size([256, 947])
    print(y_batch.shape)   # torch.Size([256, 1])
    break
```

--------------------------------

### Split Dataset by Scaffold or Random Sampling

Source: https://context7.com/jacksonburns/fastprop/llms.txt

Splits a dataset of SMILES strings into training, validation, and test sets using either scaffold-based or random sampling. Allows specifying sizes for each set and a random seed for reproducibility.

```python
import numpy as np
from fastprop.data import split

smiles = ["CCO", "c1ccccc1", "CC(=O)O", "CN1C=NC2=C1C(=O)N(C(=O)N2C)C",
          "CC(C)Cc1ccc(cc1)C(C)C(=O)O", "OC(=O)c1ccccc1O"]

train_idx, val_idx, test_idx = split(
    smiles=smiles,
    random_seed=42,
    train_size=0.7,
    val_size=0.15,
    test_size=0.15,
    sampler="scaffold",   # "random" for non-chemistry-aware split
)
print("Train:", train_idx)  # array([0, 2, 3, 4])
print("Val:  ", val_idx)    # array([1])
print("Test: ", test_idx)   # array([5])

# Set test_size=0.0 to use all data for training+validation (no held-out test set)
train_idx, val_idx, test_idx = split(smiles, test_size=0.0)
print("Test is empty:", len(test_idx) == 0)  # True
```

--------------------------------

### Make Predictions with fastprop

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

Runs `fastprop predict` to generate predictions for a given SMILES string using a trained model. Ensure the checkpoint directory path is correct for your local run.

```bash
!fastprop predict pah/fastprop_1713555122/checkpoints --smiles-strings c1c2ccccc2ccc1 -ds all
```

--------------------------------

### Upload Results to Polaris Hub (Commented Out)

Source: https://github.com/jacksonburns/fastprop/blob/main/examples/fastprop_polaris_classification_demo.ipynb

This code snippet is commented out and will only work if you are logged into the polaris website. It uploads the configured results to the polaris hub.

```python
# results.upload_to_hub(owner="jacksonburns", access="public")
```

--------------------------------

### Fastprop Citation Information

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

This message provides the citation for using Fastprop in published work, including a link to the arXiv paper.

```python
[04/19/2024 07:34:03 PM fastprop.cli.base] INFO: If you use fastprop in published work, please cite https://arxiv.org/abs/2404.02058
```

--------------------------------

### Fastprop Testing Results Output

Source: https://github.com/jacksonburns/fastprop/blob/main/fastprop_demo.ipynb

This output displays the performance metrics on the test dataset after training. It includes MSE loss, R2 score, and other error metrics, providing an evaluation of the model's generalization ability.

```python
[04/19/2024 07:34:03 PM fastprop.model] INFO: Displaying validation results for repetition 1:
                                                       value
test_mse_loss                                       0.079504
test_r2_score                                       0.690164
test_mean_absolute_percentage_error_score           0.079382
test_weighted_mean_absolute_percentage_error_score  0.077446
test_mean_absolute_error_score                      0.570651
test_root_mean_squared_error_loss                   0.654945
```

--------------------------------

### `fastprop` model class

Source: https://context7.com/jacksonburns/fastprop/llms.txt

The PyTorch Lightning module for direct instantiation, custom training loops, fine-tuning, or embedding into larger architectures. Handles feature/target scaling internally when scaling tensors are provided.

```APIDOC
## `fastprop` model class — Direct model instantiation and inference

The `fastprop` PyTorch Lightning module (in `fastprop.model`) can be instantiated directly for custom training loops, fine-tuning, or embedding into larger architectures. It handles feature/target scaling internally when `feature_means`/`feature_vars`/`target_means`/`target_vars` tensors are provided.

```python
import torch
from fastprop.model import fastprop, train_and_test
from fastprop.data import fastpropDataset, fastpropDataLoader, standard_scale, split

# --- Build synthetic dataset ---
n_samples, n_features, n_targets = 500, 947, 1
X = torch.randn(n_samples, n_features)
y = torch.randn(n_samples, n_targets)
smiles = [f"C{'C'*i}" for i in range(n_samples)]  # dummy SMILES for splitting

train_idx, val_idx, test_idx = split(smiles, random_seed=42, train_size=0.8, val_size=0.1, test_size=0.1)


```

--------------------------------

### Split Data for Validation

Source: https://github.com/jacksonburns/fastprop/blob/main/examples/fastprop_polaris_classification_demo.ipynb

Samples 20% of the training data for validation using a fixed random state for reproducibility. The remaining data is used for training.

```python
val_df = train_df.sample(frac=0.2, random_state=42)
train_df = train_df.drop(val_df.index)
```