DRO

https://python-dro.org
Admin
DRO is a Python package that implements distributionally robust optimization methods for linear,...
Tokens:56,842
Snippets:512
Trust Score:5.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install dro Package

Source: https://python-dro.org/api/install.html

Install the 'dro' package and its dependencies using pip.

```bash
pip install dro

```

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

### Example Usage of evaluate()

Source: https://python-dro.org/api/apis/base_linear.html

Demonstrates how to use the evaluate method with an OLS model. Shows instantiation, data preparation, and calling evaluate to get the corrected MSE.

```python
model = Chi2DRO(input_dim=5, model_type='ols')
X_test = np.random.randn(50, 5)
y_test = np.random.randn(50)
score = model.evaluate(X_test, y_test)
print(f"Corrected MSE: {score:.4f}")
```

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

### Bayesian DRO Newsvendor Example

Source: https://python-dro.org/api/notebooks/param_dro.html

Demonstrates setting up and fitting a Bayesian DRO model for a newsvendor loss function. It uses an exponential distribution and KL divergence.

```python
import numpy as np
from dro.linear_model.chi2_dro import *
from dro.linear_model.bayesian_dro import *

from dro.data.dataloader_regression import regression_basic

feature_dim = 1
sample_num = 1000
X = np.ones((sample_num, feature_dim))
y = np.random.exponential(2, sample_num)

reg_model = BayesianDRO(input_dim = feature_dim, model_type = 'newsvendor')
reg_model.update({'posterior_param_num': 1, 'distribution_class': 'Exponential', 'distance_type': 'KL'})
reg_model.fit(X, y)
```

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

### Train a CVaR-DRO LightGBM model

Source: https://python-dro.org/api/notebooks/tree_dro_tutorial.html

This example shows how to use the CVaR-DRO model with LightGBM. It includes data preparation, model instantiation with a specified `eps`, configuration, training, and prediction.

```python
X, y = make_classification(
        n_samples=1000,
        n_features=5,
        n_informative=3,
        n_redundant=1,
        n_classes=2,
        random_state=42
    )

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=.2)
# create model instance
model = CVaRDRO_LGBM(eps=0.1)
config = {"max_depth":2, "learning_rate":1, "num_boost_round":4}
model.update(config)
model.fit(X_train, y_train)
predict = model.predict(X_test)
print((predict==y_test).mean())
```

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

### BaseNNDRO Classification Example

Source: https://python-dro.org/api/apis/base_nn.html

Example of initializing and fitting a BaseNNDRO model for classification. Requires numpy and matplotlib for plotting metrics.

```python
>>> X, y = np.random.randn(1000, 64), np.random.randint(0,2,1000)
>>> model = BaseNNDRO(input_dim=64, num_classes=2)
>>> metrics = model.fit(X, y, lr=5e-4, epochs=50)
>>> plt.plot(metrics['val_accuracy'])
```

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

### Chi2DRO Worst Distribution Example

Source: https://python-dro.org/api/apis/chi2dro_linear.html

Instantiates Chi2DRO, generates synthetic data, and computes the worst-case distribution. Asserts that the resulting weights sum to 1.

```python
>>> model = Chi2DRO(input_dim=5, eps=0.5)
>>> X = np.random.randn(100, 5)
>>> y = np.sign(np.random.randn(100))  # Binary labels
>>> dist = model.worst_distribution(X, y)
>>> print(dist["weight"].shape)  # (100,)
>>> np.testing.assert_allclose(dist["weight"].sum(), 1.0, rtol=1e-3)  # Sum to 1
```

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

### BaseNNDRO Regression Example

Source: https://python-dro.org/api/apis/base_nn.html

Example of initializing and fitting a BaseNNDRO model for regression using PyTorch tensors. The target variable `y` is squeezed to remove an unnecessary dimension.

```python
>>> X = torch.randn(500, 8)
>>> y = X @ torch.randn(8,1) + 0.1*torch.randn(500,1)
>>> model = BaseNNDRO(input_dim=8, task_type='regression')
>>> model.fit(X, y.squeeze(), batch_size=64)
```

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

### Initialize HRNNDRO for CIFAR-10

Source: https://python-dro.org/api/apis/hrdro_nn.html

Instantiate the HRNNDRO model with specific parameters for a classification task on CIFAR-10. This example demonstrates setting custom adversarial parameters.

```python
adv_params = {"steps":5, "norm":"l2", "method":"PGD"}
model = HRNNDRO(
    input_dim=3072, 
    num_classes=10,
    alpha=0.5,
    epsilon=0.2,
    adversarial_params=adv_params
)

```

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

### Import necessary libraries for DRO with tree models

Source: https://python-dro.org/api/notebooks/tree_dro_tutorial.html

Import XGBoost, scikit-learn, and specific DRO model classes for tree ensembles. Ensure these libraries are installed.

```python
import xgboost as xgb
import numpy as np
from sklearn.model_selection import train_test_split
from sklearn.datasets import make_classification
from dro.tree_model.xgb import KLDRO_XGB, CVaRDRO_XGB
from dro.tree_model.lgbm import KLDRO_LGBM, CVaRDRO_LGBM
```

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

### Bayesian DRO Regression Example

Source: https://python-dro.org/api/notebooks/param_dro.html

Demonstrates setting up and fitting a Bayesian DRO model for an Ordinary Least Squares (OLS) regression task. It uses chi2 divergence.

