# Using Optuna Dashboard with rCISSVAE

#### 2026-01-20

## What is Optuna Dashboard?

Optuna dashboard is a visualization tool that allows you to view the history and results of optuna hyperparameter optimization studies. To install it, activate your `rCISSVAE` virtual environment and use `pip install optuna-dashboard` from command line.

If you are using Positron as your IDE, you can install the Optuna Dashboard Extension and easily open optuna database files. For others, the simplest way to use Optuna Dashboard is from the command line. Please note that the command line version of Optuna Dashboard has some features that are not in the Extension.

## Creating an Optuna Dashboard with the Autotune Function

The `autotune_cissvae()` function has an option for creating an Optuna Dashboard database.

In R:

    library(tidyverse)
    library(reticulate)
    library(rCISSVAE)
    library(kableExtra)

    ## Set the virtual environment
    # reticulate::use_virtualenv("./.venv", required = TRUE)

    ## Load the data
    data(df_missing)
    data(clusters)

    aut <- autotune_cissvae(
      data = df_missing,
      index_col = "index",
      clusters = clusters$clusters,
      n_trials = 3, ## Using low number of trials for demo
      study_name = "ShowOptunaDB",
      device_preference = "cpu",
      optuna_dashboard_db = "sqlite:///optuna_study_demo.db",  # Save results to database
      load_if_exists = TRUE, ## Set true to load and continue study if it exists
      seed = 42,
      verbose = FALSE,

      ## Hyperparameter search space
      num_hidden_layers = c(2, 5),     # Try 2-5 hidden layers
      hidden_dims = c(64, 512),        # Layer sizes from 64 to 512
      latent_dim = c(10, 100),         # Latent dimension range
      latent_shared = c(TRUE, FALSE),
      output_shared = c(TRUE, FALSE),
      lr = 0.01,  # Learning rate range
      decay_factor = 0.99,
      beta = 0.01,  # KL weight range
      num_epochs = 5,                # Fixed epochs for demo
      batch_size = c(1000, 4000),     # Batch size options
      num_shared_encode = c(0, 1, 2, 3),
      num_shared_decode = c(0, 1, 2, 3),

      # Layer placement strategies - try different arrangements
      encoder_shared_placement = c("at_end", "at_start", "alternating", "random"),
      decoder_shared_placement = c("at_start", "at_end", "alternating", "random"),

      refit_patience = 2,        # Early stopping patience
      refit_loops = 10,                # Fixed refit loops
      epochs_per_loop = 5,   # Epochs per refit loop
      reset_lr_refit = FALSE
    )

    # Analyze results
    imputed <- aut$imputed
    best_model <- aut$model
    results <- aut$results

    # View best hyperparameters
    print("Trial results:")
    results |> kable() |>
      kable_styling(font_size=12)

    ## [1] "Trial results:"

trial_number | imputation_error | num_hidden_layers | hidden_dim_0 | hidden_dim_1 | hidden_dim_2 | hidden_dim_3 | hidden_dim_4 | latent_dim | latent_shared | output_shared | batch_size | num_shared_encode | num_shared_decode | encoder_shared_placement | decoder_shared_placement | layer_order_enc_used | layer_order_dec_used
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
0 | 29.62110 | 5 | 512 | 64 | 512 | 64 | 64 | 100 | FALSE | FALSE | 1000 | 1 | 1 | alternating | at_start | S,U,U,U,U | S,U,U,U,U
1 | 33.00819 | 5 | 64 | 64 | 64 | 512 | 64 | 10 | TRUE | TRUE | 1000 | 1 | 0 | alternating | alternating | S,U,U,U,U | U,U,U,U,U
2 | 58.28946 | 2 | 512 | 64 | NaN | NaN | NaN | 10 | TRUE | FALSE | 4000 | 0 | 3 | alternating | random | U,U | S,S

To view the dashboard:

From Command Line

    optuna-dashboard "sqlite:///optuna_study_demo.db"

For more information see the optuna dashboard documentation.