📊 Hierarchical Partitioning Pipeline for GAMs

The protocol below allows us to more rapidly carry out hierarchical variance partitioning using gam.hp() from the hp.gam package. It is designed for Posit Workbench (RStudio Server) and assumes pre-fitted mgcv::gam models saved as .rds files with “model” in the title somewhere.

🚪 Login Instructions for Posit Workbench

  • Link: https://bit.ly/clearRonline

  • Username: ubuntu

  • Password: (see Tory for the current password)

  • Start a new Session and name it YOURNAME-HP.

    • NOTE: Later on, when you’re done, terminate/close the session by hitting the orange “power” button in the upper right when you’re done. We pay by the hour, so this is critical.

💡 Access to the Home directory is shared among all lab members. Please avoid overwriting each other’s files.

📁 Folder Structure for this workflow

  • In the Home folder, you should see the following folder:
clearlab_gamhp_pipeline/
├── 00_uploaded_gamms_to_HP/       # Drop your .rds GAM model files here
├── 01_gamms_HPd_and_txt_output/   # Processed models + partition .txt outputs go here
├── hp_partitioning_script.R       # Main R script
└── README.md                      # This file

▶️ How to Use

1. Prepare your model files

  • On your OWN computer, fit your models with mgcv::gam() and save each as an .rds file.
  • Filenames must include the word model (e.g., DRSP_model_beta.rds).

2. Upload to input folder

In the Files pane, open 00_uploaded_gamms_to_HP/ and click Upload to add your .rds model files. Your folder should look like:

00_uploaded_gamms_to_HP/
└── DRSP16_overwhelm_peri_model_beta.rds

3. Run the script

Copy and paste this into the console and run it:

source("hp_partitioning_script.R")

4. Check the output

For each model processed:
- A partition table (*_partition.txt) is generated.
- Both .rds and .txt are moved into 01_gamms_HPd_and_txt_output/.

🧠 What the Script Does

For each .rds in 00_uploaded_gamms_to_HP/ containing model:

  1. Loads the GAM object
  2. Runs gam.hp() for variance partitioning
  3. Writes the partition table as a .txt file
  4. Moves both .rds and .txt into 01_gamms_HPd_and_txt_output/

✅ Output Example

Before running:

00_uploaded_gamms_to_HP/
└── DRSP16_overwhelm_peri_model_beta.rds

After running:

01_gamms_HPd_and_txt_output/
├── DRSP16_overwhelm_peri_model_beta.rds
└── DRSP16_overwhelm_peri_model_beta_partition.txt

🧼 Clean up after yourself!

  • Once you’re done, move the model (.rds) and hp output file (.txt) to your done folder. Feel free to create it if it doesn’t exist, or place it in the “OTHER_done” folder.

🛑 Close the Session When You’re Done!

  • Hit the orange “power” button in the upper right to close the session when you’re done. Everything you’ve done will still be where you put it if you start a new session. We pay by the hour, so shutting down each session when we’re not using it is critical.

📝 Troubleshooting

  • Only .rds files representing gam model results can be processed.
  • Only .rds files with model somewhere in the filename are processed.
  • If needed, install required packages:
install.packages("mgcv")
install.packages("gam.hp")