```python
from dro.linear_model.chi2_dro import *
from dro.linear_model.bayesian_dro import *

from dro.data.dataloader_regression import regression_basic

feature_dim = 5
X, y = regression_basic(num_samples = 100, d = feature_dim, noise = 1)

reg_model = BayesianDRO(input_dim = feature_dim, model_type = 'ols')

reg_model.update({'posterior_param_num': 5, 'distance_type': 'chi2'})
reg_model.fit(X, y)
```

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

### Prepare Mosek License

Source: https://python-dro.org/api/install.html

Place the Mosek license file in the 'mosek' directory within your home directory.

```bash
cd
mkdir mosek
mv /path_to_license/mosek.lic mosek/

```

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

### Initialize BaseLinearDRO Model

Source: https://python-dro.org/api/apis/base_linear.html

Instantiate a BaseLinearDRO model with specified parameters. Configure input dimension, model type, intercept fitting, solver, and kernel.

```python
BaseLinearDRO(
    input_dim_,
    model_type ='svm',
    fit_intercept =True,
    solver ='MOSEK',
    kernel ='linear'
)
```

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

### CVaRDRO_LGBM Initialization

Source: https://python-dro.org/api/apis/cvardro_tree.html

Initializes the CVaRDRO_LGBM model with specified epsilon and task kind.

```APIDOC
## CVaRDRO_LGBM(eps=0.2, kind='classification')

### Description
Initializes the CVaRDRO_LGBM model with Conditional Value-at-Risk (CVaR) Distributionally Robust Optimization (DRO) using LightGBM.

### Parameters
* **eps** (float) - Constraint parameter (1 > ε > 0, default: 0.2)
* **kind** (str) - Task type ('classification' or 'regression', default: classification)

### Raises
* **ValueError** - If invalid parameters are provided
* **TypeError** - If inputs have incorrect types
```

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

### KLDRO Initialization

Source: https://python-dro.org/api/apis/kldro_linear.html

Initializes the KL-DRO model with specified parameters. Key parameters include input dimension, model type (e.g., 'svm', 'logistic', 'ols', 'lad'), whether to fit an intercept, the convex optimization solver, the kernel type, and the KL divergence bound (epsilon).

```APIDOC
## KLDRO(input_dim, model_type='svm', fit_intercept=True, solver='MOSEK', kernel='linear', eps=0.0)

### Description
Initializes KL-divergence Distributionally Robust Optimization model. Configures KL ambiguity set parameters defined by Q={Q≪P|DKL(Q‖P)≤ϵ}.

### Parameters
* **input_dim** (int) - Dimension of input features. Must match training data features.
* **model_type** (str) - Base model architecture. Supported: 'svm', 'logistic', 'ols', 'lad'.
* **fit_intercept** (bool) - If True, adds intercept term b to linear model. Disable when data is pre-centered.
* **solver** (str) - Convex optimization solver. Supported: 'MOSEK'.
* **kernel** (str) - The kernel type to be used in the optimization model, default = ‘linear’.
* **eps** (float) - KL divergence bound (ε ≥ 0). Special cases: ε = 0 (standard empirical risk minimization), ε → ∞ (maximally conservative).

### Example
```python
>>> from dro_linear.kl_dro import KLDRO
>>> model = KLDRO(input_dim=5, model_type='logistic', eps=0.1)
>>> model.input_dim
5
>>> model.eps
0.1
```
```

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

### Get SVM Satisficing Model Parameters

Source: https://python-dro.org/api/notebooks/WassersteinDRO_tutorial.html

Retrieves the fitted parameters (theta and b) for the SVM satisficing model.

```python
{'theta': [-9.569193873337038e-17, 1.2730213999516989e-14],
 'b': array(0.03031427)}
```

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

### MarginalCVaRDRO Initialization

Source: https://python-dro.org/api/apis/marginaldro.html

Initializes the MarginalCVaRDRO model with specified parameters for robust optimization.

```APIDOC
## MarginalCVaRDRO

### Description
Initializes the MarginalCVaRDRO model with specified parameters for robust optimization.

### Parameters
* **input_dim** (int) - Dimension of input features. Must be ≥ 1.
* **model_type** (str) - Base model architecture. Supported: 'svm', 'logistic', 'ols', 'lad'.
* **fit_intercept** (bool) - Whether to learn intercept term b. Defaults to True.
* **solver** (str) - Convex optimization solver. Defaults to ‘MOSEK’.
* **kernel** (str) - The kernel type to be used in the optimization model. Defaults to ‘linear’.
* **alpha** (float) - CVaR risk level controlling tail expectation. Must satisfy 0 < α ≤ 1. Defaults to 1.0.
* **L** (float) - Wasserstein radius scaling factor. Must satisfy L ≥ 0. Defaults to 10.0.
* **p** (int) - Order of Wasserstein distance. Supported values: 1 or 2. Defaults to 2.

### Raises
**ValueError** - If input_dim < 1, alpha ∉ (0, 1], L < 0, or p < 1.

### Example
```python
>>> model = MarginalCVaRDRO(
...     input_dim=5, 
...     model_type='lad',
...     alpha=0.95,
...     L=5.0,
...     p=1
... )
>>> model.L  # 5.0
>>> model.p  # 1
```
```

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

### Get Logistic Regression Model Parameters

Source: https://python-dro.org/api/notebooks/WassersteinDRO_tutorial.html

Retrieves the fitted parameters (theta and b) for the logistic regression model.

```python
{'theta': [-1.208003584870942, 1.2080035865776435], 'b': array(1.15966179)}
```

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

### Initialize KLDRO Model

Source: https://python-dro.org/api/apis/kldro_linear.html

