### Download DrugEx Example Data (Bash)

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/CLI/README.md

This command downloads example data and pretrained models for the DrugEx CLI tutorial. It creates an 'examples' folder and a local copy of the Papyrus dataset in 'data/.Papyrus'. Ensure DrugEx and QSPRPred are installed prior to execution.

```bash
drugex download -o examples
```

```bash
python -m drugex.download -o examples
```

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

### Downloading Example Data and Models

Source: https://github.com/cddleiden/drugex/blob/master/docs/use.md

Downloads the necessary example datasets and pretrained models required for running the tutorial workflows.

```bash
python -m drugex.download -o tutorial/CLI/examples
```

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

### Setup Google Colab Environment

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/README.md

Downloads and executes a setup script for Google Colab to prepare the environment for running DrugEx tutorials. This includes fetching the script and running it via bash.

```python
!wget https://raw.githubusercontent.com/CDDLeiden/DrugEx/master/tutorial/colab.sh
!bash colab.sh
```

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

### Multi-class Classification Model Setup and Training

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/qsar.ipynb

This section details the setup and training of a multi-class classification model using QSPRDataset and SklearnModel. It includes data preparation with scaffold splitting, feature calculation (Morgan fingerprints), model training with RandomForestClassifier, and model assessment using cross-validation and test set evaluation.

```python
import os
from qsprpred.data import QSPRDataset
from qsprpred.data.descriptors.fingerprints import MorganFP
from qsprpred.data.sampling.splits import ScaffoldSplit
from qsprpred.tasks import TargetTasks

DATA_PATH_QSAR = "data/data/qsar"
os.makedirs(DATA_PATH_QSAR, exist_ok=True)

# create the data set
dataset = QSPRDataset(
    name="A2AR_multiclass",
    df=df.copy(), 
    target_props=[{"name" : "pchembl_value_Median", "task" : TargetTasks.MULTICLASS, "th": [0, 5.5, 7, 12]}], 
    store_dir=DATA_PATH_QSAR,
)

# split on scaffolds
split = ScaffoldSplit(test_fraction=0.2)

dataset.prepareDataset(
    split=split,
    feature_calculators=[MorganFP(radius=3, nBits=2048)]
)

print(f"Number of samples train set: {len(dataset.y)}")
print(f"Number of samples test set: {len(dataset.y_ind)}, {len(dataset.y_ind) / len(dataset.df) * 100}%")
```

```python
from qsprpred.models.scikit_learn import SklearnModel
from sklearn.ensemble import RandomForestClassifier
from qsprpred.models.assessment.methods import CrossValAssessor, TestSetAssessor

model = SklearnModel(
    name="A2AR_RandomForestMultiClassClassifier",
    base_dir='data/models/qsar/',
    alg = RandomForestClassifier
)

CrossValAssessor(scoring='roc_auc_ovr')(model, dataset)
TestSetAssessor(scoring='roc_auc_ovr')(model, dataset)
_ = model.fitDataset(dataset)
```

```python
from qsprpred.plotting.classification import MetricsPlot

plot = MetricsPlot([model], metrics=["roc_auc_ovr"])
figs, summary = plot.make(save=True, show=True)
```

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

### Install DrugEx using pip

Source: https://context7.com/cddleiden/drugex/llms.txt

Installs the DrugEx library from its GitHub repository using pip. Includes an option for installing with QSPRpred support for enhanced CLI and QSAR model integration.

```bash
pip install git+https://github.com/CDDLeiden/DrugEx.git@master
pip install "drugex[qsprpred] @ git+https://github.com/CDDLeiden/DrugEx.git@master"
```

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

### Explorer Setup for Reinforcement Learning

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/Graph-Transformer.ipynb

Creates a FragGraphExplorer instance for reinforcement learning, configuring the agent, environment, and exploration parameters.

```APIDOC
## Explorer Setup for Reinforcement Learning

### Description
Sets up a `FragGraphExplorer` which facilitates the reinforcement learning loop. It uses a pretrained model as the agent and a finetuned model as a prior to introduce mutations.

### Method
Python Code

### Endpoint
N/A

### Parameters
- **agent** (object) - Required - The pretrained model to be trained (agent).
- **env** (object) - Required - The environment for the reinforcement learning loop.
- **mutate** (object) - Required - The finetuned model used as a prior for mutations.
- **epsilon** (float) - Required - The exploration rate, controlling the influence of the finetuned network.
- **use_gpus** (boolean) - Required - Flag to indicate if GPUs should be used.

### Request Example
```python
# Assuming pretrained, environment, finetuned, epsilon, and GPUS are defined
from drugex.training.explorers import FragGraphExplorer

explorer = FragGraphExplorer(agent=pretrained, env=environment, mutate=finetuned, epsilon=0.2, use_gpus=GPUS)
```

### Response
#### Success Response (200)
An explorer object is successfully created.

#### Response Example
N/A (Python object is created in memory)
```

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

### Install DrugEx and Dependencies

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/README.md

Installs the DrugEx package and its required dependencies using pip from a requirements file.

```bash
pip install -r requirements.txt
```

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

### Set up DrugEx Environment for Reinforcement Learning

Source: https://context7.com/cddleiden/drugex/llms.txt

Combines multiple scorers with thresholds and reward schemes for multi-objective optimization in reinforcement learning. This example demonstrates setting up an environment with SA and QED scorers using both Pareto-based and weighted sum reward schemes.

