# scodoc-cohortes *Visualisation des cohortes de BUT depuis scodoc* Ce programme utilise l'API pour générer des graphes de Sankey permettant de visualiser le devenir d'une cohorte. La notion de cohorte devient difficile à traiter lorsqu'on considère l'existence de passerelles permettant d'entrer à n'importe quel année d'étude. La vision proposée est de regarder tous les semestres consécutifs en partant d'une année de référence, et tous les élèves qui touchent ces semestres. On peut alors dégager divers indicateurs de sortie : * Sortie en BUT3 avec le diplôme * Sortie en BUT2 avec décision de jury positive (ADM/ADJ) qui implique normalement la possibilité de poursuivre ses études ailleurs * Autorisation de redoublement et l'élève revient * Sortie en BUT1 ou BUT2 avec la possibilité de continuer, mais l'élève ne revient pas * Autorisation de redoublement et l'élève ne revient pas * Toute autre sortie du flot de la cohorte Le premier type de sortie est assurément un succès, et c'est discutable pour le deuxième. Le taux de réussite est fourni par une fourchette. Le troisième type n'est ni une réussite ni un échec, et comptera plus tard comme une réussite ou un échec dans une cohorte ultérieure. Les trois derniers types, à des niveaux divers, sont des échecs. Le taux d'échec est donc fourni comme une fourchette entre le dernier type et la somme des trois derniers. Il existe un dernier type (qui tombe dans le 5 ou le 6 actuellement), c'est le cas d'un élève en BUT3 qui ne valide pas le BUT3, a validé le BUT2, et partirait dans une autre filière après. Le cas paraît beaucoup plus douteux que le deuxième type et est pour le moment classé en échec. ## Installation (Linux et MacOS) Créer un virtualenv: ```bash python3 -m venv venv source venv/bin/activate sudo apt install libcairo-dev ``` (n'importe quelle version de python récente fera l'affaire). Si vous êtes sur un système qui n'est pas de la famille Debian/Ubuntu, il faudra sans doute remplacer la dernière ligne par votre installeur de paquets préféré. Cette opération n'est à faire qu'une seule fois par machine. Puis installer les composants suivants dans ce virtualenv: ``` pip install -r requirements.txt ``` Puis indiquer votre configuration ScoDoc dans le fichier `.env`: ```bash SCODOC_SERVER=https://votre.serveur.fr SCODOC_USER=un_utilisateur_api SCODOC_PASSWORD=son_mot_de_passe ``` ## Installation (Windows) Exécuter un terminal depuis le répertoire où est installé le programme. Les commandes à taper dans l'interpréteur de commandes *PowerShell* sont : ```powershell python.exe -m venv venv venv\Scripts\Activate.ps1 pip install -r requirements.txt ``` Puis indiquer votre configuration ScoDoc dans le fichier `.env`: ```bash SCODOC_SERVER=https://votre.serveur.fr SCODOC_USER=un_utilisateur_api SCODOC_PASSWORD=son_mot_de_passe ``` Pycairo ne devrait pas s'installer. Si vous savez installer un pycairo fonctionnel pour Windows, n'hésitez pas à nous proposer de le rajouter à ces instructions. ### Note pour les développeurs Pour mettre à jour le fichier `requirements.txt`, lancer (après avoir activé l'environnement python) ```py pip freeze|sed -e '/pycairo/ s/$/; platform_system != "Windows"/g' > requirements.txt ``` ## Usage Après ouverture du terminal (une seule fois par terminal): ```bash source venv/bin/activate ``` Puis ```bash ./get.py [--options] dept ... ``` Il est possible d'utiliser aussi un fichier JSON qui contient soit un tableau associatif avec une clé nommée CLI qui est une liste de chaînes, soit directement une liste de chaînes. Ces chaînes remplacent simplement les arguments de la ligne de commande. ### Options principales |Option|Défaut|utilisation sommaire| |------|------|--------------------------------| | --baseyear,-b |2021| L'année de début de la cohorte | | --base_techno |Faux| L'effectif principal doit avoir un bac techno| | --base_women |Faux| L'effectif principal doit être féminin | | --secondary_techno |Vrai| L'effectif focus doit avoir un bac techno | | --secondary_women |Faux| L'effectif focus doit être féminin | | **--optimize** |Oui|Utilise un algorithme pour optimiser l'ordre des paquets en repartant de l'état précédent| | --reuse |Non| N'optimise pas l'ordre des paquets : réutilise le précédent (si présent)| | --restart|Non|Utilise un algorithme pour optimiser l'ordre des paquets| | --loops|300|Nombre d'itérations de l'algorithme| ## FICHIERS ### get.py C'est l'exécutable. Il prend en argument des acronymes de département (par exemple GEA ou INFO) et fabrique un graphe comportant les formations BUT de ce département (ou ces départements dans le même graphe, s'ils sont plusieurs sur la ligne de commande). Il faut un environnement virtuel pour que soient accessibles les bibliothèques Python pycairo, drawsvg, requests. A priori libcairo est optionnel, mais le graphe marchera moins bien sans. La bibliothèque (système) `libcairo2` doit aussi être installée (`apt install libcairo-dev` ou équivalent). ### redirect.csv Certains élèves ne reçoivent jamais de décision de jury lorsqu'ils quittent la cohorte, tout en n'étant pas démissionnaires. Ce sont des erreurs administratives, mais il est possible d'indiquer un *résultat de jury* **fictif** pour ces élèves. La plupart du temps, ce sont des élèves qui abandonnent la formation, et il suffit de leur donner le résultat NAR ou DEM. Dans d'autres cas, ça peut être des élèves en attente de décision parce que le jury n'a pas encore eu lieu, mais on sait déjà quel sera l'issue du jury (par exemple des notes élevés et un stage qui se déroule bien, ou au contraire pas de stage trouvé au mois de septembre). **Format :** format CSV avec virgule comme séparateur. Les lignes vides ou commençant par # sont ignorées. #etudid,BUCKET 12345,NAR 67890,ADM ### theme.csv Ce fichier offre la ossibilité de choisir les couleurs pour chacune des catégories. **Format :** format CSV avec virgule comme séparateur. Les couleurs sont au format de sankeymatic.com, soit le format hexadécimal d'HTML sauf la catégorie TRANSPARENT qui vaut #FFFFFF.0 (blanc transparent). Les catégories sont `+DUT`, `QUIT`, `SUCCESS`, `NORMAL`, `FAIL`, `OLD`, `NEW`, `TRANSPARENT`, `RED`. +DUT,#0040C0 QUIT,#00FF00 SUCCESS,#0000FF NORMAL,#C0C0C0 FAIL,#FF4040 OLD,#FF8000 NEW,#FFFF00 TRANSPARENT,#FFFFFF.0 RED,#000000 ### _x_y.json Ce fichier permet de mettre les options autrement que sur la ligne de commande, pour permettre une utilisation plus aisée (notamment en cas d'utilisation d'une autre interface pour générer les options). Les valeurs `x` et `y` sont basées sur les populations primaires et secondaires. **Format :** format JSON (utiliser un éditeur qui sait repérer les erreurs de format est recommandé). **Liste des clés :** * `cli` : liste de chaînes de caractères qui sont des options de la ligne de commande. ### .svg Ce fichier est la sortie du programme. C'est un graphique au format SVG, facile à incorporer dans des pages Web ou autres programmes de traitement de texte. ### best-.json Ce fichier contient le résultat d'une recherche heuristique pour avoir un graphe visuellement plus satisfaisant. Il peut être supprimé si le graphe ne s'améliore pas par des lancements successifs. Il peut aussi être modifié à la main. C'est essentiellement l'ordre des balises ### cache.json Un fichier global qui stocke de façon temporaire les données issues de scodoc. Il peut être supprimé sans pertes (sauf de temps).