Instantiate the KLDRO model with specified input dimensions, model type, and KL divergence bound. Access initialized attributes to verify settings.

```python
model = KLDRO(input_dim=5, model_type='logistic', eps=0.1)
>>> model.input_dim  # 5
>>> model.eps  # 0.1
>>> model.dual_variable  # None (until fit is called)
```

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

### Initialize SinkhornDRO Model

Source: https://python-dro.org/api/apis/sinkhorn_dro.html

Instantiate the Sinkhorn Linear DRO model with specified parameters. Ensure numerical constraints for regularization and loss scaling are met. The default device is 'cpu'.

```python
model = SinkhornDRO(
    input_dim=10,
    model_type='svm',
    reg_param=0.01,
    lambda_param=50.0
)
print(model.device)  # 'cpu'
```

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

### Accessing Bayesian DRO Parameters

Source: https://python-dro.org/api/apis/bayesian_dro.html

Example of how to print the 'theta' and 'b' parameters from a Bayesian DRO model. These parameters typically represent model coefficients or latent variables.

```python
>>> print(params["theta"])
>>> print(params["b"])
```

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

### HRNNDRO Initialization

Source: https://python-dro.org/api/apis/hrdro_nn.html

Initializes the Holistic Robust DRO model with specified parameters for robust optimization.

```APIDOC
## HRNNDRO(input_dim, num_classes, task_type='classification', model_type='mlp', alpha=0.1, r=0.01, epsilon=0.1, learning_approach='HD', adversarial_params=None, train_batch_size=64, device=device(type='cpu'))

### Description
Initializes Holistic Robust DRO.

### Parameters
* **input_dim** (int) - Input feature dimension d≥1
* **num_classes** (int) - Output dimension: Classification: K≥2 (number of classes), Regression: Automatically set to 1
* **task_type** (str) - Learning task type. Supported: 'classification': Cross-entropy loss, 'regression': MSE loss
* **model_type** (str) - Neural architecture type. Supported: 'mlp' (default), 'linear', 'resnet', 'alexnet'
* **device** (torch.device) - Target computation device, defaults to CPU
* **alpha** (float) - Robustness regularization coefficient α>0, controls model conservativeness. Defaults to 0.1.
* **r** (float) - Statistical error radius r>0 for distribution shift, defaults to 0.01.
* **epsilon** (float) - Contamination ratio ϵ∈[0,1), proportion of adversarial samples. Defaults to 0.1.
* **learning_approach** (str) - Robust optimization method. Options: "HR": Huberian Robust optimization, "HD": Hybrid DRO (default)
* **adversarial_params** (dict) - Adversarial training configuration: Defaults to {"steps":7, "step_size":0.03, "norm":"l-inf", "method":"PGD"}
* **train_batch_size** (int) - Training batch size B≥1, defaults to 64.

### Raises
**ValueError** - If alpha ≤ 0, If r ≤ 0, If ε ∉ [0,1), If invalid learning_approach

### Example (CIFAR-10)
```python
adv_params = {"steps":5, "norm":"l2", "method":"PGD"}
model = HRNNDRO(
    input_dim=3072, 
    num_classes=10,
    alpha=0.5,
    epsilon=0.2,
    adversarial_params=adv_params
)
```
```

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

### Initialize HR_DRO_LR Model

Source: https://python-dro.org/api/apis/hrdro.html

Instantiate the HR_DRO_LR model with specified parameters for input dimension, model type, and robustness settings. Ensure parameters like 'r', 'epsilon', and 'epsilon_prime' adhere to their defined constraints.

```python
model = HR_DRO_LR(
    input_dim=5, 
    model_type='logistic',
    r=0.5,
    epsilon=0.3,
    epsilon_prime=0.8
)
print(model.r, model.epsilon_prime)
```

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

### Get Worst-Case Sample Point for Regression

Source: https://python-dro.org/api/notebooks/WassersteinDRO_tutorial.html

Retrieves a specific worst-case sample point from the regression model's worst-case distribution calculation. This is useful for understanding the extreme scenarios the model is robust against.

```python
reg_model.update({'cost_matrix': costM, 'eps': 1, 'p':2, 'kappa': 'inf'})
worst_case_log = reg_model.worst_distribution(X, y, 'asymp', 0.01)
worst_case_log['sample_pts'][0][-1]
```

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

### MOT-DRO Model Initialization and Training

Source: https://python-dro.org/api/notebooks/mixed_dro_tutorial.html

Initializes and trains a MOTDRO model for regression tasks. Note that this implementation does not support OLS and requires specific conditions for Y uncertainties.

```python
from sklearn.datasets import make_regression

# Data generation
X, y = make_regression(n_samples=100, n_features=10, random_state=42)

from dro.linear_model.mot_dro import *
mot_dro_model = MOTDRO(input_dim = 10, model_type = 'lad', fit_intercept = True)
mot_dro_model.update({'eps': 1, 'square':2})
mot_dro_model.fit(X, y)
```

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

### Apply Personalized Loss to Wasserstein DRO

Source: https://python-dro.org/api/notebooks/personalize_loss_tutorial.html

Integrate custom `_loss`, `_cvx_loss`, and `_penalization` functions into the WassersteinDRO model to apply personalized loss. This example demonstrates fitting the model with different epsilon values.