```python
from drugex.training.environment import DrugExEnvironment
from drugex.training.rewards import ParetoCrowdingDistance, WeightedSum
from drugex.training.scorers.properties import Property
from drugex.training.scorers.modifiers import ClippedScore

# Define scorers with modifiers
sa_scorer = Property("SA")
sa_scorer.setModifier(ClippedScore(lower_x=5, upper_x=2))

qed_scorer = Property("QED")
qed_scorer.setModifier(ClippedScore(lower_x=0.3, upper_x=0.7))

# Create environment with Pareto-based reward scheme
environment = DrugExEnvironment(
    scorers=[sa_scorer, qed_scorer],
    thresholds=[0.5, 0.5],  # Minimum acceptable modified scores
    reward_scheme=ParetoCrowdingDistance()  # NSGA-II style ranking
)

# Alternative: weighted sum reward scheme
weighted_env = DrugExEnvironment(
    scorers=[sa_scorer, qed_scorer],
    thresholds=[0.5, 0.5],
    reward_scheme=WeightedSum()
)

# Score molecules
smiles_list = ["c1ccccc1", "CCO", "CC(=O)Oc1ccccc1C(=O)O"]
scores = environment.getScores(smiles_list)
print(scores[['Valid', 'Desired', 'SA', 'QED']])

# Get rewards for reinforcement learning
rewards = environment.getRewards(smiles_list)
```

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

### Multi-task Regression Model Setup and Training

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/qsar.ipynb

This section outlines the creation and training of a multi-task regression model. It involves loading and preparing data into a QSPRDataset, specifying multiple regression targets with imputers, splitting the data using scaffold splitting, calculating Morgan fingerprints, and then training a RandomForestRegressor model. Model performance is assessed using cross-validation and test set evaluation.

```python
import pandas as pd
from sklearn.impute import SimpleImputer
from qsprpred.data import QSPRDataset


df_multitask = pd.read_csv(f'{DATASETS_PATH}/AR_LIGANDS.tsv', sep='\t', header=0, na_values=('NA', 'nan', 'NaN'))
df_multitask = df_multitask.pivot(
    index="SMILES",
    columns="accession",
    values="pchembl_value_Mean"
)
df_multitask.columns.name = None
df_multitask.reset_index(inplace=True)

# Specify the target properties (A1, A2A, A2B, A3)
target_props = [
    {"name": "P0DMS8", "task": "REGRESSION", "imputer": SimpleImputer(strategy="mean")},
    {"name": "P29274", "task": "REGRESSION", "imputer": SimpleImputer(strategy="mean")},
    {"name": "P29275", "task": "REGRESSION", "imputer": SimpleImputer(strategy="mean")},
    {"name": "P30542", "task": "REGRESSION", "imputer": SimpleImputer(strategy="mean")}]

# create the data set
dataset = QSPRDataset(
    name="AR_multitask",
    df=df_multitask.copy(), 
    target_props=target_props,
    store_dir=DATA_PATH_QSAR,
    random_state=42
)

# split on scaffolds
split = ScaffoldSplit(test_fraction=0.2)

dataset.prepareDataset(
    split=split,
    feature_calculators=[MorganFP(radius=3, nBits=2048)]
)

print(f"Number of samples train set: {len(dataset.y)}")
print(f"Number of samples test set: {len(dataset.y_ind)}, {len(dataset.y_ind) / len(dataset.df) * 100}%")
```

```python
from qsprpred.models.scikit_learn import SklearnModel
from sklearn.ensemble import RandomForestRegressor
from qsprpred.models.assessment.methods import CrossValAssessor, TestSetAssessor

model = SklearnModel(
    name="AR_RandomForestMultiTaskRegressor",
    base_dir='data/models/qsar/',
    alg = RandomForestRegressor
)

CrossValAssessor(scoring='r2')(model, dataset)
TestSetAssessor(scoring='r2')(model, dataset)
_ = model.fitDataset(dataset)
```

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

### DrugEx Command Line Interface Operations

Source: https://context7.com/cddleiden/drugex/llms.txt

Provides examples for common CLI tasks including data preprocessing, fine-tuning graph transformer models, reinforcement learning optimization, and molecule generation.

```bash
python -m drugex.download -o tutorial/CLI/examples
python -m drugex.dataset -b tutorial/CLI/examples -i A2AR_LIGANDS.tsv -mc SMILES -o arl -mt graph
python -m drugex.train -tm FT -b tutorial/CLI/examples -i arl -o arl -ag pretrained_model.pkg -mt graph -e 100 -bs 64 -gpu 0
python -m drugex.train -tm RL -b tutorial/CLI/examples -i arl -o arl -ag arl_graph_trans_FT -pr pretrained_model.pkg -p models/qsar/A2AR_model_meta.json -ta A2AR_model -sas -e 100 -bs 64 -gpu 0
python -m drugex.generate -b tutorial/CLI/examples -i arl_test_graph.txt -g arl_graph_trans_RL -gpu 0 -n 1000
```

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

### DrugEx Command Line Interface (CLI)

Source: https://context7.com/cddleiden/drugex/llms.txt

Provides examples of using the DrugEx CLI for various tasks including data downloading, preprocessing, model training (finetuning and RL), and molecule generation.

```APIDOC
## Command Line Interface

### Description
DrugEx provides CLI commands for data preprocessing, model training, and molecule generation.

### Method
CLI commands (executed via `python -m drugex.<command>`)

### Endpoint
N/A

### Parameters
Refer to individual command help (`--help`)

### Request Example
```bash
# Download tutorial data and pretrained models
python -m drugex.download -o tutorial/CLI/examples

# Preprocess data for graph transformer
python -m drugex.dataset \
    -b tutorial/CLI/examples \
    -i A2AR_LIGANDS.tsv \
    -mc SMILES \
    -o arl \
    -mt graph

