Résultats, documents et R

Texte des méthodes

Modèle › Texte pour la section Méthodes : un paragraphe écrit d'après le modèle, en français ou en anglais (données, transformations, mise à l'échelle, prétraitement des spectres, méthode, validation croisée, R², Q², CV-ANOVA, classement, logiciel et version de R), avec ses références. Bouton « Copier le texte ». À relire et compléter (plan d'expérience, prélèvements...) avant de le publier.

Rapport du modèle

Fichier › Rapport du modèle (ou clic droit sur le modèle) : un document PDF ou Word (.docx) avec un titre, un commentaire et les parties cochées (résumé, scores, loadings, DModX, VIP, coefficients, CV-ANOVA, classification, liste des variables...). Les graphiques y sont mis en forme comme dans leurs panneaux ouverts. Le document s'ouvre une fois écrit.

Documents (articles, rapports)

Fichier › Nouveau document (ou clic droit sur un projet dans l'explorateur) : un texte gardé dans le projet (un article, un rapport, des notes), écrit en Markdown à gauche, avec son aperçu à droite, redessiné pendant qu'on écrit. Il est enregistré avec le projet et dans ses copies de secours ; Édition › Annuler ne le touche pas, et Ctrl+Z dans le texte annule dans le texte. Départ : un document vide, un article (introduction, méthodes, résultats, discussion) ou un rapport d'analyse (pour chaque modèle : résumé, graphiques, méthodes), les modèles cochés déjà cités.

Les résultats du projet se citent entre doubles accolades ; l'aperçu et le fichier compilé donnent leur valeur :

{{M1.Q2}}  {{M1.R2Y}}  {{M1.R2X:%}} (en pourcentage)  {{M1.Q2:3}} (3 décimales)  {{M1.N}}
{{M1.gain}}  {{M1.vip.sucre}}  {{M1.coef.sucre}} (coefficient centré-réduit et son intervalle à 95 %)
{{M5.coef.annee}} (une régression : estimation, intervalle et p)  {{M5.p.annee}}  {{M1.cvanova.p}}
{{M1.scores | légende}} (un graphique, comme dans sa fenêtre)  {{M5.effets.annee}} (le graphique d'un terme)
{{M1.table.resume | légende}} (un tableau du rapport du modèle)  {{M1.methodes}} (texte des méthodes)
{{M1.resultats}} (texte des résultats : l'ajustement, chaque coefficient avec son intervalle et p,
en facteur ou en rapport de cotes pour un lien log ou logit, les termes significatifs, les
courbes, les effets aléatoires ; pour une ACP, une PLS ou une OPLS, la variance expliquée, Q²,
la CV-ANOVA et les variables les plus importantes)

Un graphique, un tableau, le texte des méthodes ou celui des résultats se met seul sur sa ligne. Modèle › Texte pour la section Méthodes montre aussi le texte des résultats, sous les méthodes. Graphiques et tableaux sont numérotés dans l'ordre (Figure 1, Tableau 1) ; avec une étiquette, {{M1.scores #fig-scores | légende}}, {{ref:fig-scores}} écrit « Figure 1 » n'importe où dans le texte. Tapez {{ pour voir les modèles du projet, puis ce que celui choisi offre, avec sa valeur du moment ; Insérer, dans la barre d'outils, fait de même par des menus, et un modèle ou sa vue dans l'explorateur a « Insérer dans le document » (clic droit).

Une référence introuvable (un modèle qui n'existe pas, une variable qu'il n'a pas) est en rouge, avec la raison au survol. Un modèle du projet pas encore calculé l'est quand le document le cite, sans ouvrir ses vues. Les nombres suivent la langue du document (0,65 en français, 0.65 en anglais), comme « Figure », « Tableau » et le texte des méthodes.

Compiler : un fichier Word (.docx : titres, listes, tableaux, graphiques et légendes dans les styles de Word), un PDF, une page HTML (un seul fichier, graphiques compris), ou un fichier Quarto (.qmd). Quand Quarto est installé (quarto.org, ou avec RStudio), « Compiler avec Quarto » en fait un Word, un PDF (Typst) ou une page HTML, avec ce que Quarto apporte : bibliographie (bibliography: refs.bib dans l'en-tête, [@cle] dans le texte), renvois, modèles de revues. Un en-tête YAML (title, author, date) en haut du document est lu ; une ligne {{< pagebreak >}} commence une nouvelle page.

Pour Quarto, le dialogue de Compiler demande les résultats :

• écrits en dur : les valeurs, les graphiques (dans un dossier à côté) et les tableaux tels que Nuée les montre ;
• reproductibles : R les recalcule à partir des données brutes quand Quarto compile le document. À côté du .qmd, le dossier « <nom>_R » contient l'export vers R de chaque modèle cité (Fichier › Exporter vers R : le script, ses données en CSV) et nuee.R. Le premier bloc du .qmd relance ces scripts, chacun dans son propre environnement ; chaque valeur citée devient une expression R en ligne, `r nuee_nombre(M1$composantes$Q2cum[2])`, qui lit la valeur recalculée et l'écrit comme Nuée (0,65, 71 %, p < 0,001) ; un graphique devient un bloc R qui le dessine avec le code du script (en R de base), un tableau un bloc knitr::kable des objets du script. Corriger une valeur du CSV, puis recompiler, recalcule tout ce que R écrit. Ce que les scripts n'ont pas reste écrit en dur, et le premier bloc du .qmd le dit en commentaire : un graphique qu'ils ne dessinent pas (son image), le coefficient d'une OPLS, ou d'une PLS validée avec les centres et les poids du modèle complet (son script n'a pas son intervalle), le texte des méthodes et celui des résultats (écrits par Nuée, pas recalculés), un modèle dont le type n'a pas encore d'export vers R (le dialogue le dit avant). Avant d'écrire le .qmd, Nuée relance les scripts et vérifie que chaque expression redonne la valeur qu'il montre ; une seule qui diffère reste écrite en dur. Il faut R avec ses paquets knitr et rmarkdown : Nuée fait compiler Quarto avec son propre R quand il les a (sinon Quarto prend le R de l'ordinateur, ou celui de QUARTO_R). Dans le navigateur, le .qmd et ce qui va à côté arrivent dans un .zip.

Les citations s'écrivent comme dans Quarto : [@wold2001], [voir @wold2001, p. 33 ; @eriksson2006], @wold2001 dans la phrase (« Wold et al. (2001) »), [-@wold2001] sans l'auteur. Taper @ montre les références du document, puis celles de Zotero. La liste des références vient à la fin (sous le dernier titre quand c'est « Références »), ou là où le document met {{bibliographie}} ; en auteur-année ou numérotée (Citer › Style des citations), dans la langue du document. D'où viennent les références (bouton Citer) :

• des fichiers BibTeX ou CSL-JSON, exportés de Zotero, Mendeley, JabRef... : Citer › Lier un fichier en nomme un dans l'en-tête (bibliography: refs.bib, relatif au dossier du projet, comme le lit Quarto). L'export automatique de Better BibTeX le tient à jour : une clé introuvable fait relire le fichier ;
• Zotero sur cet ordinateur (Zotero 7 ou plus récent, en cochant Paramètres › Avancé › « Autoriser les autres applications de cet ordinateur à communiquer avec Zotero ») : ses références se cherchent en tapant @, ou dans Citer › Insérer une citation, dans Ma bibliothèque ou dans la bibliothèque d'un groupe (ceux que Zotero synchronise, sous Ma bibliothèque dans sa fenêtre), entière ou dans une de ses collections ; la bibliothèque choisie dans Insérer une citation est gardée, et taper @ y cherche. Leurs clés sont celles de Zotero (celles de Better BibTeX quand il est installé). Avec l'extension Better BibTeX, Citer › Choisir dans Zotero ouvre le sélecteur de Zotero, dans toutes ses bibliothèques, avec la page qu'on y donne. Nuée ne fait que lire les bibliothèques. Quand Zotero ne donne pas ses bibliothèques de groupe, Insérer une citation dit pourquoi et propose Ma bibliothèque seule ;
• du BibTeX collé (Citer › Coller des références BibTeX).

Une clé est unique dans une bibliothèque Zotero, pas d'une bibliothèque à l'autre : deux œuvres différentes peuvent avoir la même clé dans Ma bibliothèque et dans un groupe (bechet2019). Une référence de Zotero dont le document donne déjà la clé à une autre œuvre (d'une autre bibliothèque, ou d'un fichier lié) y est citée avec une lettre en plus, @bechet2019a, et la barre d'état le dit ; le même élément cité de nouveau, ou la même œuvre copiée dans une autre bibliothèque (le même DOI, ou le même titre, la même année et le même premier auteur), garde la clé que le document lui donne, quelle que soit celle que Zotero lui donne là. Un fichier lié ensuite qui donne la clé d'une référence gardée de Zotero à une autre œuvre : c'est celle du fichier qui est citée, et la barre d'état le dit.

Le document garde une copie des références qu'il cite, avec la bibliothèque et l'élément d'où vient chacune de celles de Zotero : envoyé à quelqu'un qui n'a pas le .bib, il les cite encore (Citer › Références du document les montre, et retire celles qui ne sont plus citées). Compilé pour Quarto, le texte garde ses citations telles quelles, les références citées dans un .bib à côté du .qmd, pour que Quarto les écrive dans le style d'une revue (csl: style.csl dans l'en-tête ; le fichier est copié à côté du .qmd).

La langue d'une référence (le champ Langue de Zotero : fr, de...) la suit : les styles qui mettent les titres anglais en capitales (Title Case), comme celui de Quarto par défaut, laissent alors un titre français tel qu'il est écrit.

Chaque document s'ouvre dans son propre onglet. Les graphiques des documents et des rapports de modèle sont dessinés en clair, quel que soit le thème de la fenêtre.

Orthographe, en français et en anglais (et dans la langue du système) : les mots mal orthographiés sont soulignés ; clic droit pour les corrections proposées (dans tous les champs de texte de l'application).

Exporter vers d'autres logiciels

Fichier › Exporter les données : le tableau du projet (noms des observations, identifiants, variables). Fichier › Exporter les résultats du modèle (Ctrl+E) : les tableaux du modèle (observations : scores, T², DModX, valeurs ajustées ; variables : loadings, VIP, intervalles ; composantes ; coefficients ; variables Y). Formats : Excel (une feuille par tableau), CSV, texte séparé par des tabulations, R (.rds : une liste de tableaux ; .RData), SPSS (.sav), Stata (.dta), SAS transport (.xpt), jamovi (.omv), dBase (.dbf) et Weka (.arff) ; dans ces derniers, un fichier par tableau (« M1.sav », « M1 - variables.sav »...). Les variables qualitatives restent qualitatives (facteurs R, étiquettes de valeurs SPSS et Stata, nominales jamovi). Pour SPSS, Stata, SAS et dBase, les noms de variables sont rendus valides (lettres sans accent, chiffres, « _ ») ; le nom d'origine devient l'étiquette de la variable. Les unités et descriptions des variables (Édition › Unités et descriptions) vont dans une feuille « Variables » d'un classeur Excel, relue quand Nuée l'ouvre, une table « Variables » d'un GeoPackage, les descriptions d'un fichier jamovi et les attributs d'un tableau R (voir Nettoyer les données).

SAS : format de transport version 5, que SAS lit avec libname xport (noms de 8 caractères, étiquettes de 40, textes de 200 au plus). dBase : textes en Windows-1252 ; dans LibreOffice, choisir le jeu de caractères « Europe occidentale (Windows-1252) » à l'ouverture. Les fichiers écrits ont été ouverts dans jamovi, PSPP (pour SPSS), Weka, LibreOffice et pandas.

Exporter vers R (script, R Markdown, Quarto)

Fichier › Exporter vers R : un fichier qui refait le modèle sans Nuée, avec R seul, à envoyer à un collègue ou à joindre à un article. Le calcul y est écrit pour ce modèle seul, en R sans paquet (une régression : lm, ou nlme et mgcv, livrés avec R ; un NMDS : MASS, livré avec R lui aussi ; TRIM et l'échantillonnage par distances, et des arbres boostés avec rpart : les fonctions du moteur de Nuée, recopiées dans le script ; une forêt aléatoire, la seule exception : le paquet ranger, que Nuée installe avec lui), commenté dans la langue de l'export, en quatre parties :

1. les fonctions : l'algorithme NIPALS, la validation croisée, et seulement ce que ce modèle utilise (valeurs manquantes, prétraitement des spectres, OPLS...) ;
2. les données, dans le script ou dans un fichier CSV à côté (« M1 - donnees.csv »), les nombres écrits sans perte et les catégories dans leur ordre ;
3. le modèle : ses termes X et Y (transformations, catégories, termes croisés), leur mise à l'échelle, l'ajustement, puis R2 et Q2, T2 et DModX avec leurs limites, VIP, coefficients (ceux d'une PLS avec leur intervalle à 95 % par jack-knife), RMSEE et RMSEcv, CV-ANOVA, classement pour une PLS-DA, jeu de test ;
4. les résultats : les tableaux, le test de permutation (en commentaire) et les graphiques (scores, loadings, VIP, observé / ajusté, T2 et DModX).

Format : script R (.R) ; ou rapport R Markdown (.Rmd) ou Quarto (.qmd), qui y ajoute le texte des méthodes, des tableaux et des graphiques (scores, loadings, VIP, observé / prédit, T2, DModX) et les références ; il se compile dans RStudio (bouton Knit) ou avec quarto render, et demande le paquet knitr. Fichiers en plus, au choix : renv.lock (versions de R et des paquets, pour renv::restore()), les données et le modèle ajusté en .RData (load() les rend sans recalculer), un projet RStudio (.Rproj, à mettre dans un dossier à part).

Modèles : celui-ci, ou tous les modèles de la séance (le dernier ajustement de chacun) dans un seul script .R : les fonctions et les données une fois, puis un bloc par modèle sous son nom (M1, M2...).

Avant d'écrire, l'application recalcule les modèles du script et vérifie qu'ils donnent les mêmes résultats ; sinon elle le signale.

Console R

Affichage › Console R (Ctrl+J) : un panneau sous les onglets, avec

• le journal : pour chaque action de l'application, l'appel au moteur qu'elle a fait, écrit en R (P1 <- lire_projet(...), d <- modele_du_projet(P1, 5), M4 <- ajuster(P1, d)...), à recopier dans un script (bouton Copier), et pour chaque modèle ajusté ce que R en affiche (composantes, Y, limites, variables, observations ; print(M4) fait de même) ; la case « Actions de l'application » les masque ou les montre ;

• une invite où taper du R, exécuté dans la session R de l'application. m est le modèle affiché, p son projet ; P1, M4... les projets et modèles ouverts, sous les noms du journal. Par exemple : m$statistiques$variables, summary(p$donnees), plot(m$T[, 1], m$T[, 2]) (le graphique s'affiche dans la console), modeles(), projets(), definition("M4").

  Entrée lance la commande, Maj+Entrée passe à la ligne, ↑ et ↓ rappellent les commandes.

  Tab complète le nom commencé : objets, m$... et p$... (les noms qu'ils contiennent), arguments de la fonction dont la parenthèse est ouverte ; s'il y en a plusieurs, une liste s'ouvre (flèches, puis Tab ou Entrée). Les raccourcis de l'application (Ctrl+S, Ctrl+K...) fonctionnent aussi pendant qu'on tape.

Modifier un projet dans la console (p$donnees[...] <- ...) le modifie dans l'application. Corriger le moteur : dossier_moteur() donne le dossier des fichiers R de l'application ; après une correction, recharger_moteur() les relit, puis réajuster le modèle. Une mise à jour de Nuée remplace ces fichiers.

Une commande longue bloque l'application jusqu'à la fin du calcul.

Vérifier le moteur : verifier_moteur() recalcule les modèles importés des projets ouverts, validés comme leurs fichiers, et les compare aux valeurs enregistrées dans leurs fichiers (R2X, R2Y, Q2) ; verifier_moteur("dossier") fait de même pour les fichiers .usp et .json d'un dossier. À faire après une correction du moteur. Le Q2 entre dans le verdict, sauf celui d'une ACP, seulement proche (voir « Ce qui diffère »).

Le code

Tous les calculs sont dans resources\moteur\R (R, commenté en français) :

pretraitement.R        transformations, centrage, mise à l'échelle
nipals.R               ACP et PLS (algorithme NIPALS, données manquantes)
validation_croisee.R   validation croisée (trois façons), Q2
hierarchique.R         modèles hiérarchiques : Q2 honnête (modèles de base refaits)
regression.R           modèles de régression (lm, nlme, mgcv), AIC, apport des blocs
statistiques.R         T2, DModX, VIP, coefficients, intervalles, limites
validation.R           permutations, CV-ANOVA, classement PLS-DA et courbes ROC
opls.R                 OPLS et OPLS-DA
diagnostic.R           contributions, vérification des données, statistiques des variables
variables.R            scores en variables, classes, valeurs modifiées, variables calculées
projet.R               lecture des projets, historique du fichier
verification.R         comparaison avec les résultats enregistrés dans les fichiers .usp
script.R               export d'un modèle en script ou rapport R autonome
methodes.R             texte des méthodes et références
comparaisons.R         tests statistiques
modeles_classe.R       modèles de classe (une ACP par classe), graphique de Coomans
formats.R              lecture et écriture des tableaux (Excel, texte, R, SPSS, Stata, SAS, jamovi...)
spectres.R             prétraitement des spectres (SNV, MSC, detrend, ligne de base, Savitzky–Golay)
fichiers_spectres.R    lecture des spectres (JCAMP-DX, SPC, texte), informations jointes
jeu_test.R             jeu de test : prédiction, RMSEP, Q2 externe, Kennard–Stone
condition.R            les observations d'un modèle choisies par une condition
langue.R               langue des messages (traduire("français", "English"))
modele.R, prediction.R, classification.R (HCA), nouveau.R (tableaux, autoajustement)

Dans R : source("resources/moteur/charger.R"), puis par exemple

load.R charge le même moteur en anglais (ses messages, statuts et noms de colonnes), avec des noms anglais : import_table(), define_model(), fit_model().