```python
from dro.linear_model.wasserstein_dro import *
X = np.array([[1, 1], [2, 1], [3, 1], [4,1]])
y = np.array([1, 1, 0, 0])

model = WassersteinDRO(input_dim = 2, model_type = 'quantile')
model._loss = MethodType(_loss, model)
model._cvx_loss = MethodType(_cvx_loss, model)
# additional adjustment for the penalization function
model._penalization = MethodType(_penalization, model)

model.update({'eps': 0.05})
print('small eps', model.fit(X, y))

model.update({'eps': 0.1})
print('large eps', model.fit(X, y))
```

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

### load

Source: https://python-dro.org/api/apis/base_linear.html

Loads model parameters from a configuration dictionary.

```APIDOC
## load(config)

### Description
Load model parameters from a configuration dictionary.

### Parameters
* **config** (dict) - The model configuration to load.
```

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

### Initialize BaseNNDRO for Classification

Source: https://python-dro.org/api/apis/base_nn.html

Set up the main neural network DRO framework for a classification task. Specify input dimensions, number of classes, model type, and the computation device.

```python
model = BaseNNDRO(
    input_dim=64,
    num_classes=10,
    task_type="classification",
    model_type="mlp",
    device=torch.device("cuda")
)
```

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

### Get Worst Distribution with CVaRDRO

Source: https://python-dro.org/api/apis/cvardro_linear.html

Use `worst_distribution` to obtain a subset of samples and their weights that exceed the CVaR threshold. This is useful for analyzing the most critical data points according to the model's risk assessment. Ensure the model has been fitted before calling this method.

```python
>>> model = CVaRDRO(input_dim=3, alpha=0.95)
>>> X = np.random.randn(100, 3)
>>> y = np.sign(np.random.randn(100))
>>> model.fit(X, y)
>>> dist = model.worst_distribution(X, y)
>>> high_risk_X, high_risk_y = dist["sample_pts"]
>>> print(high_risk_X.shape[0] == len(dist["weight"]))  # True
>>> np.testing.assert_allclose(dist["weight"].sum(), 1.0, atol=1e-6)
```

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

### Illustrate Worst-Case Distributions

Source: https://python-dro.org/api/notebooks/f_dro_tutorial.html

Generates and visualizes the worst-case distributions for Chi2, KL, TV, and CVaR DRO models after fitting. This helps in understanding the model's robustness.

```python
# worst case distribution for each method
worst_chi2 = clf_model_chi2.worst_distribution(X, y)
draw_classification(worst_chi2['sample_pts'][0], worst_chi2['sample_pts'][1], weight = worst_chi2['weight'], title = 'worst-chi2')

worst_kl = clf_model_kl.worst_distribution(X, y)
draw_classification(worst_kl['sample_pts'][0], worst_kl['sample_pts'][1], weight = worst_kl['weight'], title = 'worst-kl')

worst_tv = clf_model_tv.worst_distribution(X, y)
draw_classification(worst_tv['sample_pts'][0], worst_tv['sample_pts'][1], weight = worst_tv['weight'], title = 'worst-tv')

worst_cvar = clf_model_cvar.worst_distribution(X, y)
draw_classification(worst_cvar['sample_pts'][0], worst_cvar['sample_pts'][1], weight = worst_cvar['weight'], title = 'worst-cvar')
```

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

### Prepare Data for Classification

Source: https://python-dro.org/api/notebooks/f_dro_tutorial.html

Imports necessary libraries and prepares sample data for classification tasks using a basic dataloader. Visualizes the generated data.

```python
import numpy as np

# Prepare Data
from dro.data.dataloader_regression import regression_basic
from dro.data.dataloader_classification import classification_basic
from dro.data.draw_utils import draw_classification

X, y = classification_basic(d = 2, num_samples = 100, radius = 2, visualize = True)
```

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

### Set Solver During Initialization

Source: https://python-dro.org/api/install.html

Initialize the XXDRO model with a specific solver like 'ECOS'.

```python
model = XXDRO(..., solver = 'ECOS')

```

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

### BaseLinearDRO Class Initialization

Source: https://python-dro.org/api/apis/base_linear.html

Initializes the BaseLinearDRO model with specified parameters.

```APIDOC
## BaseLinearDRO(input_dim, model_type='svm', fit_intercept=True, solver='MOSEK', kernel='linear')

### Description
Base class for Linear Distributionally Robust Optimization (DRO) models. Supports regression and binary classification tasks using linear or kernelized models.

### Parameters
* **input_dim** (int) - Dimensionality of the input features.
* **model_type** (str) - Model type indicator ('svm', 'logistic', 'ols', 'lad'). Defaults to 'svm'.
* **fit_intercept** (bool) - Whether to calculate the intercept. Defaults to True.
* **solver** (str) - Optimization solver. Defaults to 'MOSEK'.
* **kernel** (str) - Kernel type. Defaults to 'linear'.
```

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

### MOTDRO Initialization

Source: https://python-dro.org/api/apis/motdro.html

Initializes the MOTDRO model with specified dimensions and model types. Supports custom solver and intercept fitting.