# Finetune a pretrained graph transformer
python -m drugex.train \
    -tm FT \
    -b tutorial/CLI/examples \
    -i arl \
    -o arl \
    -ag pretrained_model.pkg \
    -mt graph \
    -e 100 \
    -bs 64 \
    -gpu 0

# Reinforcement learning optimization
python -m drugex.train \
    -tm RL \
    -b tutorial/CLI/examples \
    -i arl \
    -o arl \
    -ag arl_graph_trans_FT \
    -pr pretrained_model.pkg \
    -p models/qsar/A2AR_model_meta.json \
    -ta A2AR_model \
    -sas \
    -e 100 \
    -bs 64 \
    -gpu 0

# Generate new molecules
python -m drugex.generate \
    -b tutorial/CLI/examples \
    -i arl_test_graph.txt \
    -g arl_graph_trans_RL \
    -gpu 0 \
    -n 1000

# Preprocess for RNN model (no fragmentation)
python -m drugex.dataset \
    -b tutorial/CLI/examples \
    -i A2AR_LIGANDS.tsv \
    -mc SMILES \
    -o rnn \
    -nof \
    -vf vocabulary.txt

# Get help for any command
python -m drugex.dataset --help
python -m drugex.train --help
python -m drugex.generate --help
```

### Response
Output depends on the command executed.
```

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

### Configure and Run DrugEx Test Runner with Docker

Source: https://github.com/cddleiden/drugex/blob/master/testing/runner/README.md

This script defines essential environment variables for configuring the DrugEx test runner, including GPU visibility, base Docker image, Python version, and repository URLs for DrugEx and QSPRPRED. It then executes the runner script to start the testing process. Logs are saved to the 'logs' directory.

```bash
# define important variables
export NVIDIA_VISIBLE_DEVICES=0 # ids of the GPUs to use
export BASE_IMAGE_TAG="12.0.1-cudnn8-runtime-ubuntu22.04" # cuda base image tag, translated to nvidia/cuda:12.0.1-cudnn8-runtime-ubuntu22.04
export PYTHON_VERSION="3.10" # python version for the conda base environment
export DRUGEX_REPO="https://<username>:<access-token>@your_hosting_service.com/DrugEx.git"
export DRUGEX_REVISION="master" # can be branch, commit ID or a tag
export QSPRPRED_REPO="https://<username>:<access-token>@your_hosting_service.com/QSPRPred.git"
export QSPRPRED_REVISION="main" # can be branch, commit ID or a tag

# spawn a runner with the given settings
./runner.sh # make sure you are in the 'docker' group so that you have correct permissions
```

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

### Get and Analyze Molecule Scores with DrugEx Environment

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/Sequence-RNN.ipynb

Demonstrates how to obtain desirability scores for a list of generated SMILES strings using the initialized DrugEx environment. It also shows how to retrieve the original, unmodified scores and calculates the percentage of desirable compounds based on the defined thresholds.

```python
scores = environment.getScores(generated.SMILES.to_list())
print(scores)

unmodified_scores = environment.getUnmodifiedScores(generated.SMILES.to_list())
print(unmodified_scores)

desirable_percentage = sum(scores["Desired"]) / len(scores)
print(desirable_percentage)
```

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

### Initialize DrugEx Environment with Scorers and Thresholds

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/advanced/scaffold_based.ipynb

Sets up the DrugEx environment by defining scoring functions (e.g., SAscore, QED) and their corresponding thresholds. This environment is crucial for guiding the molecule generation process based on desired properties. It utilizes predefined property scorers and modifiers to clip scores within specified ranges.

```python
from drugex.training.scorers.properties import Property
from drugex.training.scorers.modifiers import ClippedScore
from drugex.training.environment import DrugExEnvironment
from drugex.training.rewards import WeightedSum

scorers, thresholds = [], []

# SAscore
sascore = Property("SA", modifier=ClippedScore(lower_x=7, upper_x=3))
scorers.append(sascore)
thresholds.append(0.5)

# QED
qed = Property("QED", modifier=ClippedScore(lower_x=0.2, upper_x=0.8))
scorers.append(qed)
thresholds.append(0.5)

# Create environment
environment = DrugExEnvironment(scorers, thresholds, reward_scheme=WeightedSum())
```

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

### Install DrugEx Package

Source: https://github.com/cddleiden/drugex/blob/master/README.md

This command installs the DrugEx package directly from its GitHub repository using pip. It ensures you get the latest version from the master branch.

```bash
pip install git+https://github.com/CDDLeiden/DrugEx.git@master
```

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

### Initialize FragGraphExplorer for Reinforcement Learning

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/advanced/scaffold_based.ipynb

Sets up the FragGraphExplorer by initializing the agent, prior, and environment. The agent and prior are loaded from pre-trained models, and the explorer is configured with parameters like epsilon for exploration.

```python
from drugex.training.explorers import FragGraphExplorer
from drugex.training.generators import GraphTransformer
from drugex.data.corpus.vocabulary import VocGraph

vocabulary = VocGraph.fromFile('../data/models/finetuned/graph/A2AR_FT.vocab')
agent = GraphTransformer(voc_trg=vocabulary, use_gpus=GPUS)
agent.loadStatesFromFile('../data/models/finetuned/graph/A2AR_FT.pkg')
prior = GraphTransformer(voc_trg=vocabulary, use_gpus=GPUS)
prior.loadStatesFromFile('../data/models/finetuned/graph/A2AR_FT.pkg')

explorer = FragGraphExplorer(agent=agent, env=environment, mutate=prior, epsilon=0.1, use_gpus=GPUS)
```

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

