Appendice K — Come installare CmdStan

ConsiglioNon preoccuparti!

L’installazione richiede alcuni passaggi tecnici, ma seguendo questa guida passo-passo riuscirai a completarla anche senza esperienza informatica. Prenditi circa 20-30 minuti di tempo e segui le istruzioni con calma.

K.1 Cos’è CmdStan e perché ci serve?

Per eseguire le analisi bayesiane che imparerai in questo corso, abbiamo bisogno di un software chiamato Stan. Stan è un programma che esegue i calcoli matematici necessari per l’inferenza bayesiana. Noi però non parleremo direttamente con Stan: useremo R come “intermediario” attraverso un pacchetto chiamato cmdstanr.

Pensa a questa analogia: R è come un interprete che traduce le nostre richieste in un linguaggio che Stan può capire, e poi ci riporta i risultati in forma comprensibile.

K.2 Prima di iniziare: verifica il tuo sistema operativo

Le istruzioni sono leggermente diverse a seconda che tu usi:

  • macOS (computer Apple);
  • Windows (la maggior parte dei PC);
  • Linux (meno comune tra gli studenti).

Se non sai quale sistema operativo hai:

  • su Windows: premi il tasto Windows + Pausa, oppure cerca “Informazioni sul PC” nel menu Start;
  • su Mac: clicca sulla mela in alto a sinistra → “Informazioni su questo Mac”.

K.3 Passo 1: installa R (se non l’hai già fatto)

Prima di tutto, assicurati di avere l’ultima versione di R installata sul tuo computer.

  1. vai su https://www.r-project.org/;
  2. clicca su “download R” nel primo paragrafo;
  3. scegli un server italiano (ad esempio, quello di Milano o Padova);
  4. clicca sul link del tuo sistema operativo (Windows, macOS, o Linux);
  5. scarica e installa R seguendo le istruzioni a schermo.
Nota

Se hai già R installato, verifica che sia una versione recente (4.3 o superiore). Puoi controllare la versione aprendo R o RStudio e guardando il numero che appare all’avvio.

K.4 Passo 2: installa RStudio (consigliato)

RStudio è un ambiente di lavoro che rende molto più facile usare R. Se non l’hai già installato:

  1. vai su https://posit.co/download/rstudio-desktop/;
  2. scarica la versione gratuita (“RStudio Desktop Free”);
  3. installa seguendo le istruzioni a schermo.

K.5 Passo 3: istruzioni specifiche per il tuo sistema operativo

Ora le strade si dividono. Segui solo la sezione relativa al tuo sistema operativo.

K.5.1 Se usi macOS (Mac)

Buone notizie! Su Mac l’installazione è più semplice perché il sistema include già gli strumenti necessari.

3.1 Installa il pacchetto cmdstanr.

Apri RStudio e copia-incolla questo codice nella Console (la finestra in basso a sinistra), poi premi Invio:

install.packages("cmdstanr", repos = c("https://stan-dev.r-universe.dev", getOption("repos")))

Aspetta che l’installazione finisca (potrebbero volerci alcuni minuti).

3.2 Carica il pacchetto e verifica che tutto funzioni.

library(cmdstanr)
check_cmdstan_toolchain()

Se vedi il messaggio The C++ toolchain is configured correctly, sei a posto! Vai al Passo 4.

Se invece ricevi un errore, potrebbe essere necessario installare gli “Xcode Command Line Tools”. In questo caso:

  1. apri l’applicazione “Terminale” (la trovi in Applicazioni → Utility);
  2. copia-incolla questo comando e premi Invio:
xcode-select --install
  1. segui le istruzioni che appariranno a schermo;
  2. una volta finito, torna su RStudio e riprova check_cmdstan_toolchain().

K.5.2 Se usi Windows

Su Windows c’è un passaggio in più: dobbiamo installare degli strumenti di compilazione chiamati RTools. Non preoccuparti, è più semplice di quanto sembri!

3.1 Installa RTools

  1. Vai su https://cran.r-project.org/bin/windows/Rtools/.
  2. Scarica la versione di RTools che corrisponde alla tua versione di R:
    • se hai R 4.4.x → scarica RTools 4.4;
    • se hai R 4.3.x → scarica RTools 4.3.
    • (Non sei sicuro della versione di R? Aprilo e guarda il numero che appare all’avvio).
  3. Esegui il file scaricato per avviare l’installazione.
  4. Importante! Durante l’installazione, assicurati che sia selezionata l’opzione “Add rtools to system PATH” (dovrebbe essere già selezionata di default).
  5. Completa l’installazione cliccando “Avanti” fino alla fine.

3.2 Riavvia il computer.

Sì, è noioso, ma è importante! Riavvia il computer per assicurarti che Windows riconosca i nuovi strumenti installati.

3.3 Installa il pacchetto cmdstanr.

Dopo il riavvio, apri RStudio e copia-incolla questo codice nella Console:

install.packages("cmdstanr", repos = c("https://stan-dev.r-universe.dev", getOption("repos")))