```APIDOC
## MOTDRO Constructor

### Description
Initializes the MOTDRO model with restricted model types and custom solver options. It implements DRO with a composite transportation cost involving Wasserstein distance and KL divergence.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **input_dim** (int) - Dimension of input features. Must be ≥ 1.
* **model_type** (str) - Base model type. Defaults to 'svm'. Supported: 'svm' (Support Vector Machine), 'lad' (Least Absolute Deviation).
* **fit_intercept** (bool) - Whether to learn intercept term. Defaults to True.
* **solver** (str) - Convex optimization solver. Defaults to 'MOSEK'.

### Variables
* **theta1** (float) - Wasserstein distance scaling factor (θ1≥0).
* **theta2** (float) - KL divergence penalty coefficient (θ2≥0).
* **eps** (float) - Robustness radius for OT ambiguity set (ϵ≥0).
* **p** (Union[float, str]) - Norm order for feature perturbation. Valid values: 2 (L2), 'inf' (L_inf).

### Raises
* **MOTDROError** - If `model_type` is 'ols' or 'logistic'.
* **MOTDROError** - If `input_dim` < 1.

### Default Parameters
* `theta1`: 1.0
* `square`: 2.0

### Request Example
```python
model = MOTDRO(input_dim=5, model_type='svm')
model.theta1 = 1.5
model.square = 1.0
```
```

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

### Initialize ORWDRO Model

Source: https://python-dro.org/api/apis/or_wdro.html

Initialize the ORWDRO model with anomaly-robust parameters. Set eta=0 to disable outlier robustness. Computation complexity scales as O(epsilon^-2).

```python
model = ORWDRO(
    input_dim=5,
    model_type='svm',
    eps=0.1,
    eta=0.05,
    dual_norm=2
)
```

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

### Train a KL-DRO LightGBM model

Source: https://python-dro.org/api/notebooks/tree_dro_tutorial.html

This snippet demonstrates the application of KL-divergence DRO with LightGBM. It covers the standard workflow of data splitting, model initialization, configuration, fitting, and prediction.

```python
X, y = make_classification(
        n_samples=1000,
        n_features=5,
        n_informative=3,
        n_redundant=1,
        n_classes=2,
        random_state=42
    )

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=.2)
# create model instance
model = KLDRO_LGBM(eps=0.1)
config = {"max_depth":2, "learning_rate":1, "num_boost_round":4}
model.update(config)
model.fit(X_train, y_train)
predict = model.predict(X_test)
print((predict==y_test).mean())
```

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

### CVaRDRO Initialization

Source: https://python-dro.org/api/apis/cvardro_linear.html

Initializes a CVaR-constrained DRO model with specified parameters. The model type, intercept fitting, solver, and risk level (alpha) can be configured.

```APIDOC
## CVaRDRO Initialization

### Description
Initializes a CVaR-constrained DRO model. This model is designed for both regression and classification tasks, aiming to minimize a robust loss function while adhering to a CVaR constraint.

### Parameters

#### Required Parameters
- **input_dim** (int) - Number of input features. Must match training data dimension.

#### Optional Parameters
- **model_type** (str) - Base model architecture. Supported: 'svm' (Hinge loss), 'logistic' (Logistic loss), 'ols' (Least squares), 'lad' (Least absolute deviation). Defaults to 'svm'.
- **fit_intercept** (bool) - Whether to learn an intercept term. Disable if data is pre-centered. Defaults to True.
- **solver** (str) - Convex optimization solver. Recommended: ‘MOSEK’ (commercial). Defaults to ‘MOSEK’.
- **kernel** (str) - Specifies the kernel type. Defaults to 'linear'.
- **alpha** (float) - Risk level controlling the CVaR conservativeness. Must satisfy 0 < alpha ≤ 1. Defaults to 1.0 (equivalent to worst-case optimization).

### Raises
- **ValueError** - If `model_type` is not in [‘svm’, ‘logistic’, ‘ols’, ‘lad’]
- **ValueError** - If `alpha` is outside (0, 1]
```

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

### Initialize MOTDRO Model

Source: https://python-dro.org/api/apis/motdro.html

Instantiate MOTDRO with input dimension and model type. Default parameters can be adjusted after initialization.

```python
>>> model = MOTDRO(input_dim=5, model_type='svm')
>>> model.theta1 = 1.5
>>> model.square = 1.0
```

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

### Load Model Parameters

Source: https://python-dro.org/api/apis/base_linear.html

Load pre-trained model parameters from a configuration dictionary. This is useful for resuming training or deploying a saved model.

```python
load(
    config
)
```

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

### Update Solver After Initialization

Source: https://python-dro.org/api/install.html

Change the solver for an existing XXDRO model instance to 'ECOS'.

```python
model.solver = 'ECOS'

```

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

### Initialize MarginalCVaRDRO Model

Source: https://python-dro.org/api/apis/marginaldro.html

Instantiate the MarginalCVaRDRO model with specified input dimensions and robustness parameters. The model_type determines the loss function (e.g., 'lad' for least absolute deviation regression).

```python
>>> model = MarginalCVaRDRO(
...     input_dim=5, 
...     model_type='lad',
...     alpha=0.95,
...     L=5.0,
...     p=1
... )
>>> model.L  # 5.0
>>> model.p  # 1
```

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

### TVDRO Class Initialization

Source: https://python-dro.org/api/apis/tvdro.html

Initializes the TVDRO model with specified parameters for Total Variation Distributionally Robust Optimization.

```APIDOC
## TVDRO(input_dim, model_type='svm', fit_intercept=True, solver='MOSEK', kernel='linear', eps=0.0)

### Description
Total Variation Distributionally Robust Optimization (TV-DRO) model. Implements DRO with TV ambiguity set defined as: P={Q|TV(Q,P)≤ϵ} where TV is the total variation distance.

### Parameters
* **input_dim** (int) - Feature space dimension. Must be ≥ 1
* **model_type** (str) - Base model architecture. Supported: 'svm', 'logistic', 'ols', 'lad'.
* **fit_intercept** (bool) - Whether to learn intercept term b. Defaults to True.
* **solver** (str) - Convex optimization solver. Recommended: 'MOSEK'.
* **kernel** (str) - The kernel type to be used in the optimization model, default = ‘linear’
* **eps** (float) - TV ambiguity radius. Special cases: 0 for Standard empirical risk minimization, >0 controls distributional robustness.

### Raises
* **ValueError** - If input_dim < 1 or eps < 0.

### Example
```python
model = TVDRO(
    input_dim=5,
    model_type='svm',
    eps=0.1
)
```
```

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