### Initialize FragGraphExplorer

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.training.explorers.md

Demonstrates the initialization of the FragGraphExplorer class with required agent, environment, and hyperparameter configurations.

```python
from drugex.training.explorers.frag_graph_explorer import FragGraphExplorer

explorer = FragGraphExplorer(
    agent=agent_model,
    env=environment,
    mutate=mutate_generator,
    crover=crover_generator,
    batch_size=128,
    epsilon=0.1,
    beta=0.0
)
```

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

### GET /drugex/molecules/mol/DrExMol

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.molecules.md

Retrieves information or representation of a specific DrExMol instance.

```APIDOC
## GET /drugex/molecules/mol/DrExMol

### Description
Access properties of a DrExMol instance, such as its SMILES representation or metadata.

### Method
GET

### Endpoint
/drugex/molecules/mol/DrExMol/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the molecule.

### Request Example
{}

### Response
#### Success Response (200)
- **smiles** (string) - The SMILES representation of the molecule.
- **metadata** (dict) - Metadata associated with the molecule.

#### Response Example
{
  "smiles": "CCO",
  "metadata": {
    "weight": 46.07
  }
}
```

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

### GET /explorer/metrics

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.training.explorers.md

Calculates performance metrics for novel molecules generated by the model.

```APIDOC
## GET /explorer/metrics

### Description
Computes validation, uniqueness, and scoring metrics for a set of generated molecules.

### Method
GET

### Endpoint
/explorer/metrics

### Parameters
#### Query Parameters
- **scores** (pd.DataFrame) - Required - DataFrame containing molecule scores.

### Response
#### Success Response (200)
- **valid_ratio** (float) - Ratio of valid molecules.
- **unique_ratio** (float) - Ratio of valid and unique molecules.
- **desired_ratio** (float) - Ratio of valid, unique and desired molecules.
- **avg_amean** (float) - Average arithmetic mean score.
- **avg_gmean** (float) - Average geometric mean score.

#### Response Example
{
  "valid_ratio": 0.95,
  "unique_ratio": 0.88,
  "desired_ratio": 0.45,
  "avg_amean": 0.72,
  "avg_gmean": 0.68
}
```

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

### Initialize and Train SequenceExplorer

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.training.explorers.md

Demonstrates how to instantiate the SequenceExplorer with an agent and environment, and initiate the training process using the fit method.

```python
from drugex.training.explorers.sequence_explorer import SequenceExplorer

# Initialize the explorer
explorer = SequenceExplorer(agent=agent_model, env=environment)

# Fit the explorer to the training data
explorer.fit(epochs=100, patience=20, criteria='desired_ratio')
```

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

### GET /explorer/batch-outputs

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.training.explorers.md

Retrieves the outputs and loss for a specific batch of fragment-molecule pairs.

```APIDOC
## GET /explorer/batch-outputs

### Description
Calculates the fragments, SMILES, and loss for a given agent and source batch.

### Method
GET

### Endpoint
/explorer/batch-outputs

### Parameters
#### Query Parameters
- **net** (string) - Required - Identifier for the agent model.
- **src** (string) - Required - Identifier for the source fragment-molecule pairs.

### Response
#### Success Response (200)
- **frags** (list) - List of fragments.
- **smiles** (list) - List of SMILES strings.
- **loss** (float) - The calculated loss value.

#### Response Example
{
  "frags": ["frag1", "frag2"],
  "smiles": ["C1CCCCC1"],
  "loss": 0.05
}
```

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

### Initialize DrugEx Environment with Custom Scorers and Thresholds

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/Sequence-RNN.ipynb

Sets up the DrugEx environment by defining a list of scoring functions (e.g., QSPRpred, SAscore) and their corresponding desirability thresholds. It then instantiates the DrugExEnvironment with a ParetoCrowdingDistance reward scheme. The thresholds are used to determine molecule desirability based on modified scores.

```python
from drugex.training.environment import DrugExEnvironment
from drugex.training.rewards import ParetoCrowdingDistance

scorers = [
    qsprpred_scorer,
    sascore
]
thresholds = [
    0.5,
    0.1
]

environment = DrugExEnvironment(scorers, thresholds, reward_scheme=ParetoCrowdingDistance())
```

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

### GET /utils/pareto/get_Pareto_fronts

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.utils.md

Utility function to identify Pareto fronts from a set of multi-objective scores.

```APIDOC
## GET /utils/pareto/get_Pareto_fronts

### Description
Identifies the Pareto fronts from a given set of scores, useful for multi-objective optimization tasks.

### Method
GET

### Endpoint
drugex.utils.pareto.get_Pareto_fronts

### Parameters
#### Query Parameters
- **scores** (numpy.ndarray) - Required - An (n_points, n_scores) array of scores to evaluate.

### Request Example
{
  "scores": [[0.1, 0.9], [0.5, 0.5], [0.9, 0.1]]
}

### Response
#### Success Response (200)
- **indices** (list of numpy.ndarray) - A list containing the indices of points belonging to each Pareto front.

#### Response Example
{
  "indices": [[0, 1, 2]]
}
```

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

### Initialize DataSet from File

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.data.md

Loads a dataset from a specified file path and initializes the associated vocabulary using a provided vocabulary class.

```python
data_set = DataSet()
data_set.fromFile(path="data.csv", vocs=("vocab.txt",), voc_class=MyVocClass)
```

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

### GET /dataset/molecules

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.md

Loads raw SMILES data from a specified file and transforms them into RDKit molecule objects.