3.4 Verifica che tutto funzioni.

library(cmdstanr)
check_cmdstan_toolchain()

Se vedi un messaggio che conferma che il toolchain è configurato correttamente, vai al Passo 4.

AvvisoSe ricevi un errore

Se check_cmdstan_toolchain() mostra un errore, probabilmente RTools non è stato aggiunto correttamente al PATH di sistema. Vedi la sezione “Risoluzione dei problemi” alla fine di questo capitolo.

K.5.3 Se usi Linux

Su Linux, gli strumenti necessari sono generalmente già presenti. Apri RStudio e procedi con:

install.packages("cmdstanr", repos = c("https://stan-dev.r-universe.dev", getOption("repos")))
library(cmdstanr)
check_cmdstan_toolchain()

Se ricevi errori, potrebbe essere necessario installare build-essential e g++ tramite il gestore pacchetti della tua distribuzione.

K.6 Passo 4: Installa CmdStan

Questo è l’ultimo passaggio! Ora che tutti gli strumenti sono pronti, possiamo installare CmdStan vero e proprio.

In RStudio, esegui:

install_cmdstan(cores = 2)
NotaCosa significa cores = 2?

Questo parametro indica quanti “nuclei” del processore usare per l’installazione. Con cores = 2, l’installazione sarà più veloce che con un solo nucleo. Se hai un computer potente, puoi provare con cores = 4.

Attenzione: questa operazione richiede tempo (da 5 a 15 minuti, a seconda del computer). Vedrai molte scritte scorrere sullo schermo: è normale! Non chiudere RStudio e aspetta che l’installazione termini.

Quando l’installazione è completa, vedrai un messaggio che indica dove CmdStan è stato installato.

K.7 Passo 5: Verifica finale

Per assicurarti che tutto funzioni, esegui questo codice:

library(cmdstanr)
cmdstan_path()

Se vedi un percorso (qualcosa come C:/Users/TuoNome/.cmdstan/cmdstan-2.35.0 su Windows o /Users/TuoNome/.cmdstan/cmdstan-2.35.0 su Mac), congratulazioni! L’installazione è completata con successo.

Puoi anche fare un test più completo:

# Questo compila ed esegue un modello di esempio
file <- file.path(cmdstan_path(), "examples", "bernoulli", "bernoulli.stan")
mod <- cmdstan_model(file)

Se non ricevi errori, sei pronto per iniziare con le analisi bayesiane!

K.8 Risoluzione dei problemi

K.8.1 Problema: “RTools non trovato” su Windows

Se check_cmdstan_toolchain() dice che non trova gli strumenti di compilazione, segui questi passaggi per aggiungere RTools al PATH manualmente:

  1. Apri le impostazioni di sistema:

    • premi il tasto Windows;
    • digita “variabili di ambiente”;
    • clicca su “Modifica le variabili di ambiente relative al sistema”.

  2. Accedi alle variabili d’ambiente:

    • nella finestra che si apre, clicca sul pulsante “Variabili d’ambiente…” in basso.

  3. Modifica la variabile PATH:

    • nella sezione inferiore (“Variabili di sistema”), trova la riga che dice “Path”;
    • selezionala e clicca “Modifica”.

  4. Aggiungi i percorsi di RTools:

    • clicca “Nuovo”;

    • aggiungi questo percorso (sostituisci 44 con la tua versione se diversa):

      C:\rtools44\usr\bin

    • Clicca di nuovo “Nuovo” e aggiungi:

      C:\rtools44\x86_64-w64-mingw32.static.posix\bin

    • Clicca “OK” su tutte le finestre

  5. Riavvia RStudio (chiudilo completamente e riaprilo).

  6. Riprova check_cmdstan_toolchain()

K.8.2 Problema: l’installazione di CmdStan si blocca o fallisce

Alcune possibili soluzioni:

  • connessione internet: assicurati di avere una connessione stabile;
  • spazio su disco: verifica di avere almeno 2 GB di spazio libero;
  • antivirus: alcuni antivirus possono interferire. Prova a disabilitarlo temporaneamente durante l’installazione;
  • riprova: a volte basta ripetere il comando install_cmdstan(cores = 2).

K.8.3 Problema: errori durante la compilazione di modelli Stan

Se l’installazione sembra completata ma ricevi errori quando provi a usare Stan:

# Prova a reinstallare CmdStan
remove_cmdstan()
install_cmdstan(cores = 2)

K.8.4 Serve ancora aiuto?

Se continui ad avere problemi:

  1. cerca il messaggio di errore esatto su Google (spesso trovi soluzioni sui forum di Stan);
  2. consulta la documentazione ufficiale: https://mc-stan.org/cmdstanr/articles/cmdstanr.html;
  3. chiedi aiuto durante le ore di ricevimento o sul forum del corso.
Consiglio

Quando chiedi aiuto per un problema tecnico, includi sempre:

  • il tuo sistema operativo (Windows/Mac/Linux);
  • la versione di R che stai usando;
  • il messaggio di errore completo (copia-incollalo!).