### Initialize WassersteinDROsatisficing Model

Source: https://python-dro.org/api/apis/wdro_linear.html

Instantiate the WassersteinDROsatisficing model with specified parameters. This model is suitable for robust satisficing constraints. Note that 'MOSEK' is the recommended solver for conic constraints.

```python
>>> model = WassersteinDROsatisficing(
...     input_dim=5,
...     model_type='svm',
...     solver='ECOS'
... )
>>> model.cost_matrix.shape  # (5, 5)
```

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

### SinkhornLinearDRO Initialization

Source: https://python-dro.org/api/apis/sinkhorn_dro.html

Initializes the Sinkhorn Linear DRO model with specified parameters.

```APIDOC
## SinkhornLinearDRO(input_dim, model_type='svm', fit_intercept=True, reg_param=0.001, lambda_param=100.0, output_dim=1, max_iter=1000, learning_rate=0.01, k_sample_max=5, device='cpu')

### Description
Sinkhorn Distributionally Robust Optimization with Linear Models.

### Parameters
* **input_dim** (int) - Dimension of input feature space (d)
* **model_type** (str) - Base model architecture. Supported: 'svm', 'logistic', 'ols', 'lad'
* **fit_intercept** (bool) - Whether to learn bias term b. Defaults to True.
* **reg_param** (float) - Entropic regularization strength ϵ controlling transport smoothness. Must be > 0. Defaults to 1e-3.
* **lambda_param** (float) - Loss scaling factor λ balancing Wasserstein distance and loss. Must be > 0. Defaults to 1e2.
* **output_dim** (int) - Dimension of model output. Defaults to 1.
* **max_iter** (int) - Maximum number of Sinkhorn iterations. Should be ≥ 100. Defaults to 1e3.
* **learning_rate** (float) - Step size for gradient-based optimization. Typical range: [1e-4, 1e-1]. Defaults to 1e-2.
* **k_sample_max** (int) - Maximum level for Multilevel Monte Carlo sampling. Defaults to 5.
* **device** (str) - Computation device. Supported: 'cpu' or 'cuda'. Defaults to ‘cpu’.

### Raises
**ValueError** - If any parameter violates numerical constraints or if model_type is not supported.

### Example
```python
model = SinkhornDRO(
    input_dim=10,
    model_type='svm',
    reg_param=0.01,
    lambda_param=50.0
)
print(model.device)  # 'cpu'
```
```

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

### Initialize Bayesian DRO Model

Source: https://python-dro.org/api/apis/bayesian_dro.html

Initialize the Bayesian DRO model with specified input dimensions, model type, and solver. Ensure input_dim is set correctly for your data.

```python
model = BayesianDRO(input_dim=10, eps=0.1)
```

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

### BayesianDRO Initialization

Source: https://python-dro.org/api/apis/bayesian_dro.html

Initializes the Bayesian DRO model with specified parameters.

```APIDOC
## BayesianDRO Initialization

### Description
Initializes the Bayesian DRO model with specified parameters.

### Parameters
* **input_dim** (int) - Dimensionality of the input features.
* **model_type** (str) - Type of base model. Supported values: ‘svm’, ‘logistic’, ‘ols’, ‘lad’. Defaults to ‘svm’.
* **fit_intercept** (bool) - Whether to fit an intercept term. Defaults to True.
* **solver** (str) - Optimization solver. Supported solvers: ‘MOSEK’. Defaults to ‘MOSEK’.
* **eps** (float) - Robustness parameter for KL-divergence ambiguity set. Defaults to 0.0.
* **distance_type** (str) - Distance type in DRO model. Supported: ‘KL’, ‘chi2’. Defaults to ‘KL’.
```

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

### Initialize MLP Layer

Source: https://python-dro.org/api/apis/base_nn.html

Create a Multi-Layer Perceptron with configurable hidden units, activation function, dropout rate, and number of layers. This is suitable for complex classification or regression problems.

```python
model = MLP(
    input_dim=64,
    num_classes=10,
    hidden_units=32,
    activation=nn.GELU(),
    dropout_rate=0.2
)
x = torch.randn(128, 64)  # batch_size=128
y = model(x)
y.shape
```

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

### Initialize WNNDRO Model

Source: https://python-dro.org/api/apis/wdro_nn.html

Initialize the Wasserstein DRO model with adversarial training. Configure input dimensions, number of classes, task type, neural architecture, and adversarial training parameters like epsilon, steps, step size, norm, and method.

```python
model = WNNDRO(
    input_dim=784,
    num_classes=10,
    epsilon=0.5,
    adversarial_norm="l-inf",
    adversarial_steps=7
)
```

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

### Initialize Linear Layer

Source: https://python-dro.org/api/apis/base_nn.html

Instantiate a fully-connected neural layer for classification or regression tasks. Specify the input feature dimension and the number of output classes.

```python
model = Linear(input_dim=5, num_classes=3)
x = torch.randn(32, 5)  # batch_size=32
y = model(x)
y.shape
```

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

### Initialize WassersteinDRO Model

Source: https://python-dro.org/api/apis/wdro_linear.html