```APIDOC
## GET /dataset/molecules

### Description
Loads SMILES strings from a source file and converts them into RDKit molecule objects for further processing.

### Method
GET

### Endpoint
/dataset/molecules

### Parameters
#### Query Parameters
- **base_dir** (str) - Required - The base directory containing the data folder.
- **input_file** (str) - Required - The path to the input file (tsv or csv, supports compression).

### Response
#### Success Response (200)
- **mols** (list) - A list of RDKit molecule objects extracted from the input file.
```

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

### GET /drugex/molecules/suppliers/ListSupplier

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.molecules.md

Retrieves the next molecule from a list-based supplier, which converts input molecules into the desired representation.

```APIDOC
## GET /drugex/molecules/suppliers/ListSupplier

### Description
Fetches the next molecule from a ListSupplier instance. This method iterates through the provided list of molecules and applies the configured converter.

### Method
GET

### Endpoint
/drugex/molecules/suppliers/ListSupplier/next

### Parameters
#### Path Parameters
- **None**

#### Query Parameters
- **None**

### Request Body
- **None**

### Request Example
{}

### Response
#### Success Response (200)
- **molecule** (object) - The next molecule instance in the sequence.
- **annotations** (dict) - Optional metadata associated with the molecule.

#### Response Example
{
  "molecule": "DrExMol object",
  "annotations": {
    "source": "list"
  }
}
```

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

### Accessing DrugEx CLI Help

Source: https://github.com/cddleiden/drugex/blob/master/docs/use.md

Displays the help documentation for specific DrugEx modules to understand available arguments and functionality.

```bash
python -m drugex.dataset --help
drugex dataset --help
```

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

### GET /data/utils/paths

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.data.md

Retrieves the file paths for training and test datasets based on the provided directory and molecule type.

```APIDOC
## GET /data/utils/paths

### Description
Retrieves the paths to training and test data files based on the input directory and molecule configuration.

### Method
GET

### Endpoint
/drugex/data/utils/getDataPaths

### Parameters
#### Query Parameters
- **data_path** (string) - Required - Path to the data directory.
- **input_prefix** (string) - Required - Prefix of the data files.
- **mol_type** (string) - Required - Type of molecules ('smiles' or 'graph').
- **unique_frags** (boolean) - Required - Whether to use unique fragments.

### Request Example
{
  "data_path": "/data",
  "input_prefix": "chem_data",
  "mol_type": "smiles",
  "unique_frags": true
}

### Response
#### Success Response (200)
- **paths** (tuple) - A tuple containing the path to the training file and the test file.

#### Response Example
{
  "train_path": "/data/chem_data_train.csv",
  "test_path": "/data/chem_data_test.csv"
}
```

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

### Configure DrugEx Environment with Scorers

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/advanced/multitask_scorers.ipynb

Explains how to initialize the DrugEx environment using a list of scorers and corresponding thresholds.

```python
from drugex.training.environment import DrugExEnvironment
from drugex.training.rewards import ParetoCrowdingDistance

scorers = [dummy_scorer, dummy_multitask_scorer]
thresholds = [0.5, 0.3, 0.4]

environment = DrugExEnvironment(scorers, thresholds, reward_scheme=ParetoCrowdingDistance())
environment.getScores(["CCO", "CCN"])
```

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

### Abstract Method: Get Batch Outputs

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.training.explorers.md

Abstract method to be implemented by subclasses. It should return the fragments, SMILES, and loss of the agent for a given batch of fragments-molecule pairs.

```python
def getBatchOutputs(self, src, net):
    """Outputs (frags, smiles) and loss of the agent for a batch of fragments-molecule pairs."""
    pass
```

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

### Train Graph Transformer Model (Pretraining and Finetuning)

Source: https://context7.com/cddleiden/drugex/llms.txt

Demonstrates how to train a GraphTransformer model from scratch (pretraining) or fine-tune an existing model. It involves loading datasets, initializing the model, configuring a FileMonitor for tracking progress, and running the `fit` method. Training logs and generated SMILES can be accessed afterwards.

```python
from drugex.training.generators import GraphTransformer
from drugex.training.monitors import FileMonitor
from drugex.data.datasets import GraphFragDataSet
from drugex.data.corpus.vocabulary import VocGraph
import pandas as pd

# Load datasets
train_data = GraphFragDataSet("data/train.tsv")
test_data = GraphFragDataSet("data/test.tsv")

# Initialize model (for pretraining, skip loadStatesFromFile)
vocabulary = VocGraph.fromFile("pretrained.vocab")
model = GraphTransformer(voc_trg=vocabulary, use_gpus=(0,))

# For finetuning, load pretrained weights
model.loadStatesFromFile("pretrained_model.pkg")

# Configure monitoring for training progress
monitor = FileMonitor(
    "output/finetuned_model",
    save_smiles=True,
    reset_directory=True
)

# Train the model
model.fit(
    train_data.asDataLoader(batch_size=64),
    test_data.asDataLoader(batch_size=64),
    epochs=100,
    monitor=monitor
)

# Access training logs
training_log = pd.read_csv("output/finetuned_model_fit.tsv", sep='\t')
generated_smiles = pd.read_csv("output/finetuned_model_smiles.tsv", sep='\t')
```

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

### Initialize Explorer in DrugEx

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.training.explorers.md

Initializes the DrugEx Explorer, setting up the agent, environment, and various parameters for exploration. It supports multi-fragment SMILES filtering, batch size configuration, epsilon-greedy exploration, and device selection for computation.

```python
explorer = Explorer(agent, env, mutate=None, crover=None, no_multifrag_smiles=True, batch_size=128, epsilon=0.1, beta=0.0, n_samples=-1, device=device(type='cpu'), use_gpus=(0,))
```

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