Instantiate a WassersteinDRO model with specified input dimensions and model type. The cost matrix shape is determined by the input dimension.

```python
model = WassersteinDRO(
    input_dim=5,
    model_type='svm',
    solver='MOSEK'
)
model.cost_matrix.shape  # (5, 5)
```

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

### Prepare Data for Regression

Source: https://python-dro.org/api/notebooks/f_dro_tutorial.html

Generates regression data using scikit-learn's make_regression and imports the Chi2DRO model for fitting.

```python
import numpy as np
from sklearn.datasets import make_regression
from dro.linear_model.chi2_dro import *


# Data generation
sample_num = 200
X, y = make_regression(n_samples = sample_num, n_features=10, noise = 5, random_state=42)

eps = 2 / sample_num

dro_model = Chi2DRO(input_dim = 10, model_type = 'ols', fit_intercept=False)
dro_model.update({'eps': 0.5})
dro_model.fit(X, y)
```

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

### Initialize TVDRO Model

Source: https://python-dro.org/api/apis/tvdro.html

Initializes a TV-constrained DRO model. Configure the input dimension, base model type, and the TV ambiguity radius 'eps'. A value of 0 for 'eps' results in standard empirical risk minimization.

```python
model = TVDRO(
    input_dim=5,
    model_type='svm',
    eps=0.1
)
model.eps  # 0.1
```

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

### Classification Data Loader with Label Flipping

Source: https://python-dro.org/api/apis/dataloader_classification.html

Generates a classification dataset with a specified ratio of flipped labels, based on the paper 'Learning Models with Uniform Performance via Distributionally Robust Optimization'. Use this to simulate noisy labels.

```python
dro.data.dataloader_classification.classification_DN21(
  _d_ ,
  _flip_ratio =0.1_,
  _num_samples =100_,
  _seed =42_,
  _visualize =False_,
  _save_dir ='./visualization.png'
)
```

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

### Bayesian DRO Newsvendor CVXPY Problem

Source: https://python-dro.org/api/notebooks/param_dro.html

Sets up and solves a CVXPY problem for the Bayesian DRO newsvendor model to find optimal parameters.

```python
theta = cp.Variable(1)
b = cp.Variable(1)
eta = cp.Variable()
loss = np.sqrt(1) / np.sqrt(sample_num) * cp.norm(cp.pos(reg_model._cvx_loss(X[0], y[0], theta, b) - eta), 2) + eta
t = cp.Variable()
problem = cp.Problem(cp.Minimize(t), [t >= loss])
problem.solve(solver = 'MOSEK')
print(theta.value)
```

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

### Initialize BaseNNDRO for Regression

Source: https://python-dro.org/api/apis/base_nn.html

Configure the neural network DRO framework for a regression task. The number of classes will be automatically set to 1.

```python
model = BaseNNDRO(
    input_dim=8,
    num_classes=5,  # Auto-override to 1
    task_type="regression"
)
```

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

### Initialize Standard f-divergence DRO Models

Source: https://python-dro.org/api/notebooks/f_dro_tutorial.html

Initializes logistic regression models for Chi2, CVaR, KL, and TV f-divergence DRO. These models are suitable for handling distribution shifts.

```python
from dro.linear_model.chi2_dro import *
from dro.linear_model.cvar_dro import *
from dro.linear_model.tv_dro import *
from dro.linear_model.kl_dro import *


clf_model_chi2 = Chi2DRO(input_dim=2, model_type = 'logistic')
clf_model_cvar = CVaRDRO(input_dim=2, model_type = 'logistic')
clf_model_kl = KLDRO(input_dim = 2, model_type = 'logistic')
clf_model_tv = TVDRO(input_dim = 2, model_type = 'logistic')
```

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

### Compute and Visualize Worst-Case Distribution for Classification

Source: https://python-dro.org/api/notebooks/WassersteinDRO_tutorial.html

Computes the worst-case distribution using the exact calculation method (kappa=2) and visualizes it alongside the original data. Requires specifying the approximation method ('asymp') and a threshold.

```python
clf_model1.update({'eps': 0.1, 'kappa': 2})

worst_case_log = clf_model1.worst_distribution(X, y, 'asymp', 0.01)
draw_classification(X, y)
draw_classification(worst_case_log['sample_pts'][0][100:], worst_case_log['sample_pts'][1][100:], weight = worst_case_log['weight'][100:], title = 'worst-case', scale = 20)
```

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

### Initialize MMD_DRO Model

Source: https://python-dro.org/api/apis/mmddro.html

Instantiate the MMD_DRO model with specified input dimensions and model type. Configuration parameters like sampling method and intercept fitting can also be set during initialization or updated later.

```python
>>> model = MMD_DRO(input_dim=128, model_type='svm')
>>> model.sampling_method = 'hull' 
>>> model.eta = 0.5  
```

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

### CVaRDRO_LGBM.fit

Source: https://python-dro.org/api/apis/cvardro_tree.html

Trains the CVaRDRO_LGBM model.

```APIDOC
## fit(X, y)

### Description
Trains the KL-DRO LGBM model using the provided feature matrix and target values.

### Parameters
* **X** (numpy.ndarray) - Feature matrix (n_samples, n_features)
* **y** (numpy.ndarray) - Target values (n_samples,)

### Raises
* **ValueError** - For invalid input shapes
* **RuntimeError** - For configuration or training errors

### Return type
None
```

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

### HR_DRO_LR Initialization

Source: https://python-dro.org/api/apis/hrdro.html

Initializes the HR_DRO_LR model with specified dimensions and robustness parameters.