### Execute DrugEx CLI Tests

Source: https://github.com/cddleiden/drugex/blob/master/testing/clitest/README.md

Runs the test suite for the DrugEx CLI. It provides options for running tests when the package is installed versus when only dependencies are present by setting the PYTHONPATH.

```bash
# if you do not have the package installed and only the dependencies
PYTHONPATH=../.. ./test.sh

# if you have the package installed
./test.sh
```

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

### Initialize FragExplorer

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.training.explorers.md

Initializes the FragExplorer with agent, environment, and optional mutation/convergence generators. It supports configuration for multi-fragment SMILES, batch size, exploration probability (epsilon), reward baseline (beta), sampling count, and device selection.

```python
class FragExplorer(Explorer):
    def __init__(self, agent, env, mutate=None, crover=None, no_multifrag_smiles=True, batch_size=128, epsilon=0.1, beta=0.0, n_samples=-1, device=device(type='cpu'), use_gpus=(0,)):
        pass
```

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

### Initialize GraphTransformer Models

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/Graph-Transformer.ipynb

Loads pretrained and finetuned GraphTransformer models from specified file paths. This step is essential for setting up the agent and mutation models for reinforcement learning.

```python
pretrained = GraphTransformer(voc_trg=vocabulary, use_gpus=GPUS)
pretrained.loadStatesFromFile(MODEL_FILE_PR)

finetuned = GraphTransformer(voc_trg=vocabulary, use_gpus=GPUS)
finetuned.loadStatesFromFile(f'{MODELS_FT_PATH}/A2AR_FT.pkg')
```

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

### Get Model Save Option (Python)

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.training.md

Returns the configured strategy for saving model snapshots. This strategy determines whether to save the best performing model, all models, or only models that show improvement.

```python
def getSaveModelOption():
    """Return the scheme implemented by the monitor to save model snapshots."""
    # Implementation details...
```

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

### Download DrugEx Models and Data

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/README.md

Downloads pre-trained tutorial models and necessary data using the DrugEx command-line interface.

```bash
drugex download
```

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

### Get Current Model State (Python)

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.training.md

Retrieves the current model, either as an instance of the Model class or in a serialized format. This is useful for inspecting or saving the model's current state during training.

```python
def getModel():
    """Return the current model as a Model instance or in serialized form."""
    # Implementation details...
```

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

### Pretrain DrugEx Generator Model

Source: https://github.com/cddleiden/drugex/blob/master/docs/use.md

This section demonstrates pretraining a generator model from scratch using the DrugEx CLI. It involves preparing a dataset and then initiating the training process without loading pretrained weights. The output is a pretrained generator model.

```bash
python -m drugex.dataset -b ${BASE_DIR} -i A2AR_LIGANDS.tsv -mc SMILES -o example_pt -mt graph
python -m drugex.train -tm PT -b ${BASE_DIR} -i example_pt -mt graph -e 2 -bs 32 -gpu 0
```

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

### Get DrugEx Agent Model State

Source: https://github.com/cddleiden/drugex/blob/master/docs/api/drugex.training.explorers.md

Retrieves the current state of the agent model within the DrugEx Explorer. This is useful for inspecting the model's parameters or saving its state for later use.

```python
agent_model = explorer.getModel()
```

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

### Implement Custom DrugEx Scorer Interface

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/Graph-Transformer.ipynb

Demonstrates how to create a custom scoring function by implementing the drugex.training.interfaces.Scorer interface. This example provides a dummy scorer that returns zero for all molecules, serving as a template for custom scorers.

```python
from drugex.training.scorers.interfaces import Scorer

class ModelScorer(Scorer):
    
    def __init__(self, *args, **kwargs):
        super().__init__()
        pass
    
    def getScores(self, mols, frags=None):
        """
        Processes molecules and returns a score for each (i.e. a QSAR model prediction).
        """
        
        return [0] * len(mols) # just return zero for all molecules for the sake of example
    
    def getKey(self):
        """
        Unique Identifier among all the scoring functions used in a single environment.
        """
        
        return "ScorerName"
```

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

### Initialize and View Default SMILES Vocabulary (Python)

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/advanced/extending_api.ipynb

Demonstrates how to instantiate the `VocSmiles` class without fragment encoding and view its default vocabulary words. This serves as a baseline for understanding the default tokens available.

```python
from drugex.data.corpus.vocabulary import VocSmiles

voc = VocSmiles(encode_frags=False)
voc.words
```

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

### Train Graph Transformer with FragGraphExplorer

Source: https://context7.com/cddleiden/drugex/llms.txt

Optimizes Graph Transformer models using policy gradient reinforcement learning with multi-objective rewards. This snippet initializes the explorer with agent, environment, and mutation models, configures monitoring, and starts the training process.

```python
from drugex.training.explorers import FragGraphExplorer
from drugex.training.generators import GraphTransformer
from drugex.training.environment import DrugExEnvironment
from drugex.training.rewards import ParetoCrowdingDistance
from drugex.training.monitors import FileMonitor
from drugex.data.corpus.vocabulary import VocGraph

# Load vocabulary and models
vocabulary = VocGraph.fromFile("model.vocab")

# Agent: model being optimized
agent = GraphTransformer(voc_trg=vocabulary, use_gpus=(0,))
agent.loadStatesFromFile("pretrained_model.pkg")

# Mutate/Prior: provides exploration through mutations
mutate = GraphTransformer(voc_trg=vocabulary, use_gpus=(0,))
mutate.loadStatesFromFile("finetuned_model.pkg")

# Create environment (as shown above)
# Assuming sa_scorer and qsar_scorer are defined from previous snippets
sa_scorer = Property("SA")
sa_scorer.setModifier(ClippedScore(lower_x=5, upper_x=2))
qsar_scorer = QSPRPredScorer(SklearnModel(name='A2AR_RandomForestClassifier', base_dir='./models/qsar'))
qsar_scorer.setModifier(ClippedScore(lower_x=0.2, upper_x=0.8))

environment = DrugExEnvironment(
    scorers=[sa_scorer, qsar_scorer],
    thresholds=[0.5, 0.5],
    reward_scheme=ParetoCrowdingDistance()
)

# Initialize explorer
explorer = FragGraphExplorer(
    agent=agent,
    env=environment,
    mutate=mutate,
    epsilon=0.2,      # Mutation rate (exploration vs exploitation)
    batch_size=64,
    use_gpus=(0,)
)

# Configure monitoring
monitor = FileMonitor(
    "output/rl_model",
    save_smiles=True,
    reset_directory=True
)

# Train with reinforcement learning
# Assuming train_data and test_data are loaded DataLoaders
# explorer.fit(
#     train_loader=train_data.asDataLoader(batch_size=64),
#     valid_loader=test_data.asDataLoader(batch_size=64),
#     epochs=100,
#     patience=50,        # Early stopping patience
#     criteria='desired_ratio',  # Optimization target
#     min_epochs=10,
#     monitor=monitor
# )

# Generate optimized molecules
optimized = agent.generate(
    input_frags=["c1ccncc1"],
    num_samples=100,
    evaluator=environment
)
print(optimized[['SMILES', 'Valid', 'Desired', 'SA']])
```

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

### Prepare QSPR Dataset and Split Data

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/qsar.ipynb

This snippet demonstrates how to create a QSPRDataset from a pandas DataFrame, define target properties with classification tasks and thresholds, and then prepare the dataset for modeling. It includes splitting the data using a ScaffoldSplit strategy and calculating Morgan fingerprints as molecular descriptors.

```python
import os
from qsprpred.data import QSPRDataset
from qsprpred.data.descriptors.fingerprints import MorganFP
from qsprpred.data.sampling.splits import ScaffoldSplit
from qsprpred.tasks import TargetTasks

DATA_PATH_QSAR = "data/data/qsar"
os.makedirs(DATA_PATH_QSAR, exist_ok=True)

# create the data set
dataset = QSPRDataset(
    name="A2AR",
    df=df.copy(), 
    target_props=[{"name" : "pchembl_value_Median", "task" : TargetTasks.SINGLECLASS, "th": [6.5]}], 
    store_dir=DATA_PATH_QSAR,
)

# split on scaffolds
split = ScaffoldSplit(test_fraction=0.2)

dataset.prepareDataset(
    split=split,
    feature_calculators=[MorganFP(radius=3, nBits=2048)]
)

print(f"Number of samples train set: {len(dataset.y)}")
print(f"Number of samples test set: {len(dataset.y_ind)}, {len(dataset.y_ind) / len(dataset.df) * 100}%")
```

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

### Reload QSPR Model and Make Predictions

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/qsar.ipynb

This code demonstrates how to reload a previously saved QSPRpred model from disk and use it for making predictions. It initializes a SklearnModel by specifying its name and base directory, then uses the predictMols method with example SMILES strings.

```python
## This is how you can reload the model and make predictions
from qsprpred.models.scikit_learn import SklearnModel

predictor = SklearnModel(
    name='A2AR_RandomForestClassifier',
    base_dir='./data/models/qsar'
)

predictor.predictMols(sample_inputs, use_probas=True)
```

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

### Load Model and Vocabulary

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/Graph-Transformer.ipynb

Shows how to initialize a VocGraph object from a file and load a pretrained GraphTransformer model into the specified GPU environment.

```python
from drugex.data.corpus.vocabulary import VocGraph
from drugex.training.generators import GraphTransformer

VOCAB_FILE_PR = 'data/models/pretrained/graph-trans/Papyrus05.5_graph_trans_PT.vocab'
MODEL_FILE_PR = 'data/models/pretrained/graph-trans/Papyrus05.5_graph_trans_PT.pkg'

vocabulary = VocGraph.fromFile(VOCAB_FILE_PR)
GPUS = [0]
pretrained = GraphTransformer(voc_trg=vocabulary, use_gpus=GPUS)
pretrained.loadStatesFromFile(MODEL_FILE_PR)
```

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

### DrugEx Test Runner Environment Variables (.env file)

Source: https://github.com/cddleiden/drugex/blob/master/testing/runner/README.md

This example shows how to define environment variables in a .env file for persistent configuration of the DrugEx test runner. This file can be placed in the current directory to automatically set the variables when the runner script is executed.

```env
NVIDIA_VISIBLE_DEVICES=0
DRUGEX_REPO=https://<gitlab-username>:<access-token>@<gitlab-repo-url>
DRUGEX_REVISION=master
QSPRPRED_REPO=https://<gitlab-username>:<access-token>@<gitlab-repo-url>
QSPRPRED_REVISION=main
```

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

### Initialize SequenceExplorer for Reinforcement Learning

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/Sequence-RNN.ipynb

Sets up the SequenceExplorer, a core component for reinforcement learning in DrugEx. It involves loading pre-trained and fine-tuned RNN models, defining the environment, and configuring parameters like mutation rate (epsilon) and GPU usage. The explorer facilitates the generation of novel molecules through an iterative learning process.