```APIDOC
## HR_DRO_LR(input_dim, model_type='svm', fit_intercept=True, solver='MOSEK', r=1.0, alpha=0.0, epsilon=0.5, epsilon_prime=1.0)

### Description
Initialize advanced DRO model with dual robustness parameters.

### Parameters
* **input_dim** (int) - Number of input features. Must be ≥ 1.
* **model_type** (str) - Base model type. Defaults to ‘svm’.
* **fit_intercept** (bool) - Whether to fit intercept term. Defaults to True.
* **solver** (str) - Optimization solver. Defaults to ‘MOSEK’.
* **r** (float) - Ambiguity set curvature parameter. Must satisfy r ≥ 0. Defaults to 1.0.
* **alpha** (float) - Risk level parameter. Must satisfy 0 ≤ alpha < 1. Defaults to 0.0.
* **epsilon** (float) - Wasserstein radius for distribution shifts. Must be ≥ 0. Defaults to 0.5.
* **epsilon_prime** (float) - Robustness budget for moment constraints. Must be ≥ 0. Defaults to 1.0.

### Raises
**ValueError** - 
  * If any parameter violates numerical constraints (r < 0, alpha ∉ (0,1], etc.)
  * If model_type is not in allowed set
  * If input_dim < 1

### Example
```python
>>> model = HR_DRO_LR(
...     input_dim=5, 
...     model_type='logistic',
...     r=0.5, 
...     epsilon=0.3,
...     epsilon_prime=0.8
... )
>>> print(model.r, model.epsilon_prime)
0.5 0.8
```
```

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

### KLDRO_XGB

Source: https://python-dro.org/api/apis/kldro_tree.html

KLDRO_XGB provides an implementation of XGBoost for KL-divergence based Distributionally Robust Optimization.

```APIDOC
## KLDRO_XGB.update()

### Description
Update XGBoost training configuration.

### Method
update

### Parameters
#### Request Body
- **config** (dict) - Required - XGBoost parameters dictionary

### Raises
- **KeyError** - If missing ‘num_boost_round’ parameter
- **TypeError** - For non-dictionary input

## KLDRO_XGB.loss()

### Description
Compute base loss values.

### Method
loss

### Parameters
#### Request Body
- **preds** (numpy.ndarray) - Required - Model predictions (n_samples,)
- **labels** (numpy.ndarray) - Required - True labels (n_samples,)

### Returns
Loss values array (n_samples,)

### Raises
- **NotImplementedError** - For unsupported task types

## KLDRO_XGB.fit()

### Description
Train CVaR-DRO XGBoost model.

### Method
fit

### Parameters
#### Request Body
- **X** (numpy.ndarray) - Required - Feature matrix (n_samples, n_features)
- **y** (numpy.ndarray) - Required - Target values (n_samples,)

### Raises
- **ValueError** - For invalid input shapes
- **RuntimeError** - For configuration or training errors

## KLDRO_XGB.predict()

### Description
Generate predictions.

### Method
predict

### Parameters
#### Request Body
- **X** (numpy.ndarray) - Required - Input features (n_samples, n_features)

### Returns
Model predictions

### Raises
- **NotFittedError** - If model is untrained

## KLDRO_XGB.score()

### Description
Testing function.

### Method
score
```

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

### WNNDRO Initialization

Source: https://python-dro.org/api/apis/wdro_nn.html

Initializes the Wasserstein DRO model with adversarial training. Supports classification and regression tasks with various neural network architectures.

```APIDOC
## WNNDRO(input_dim, num_classes, task_type='classification', model_type='mlp', epsilon=0.1, adversarial_steps=10, adversarial_step_size=0.02, adversarial_norm='l2', adversarial_method='PGD', device=device(type='cpu'))

### Description
Initializes the Wasserstein DRO model with adversarial training.

### Parameters
* **input_dim** (int) - Input feature dimension d≥1
* **num_classes** (int) - Output dimension: - Classification: K≥2 (number of classes) - Regression: Automatically set to 1
* **task_type** (str) - Learning task type. Supported: - `'classification'`: Cross-entropy loss - `'regression'`: MSE loss
* **model_type** (str) - Neural architecture type. Supported: - `'mlp'`: Multi-Layer Perceptron (default) - `linear` - `resnet` - `alexnet`
* **device** (torch.device) - Target computation device, defaults to CPU
* **epsilon** (float) - Dual parameter (parameter of the L2-penalty during adversarial training) ϵ≥0 controlling distributional robustness. Larger values increase model conservativeness. Defaults to 0.1.
* **adversarial_steps** (int) - Number of PGD attack iterations Tadv≥1. Defaults to 10.
* **adversarial_step_size** (float) - PGD step size ηadv>0. Defaults to 0.02.
* **adversarial_norm** (str) - Adversarial perturbation norm type. Options: - `'l2'`: ℓ2-ball constraint - `'l-inf'`: ℓ∞-ball constraint
* **adversarial_method** (str) - Adversarial example generation method. Options: - `'PGD'`: Projected Gradient Descent (default) - `'FGSM'`: Fast Gradient Sign Method

### Raises
**ValueError** - 
  * If epsilon < 0
  * If adversarial_steps < 1
  * If adversarial_step_size ≤ 0
  * If invalid norm/method type

### Example (MNIST)
```python
model = WNNDRO(
    input_dim=784,
    num_classes=10,
    epsilon=0.5,
    adversarial_norm="l-inf",
    adversarial_steps=7
)
```
```
Tokens:
Raw