```python
from drugex.training.explorers import SequenceExplorer
import warnings
warnings.filterwarnings('ignore')

pretrained = SequenceRNN(voc, is_lstm=True, use_gpus=GPUS)
pretrained.loadStatesFromFile(f'{MODELS_PR_PATH}/Papyrus05.5_smiles_rnn_PT.pkg')

finetuned = SequenceRNN(voc, is_lstm=True, use_gpus=GPUS)
finetuned.loadStatesFromFile(f'{MODEL_DIR}/a2ar_finetuned.pkg')

explorer = SequenceExplorer(
    agent = finetuned,
    env = environment,
    mutate = pretrained, 
    epsilon = 0.1,
    use_gpus = GPUS
)
```

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

### Implement PrintMonitor for Epoch Loss Output

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/advanced/extending_api.ipynb

The PrintMonitor class is a simple implementation of the TrainingMonitor interface that prints the training loss for the current epoch to the standard output. It's useful for quick visual feedback during model training without complex logging setups.

```python
class PrintMonitor(TrainingMonitor):
    """Simply print current training loss at the current epoch."""

    def saveModel(self, model):
        pass

    def savePerformanceInfo(self, performance_dict, df_smiles=None):
        """Do the print."""
        print(f"Loss at epoch {performance_dict['Epoch']}:", performance_dict['loss_train'])

    def saveProgress(self, model, current_step=None, current_epoch=None, total_steps=None, total_epochs=None, *args, **kwargs):
        pass

    def endStep(self, step, epoch):
        pass

    def close(self):
        pass

    def getModel(self):
        pass

    def getSaveModelOption(self):
        pass
```

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

### Apply ClippedScore Modifier to QSPR Scorer in Python

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/Sequence-RNN.ipynb

Applies the `ClippedScore` modifier to a QSPR scorer. This modifier normalizes scores, treating values below 0.2 as undesirable and above 0.8 as desirable, with a linear progression in between. It helps guide the model towards molecules with better QSPR predictions.

```python
from drugex.training.scorers.modifiers import ClippedScore

qsprpred_scorer.setModifier(ClippedScore(lower_x=0.2, upper_x=0.8))
```

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

### File Monitor for Training

Source: https://context7.com/cddleiden/drugex/llms.txt

Illustrates how to use the `FileMonitor` class to track training progress, save checkpoints, and log generated molecules and metrics.

```APIDOC
## File Monitor for Training

### Description
The `FileMonitor` tracks training progress, saves model checkpoints, and logs generated molecules and metrics.

### Method
Python class instantiation and method calls

### Endpoint
N/A

### Parameters
- `output_dir` (str): Directory to save logs and checkpoints.
- `save_smiles` (bool): Whether to save generated molecules each epoch.
- `reset_directory` (bool): Whether to clear the output directory before starting.

### Request Example
```python
from drugex.training.monitors import FileMonitor
import pandas as pd

# Initialize monitor
monitor = FileMonitor(
    "output/experiment",
    save_smiles=True,       # Save generated molecules each epoch
    reset_directory=True    # Clear previous files
)

# After training, analyze results
training_log = pd.read_csv("output/experiment_fit.tsv", sep='\t')
print(training_log[['Epoch', 'loss_train', 'loss_valid', 'valid_ratio']])

# Plot training progress
training_log[['loss_train', 'loss_valid']].plot(
    x=training_log['Epoch'],
    title='Training Progress'
)

# Analyze generated molecules
generated = pd.read_csv("output/experiment_smiles.tsv", sep='\t')
print(f"Total molecules generated: {len(generated)}")
print(f"Valid ratio: {generated['Valid'].mean():.2%}")
print(f"Desired ratio: {generated['Desired'].mean():.2%}")

# Get best model state from monitor
best_model_state = monitor.getModel()
```

### Response
Output includes printed logs and plots. `best_model_state` contains the model weights.
```

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

### POST /training/fit

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/advanced/extending_api.ipynb

Initiates the training process for a SequenceRNN model using a specified data loader and training monitor.

```APIDOC
## POST /training/fit

### Description
Trains a SequenceRNN model using a data loader and a TrainingMonitor implementation to track performance metrics and save model states.

### Method
POST

### Endpoint
/training/fit

### Parameters
#### Request Body
- **data_loader** (DataLoader) - Required - The data loader containing the encoded training data.
- **valid_loader** (DataLoader) - Optional - The data loader for validation data.
- **epochs** (int) - Required - Number of training epochs.
- **monitor** (TrainingMonitor) - Required - An instance of a class implementing the TrainingMonitor interface (e.g., ChainedMonitor).

### Request Example
{
  "epochs": 10,
  "monitor": "ChainedMonitor([FileMonitor, PrintMonitor])"
}

### Response
#### Success Response (200)
- **status** (string) - Training completion status.

#### Response Example
{
  "status": "success",
  "message": "Model training completed successfully."
}
```

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

### Predict Molecular Properties using Trained QSPR Model

Source: https://github.com/cddleiden/drugex/blob/master/tutorial/qsar.ipynb

This snippet shows how to use a trained QSPRpred model to predict properties for new molecules. It provides example SMILES strings for caffeine and SCH-58261, and demonstrates how to use the model's predictMols method, optionally returning probabilities.

```python
# How to use the model to predict values for new molecules
sample_inputs = [
    'CN1C=NC2=C1C(=O)N(C(=O)N2C)C', # caffeine
    'c1ccccc1CCN1N=CC2=C1N=C(N)N3C2=NC(C4=CC=CO4)=N3' # SCH-58261 (50x more selective to A2A than caffeine -> more potent)
]

model.predictMols(sample_inputs, use_probas=True)
```