spb/traite-evaluation-qc

1# CONVENTIONS.md — Règles de rédaction et de production (obligatoires)23Ce document s'adresse à toute personne ou agent qui rédige un chapitre, un script, une figure ou une solution. Il complète `CLAUDE.md` (mission) et prévaut sur les habitudes personnelles. **Lire en entier avant d'écrire.**45## 1. Arborescence et propriété des fichiers67| Élément | Emplacement | Règle |8|---|---|---|9| Chapitre *N* | `manuscript/chapters/chNN.tex` | un seul fichier par chapitre ; commence par `\chapter{Titre}\label{ch:NN}` (titre : `manuscript/chapters/TITRES.json`) |10| Solutions du chapitre | `solutions/chNN.tex` | une `\begin{solution}{ex:NN:k}{titre}` par exercice, dans l'ordre |11| Figures | `assets/figures/chNN/chNN-fig-<slug>.pdf` | PDF vectoriel produit par un script ; jamais de PNG sauf cartes raster |12| Scripts de figures | `analysis/python/figures/chNN_<slug>.py` (ou `analysis/r/chNN_<slug>.R`) | idempotents ; `python3 analysis/python/figures/chNN_x.py` depuis la racine |13| Calculs d'exemples | `analysis/python/cases/chNN_<slug>.py` | impriment les chiffres cités dans le texte ; testés dans `analysis/python/tests/test_chNN.py` |14| Données synthétiques | `data/synthetic/<nom>.csv` + `data/synthetic/README.md` | générées par `analysis/python/cases/generate_all.py` ou un script dédié, **graine fixée** |15| Données réelles | `data/raw/` (brut, jamais modifié) → `data/processed/` | uniquement sources publiques et libres (Statistique Canada, Banque du Canada, Données Québec, SCHL tableaux publics) avec `data/raw/SOURCES.md` (URL, licence, date) |16| Bibliographie | `references/library.bib` | clés existantes réutilisées ; nouvelle entrée = vérifiée (URL/DOI, `urldate`) |17| Registres | `sources/registry.csv`, `verification/{claims,calculations,figures}.csv` | une ligne par source, affirmation vérifiée, calcul, figure |1819Le chapitre doit compiler seul : `tools/compile_chapter.sh NN` (0 erreur, 0 référence non définie, idéalement 0 overfull hbox). **Ne jamais déclarer un chapitre terminé sans avoir exécuté cette commande et lu le résumé.**2021## 2. Structure obligatoire d'un chapitre (ordre)22231. `\chapter{…}\label{ch:NN}` puis un paragraphe d'ouverture (3-6 phrases : enjeu, place dans l'ouvrage).242. `\begin{objectifs}` : 4 à 7 puces « À la fin de ce chapitre, le lecteur sait… ».253. Sections numérotées (`\section`, `\subsection` ; pas de `\subsubsection` au-delà du nécessaire). Dérivations complètes, équations numérotées (`equation`/`align`, étiquettes `eq:NN:slug`), définitions dans `definition`, résultats dans `theoreme`/`proposition` avec `proof`.264. Au moins un **exemple intégral** (`exemple`) dont chaque chiffre provient d'un script de `analysis/python/cases/` (nommer le script dans le texte ou dans `\tabsource`).275. Au moins deux **figures** (si justifié) et des **tableaux** (unités dans les en-têtes, `\tabsource{}` sous le tableau, `\figsource{}` sous la légende).286. Une **analyse de sensibilité** (tableau ou figure).297. `\begin{quebec}` : règles, institutions, données propres au Québec avec source et date de consultation.308. `\begin{erreurs}` (erreurs fréquentes) et `\begin{limites}`.319. `\begin{synthese}` (à retenir).3210. `\section*{Exercices}` : 4 à 8 exercices de difficulté croissante (`\begin{exercice}[niveau 1-3]{Titre}{ex:NN:k}`), **sans solution dans le chapitre**.3311. `\section*{Pour aller plus loin}` : bibliographie commentée (3-8 titres, `\textcite`/`\parencite`).3435Cible : **9 000 à 14 000 mots** par chapitre (prose), 3-6 figures, 4-8 tableaux, 8-15 équations numérotées, 2-4 exercices de niveau 3. Les chapitres de cas (45-48) sont plus longs (12 000-18 000 mots) et plus riches en tableaux.3637## 3. Style rédactionnel3839- **Français québécois soutenu**, prose magistrale. Les listes à puces sont réservées aux objectifs, aux synthèses, aux étapes de calcul et aux listes de contrôle ; tout le reste est en paragraphes développés.40- Vouvoiement proscrit ; « le lecteur », « l'évaluateur », « l'analyste ». Pas d'anglicismes non nécessaires ; l'équivalent anglais est donné une fois entre parenthèses puis au glossaire : revenu net d'exploitation (RNE, *net operating income*).41- Sigles français : RNE (NOI), RCD (DSCR), RPV (LTV), TRI (IRR), VAN (NPV), REB/RBE (revenu brut effectif), RBP (revenu brut potentiel), PHMU (plus haute et meilleure utilisation), MRB (multiplicateur du revenu brut), taux global d'actualisation (TGA) = taux de capitalisation global.42- Distinguer toujours : **prix** (observé), **valeur marchande** (estimation), **valeur au rôle** (fiscale, date de référence), **valeur d'investissement** (propre à un investisseur), **coût**. Ne jamais écrire « la valeur est de… » pour un prix observé.43- Distinguer **exigence professionnelle** (norme OEAQ/IVS/CUSPAP), **droit applicable** (loi, règlement, jurisprudence), **pratique courante** et **modèle expérimental**. Formules : « la norme exige », « la loi prévoit », « il est d'usage », « on peut modéliser ».44- Toute affirmation juridique cite l'article (ex. « art. 1955 C.c.Q. ») et la source bibliographique, avec date de consultation si c'est une page web ; toute statistique cite l'organisme, le tableau et la période.45- **Rien d'inventé.** Pas de référence, de loi, de norme, de chiffre « plausible ». En cas de doute : écrire la chose comme non vérifiée dans `limites` et l'inscrire dans `verification/claims.csv` avec `statut=non_verifie`.4647## 4. Notation mathématique (uniforme dans tout l'ouvrage)4849| Objet | Symbole | Remarques |50|---|---|---|51| Prix observé du bien *j* | $P_j$ | prix de vente ; $P^{\text{aj}}_j$ prix ajusté |52| Valeur estimée | $\hat V$, $V_0$ (valeur présente), $V_T$ (valeur terminale) | |53| Ajustement *k* appliqué au comparable *j* | $A_{jk}$ (monétaire), $a_{jk}$ (proportion) | comparaison : $P^{\text{aj}}_j = P_j + \sum_k A_{jk}$ ; multiplicatif : $P_j\prod_k(1+a_{jk})$ |54| Hédonique | $\ln P_i = \alpha + \mathbf{x}_i\T\boldsymbol\beta + \tau_{t(i)} + \mu_{s(i)} + \varepsilon_i$ | $\tau$ effets temporels, $\mu$ effets spatiaux |55| Coût | $V = V_L + C_N - D_{\text{phys}} - D_{\text{fonc}} - D_{\text{ext}}$ | $V_L$ terrain, $C_N$ coût neuf |56| Revenus | $RBP$, $RBE = RBP - V\&P + R_{\text{autres}}$, $\NOI = RBE - DE$ | $V\&P$ vacance et mauvaises créances ; $DE$ dépenses d'exploitation ; réserves : explicites |57| Capitalisation directe | $V = \NOI_1 / R$ | $R$ taux global ; $\NOI_1$ = première année (prospectif) |58| DCF | $V_0 = \sum_{t=1}^{T} \dfrac{CF_t}{(1+r)^t} + \dfrac{V_T - c_v V_T}{(1+r)^T}$ | $r$ taux d'actualisation, $c_v$ coûts de vente ; $V_T = \NOI_{T+1}/R_T$ |59| Financement | $\LTV = M_0/V_0$, $\DSCR = \NOI/SD$ | $SD$ service de la dette annuel ; hypothèques canadiennes : composition **semestrielle** |60| Taux | $i$ nominal annuel, $i_m$ périodique, $R$ capitalisation, $r$ actualisation, $g$ croissance | $R \approx r - g$ (démontrer les hypothèses) |61| Statistique | $\E$, $\Var$, $\Cov$, $\hat\beta$, $\sigma^2$, IC à 95 % | « intervalle de crédibilité » pour le bayésien |6263Macros disponibles (`styles/traite-qc.sty`) : `\NOI` (RNE), `\VAN`, `\TRI`, `\DSCR` (RCD), `\LTV` (RPV), `\E`, `\Var`, `\Cov`, `\T` (transposée), `\argmin`, `\dd`, `\abs{}`, `\norm{}`.6465## 5. Unités et nombres (siunitx, conventions québécoises)6667- `\dollars{452500}` → 452 500 $ ; `\pct{4.75}` → 4,75 % ; `\parmsq{3250}` → 3 250 $/m² ; `\msq{145}` ; `\pisq{1560}` ; `\num{1234.5}` ; `\qty{12}{\logement}`.68- Dans les tableaux, colonnes `S[table-format=7.0]` pour les nombres, unité dans l'en-tête entre accolades : `{Prix (\$)}`.69- Superficies en m² (pi² en second si utile) ; conversion 1 m² = 10,7639 pi². Taux : pourcentage annuel, deux décimales ; points de base `\qty{25}{\pb}`.70- Dates : « 1^er^ juillet 2025 » en toutes lettres dans la prose ; ISO (2025-07-01) dans les tableaux et CSV.71- Dollars canadiens courants ; préciser l'année de référence des coûts et des prix.7273## 6. Figures7475- Palette et style **imposés** : `from traite.style import setup, palette` (`analysis/python/traite/style.py`) ; `setup()` configure Matplotlib (Source Sans 3, surface #fcfcfb, grille discrète, 2 pt de trait). Couleurs par le rôle : catégoriel `palette.cat[i]` (ordre fixe, max 6 séries, max 3 dans un nuage de points), séquentiel `palette.seq` (bleu clair→foncé), divergent `palette.div` (bleu–gris–rouge). Pas de double axe y. Pas d'arc-en-ciel. Une légende dès 2 séries, étiquettes directes quand c'est lisible, texte en encre (jamais de la couleur de la série).76- Dimensions : largeur 135 mm (pleine colonne) ou 65 mm (demi) ; `fig.savefig(path, bbox_inches="tight")` ; polices 8-9 pt.77- Légende LaTeX : `\caption{Phrase complète qui dit ce que montre la figure et ce qu'il faut y voir.}` puis `\figsource{\synth{script analysis/python/figures/chNN_x.py, graine 20261031}}` ou `\figsource{Statistique Canada, tableau 18-10-0205-01, consulté le 2026-10-31 ; calculs de l'auteur}`.78- Chaque figure est inscrite dans `verification/figures.csv` : `fichier,chapitre,script,donnees,type_donnees(synthetique|reelle|schema),legende_courte,statut`.79- Schémas conceptuels : TikZ directement dans le `.tex` (type `schema`), aussi inscrits dans figures.csv (script = fichier tex).8081## 7. Tableaux8283`booktabs` (`\toprule/\midrule/\bottomrule`), jamais de filets verticaux. `\caption` au-dessus, `\label{tab:NN:slug}`, `\tabsource{}` dessous. Unités dans les en-têtes. Tableaux longs : `longtable`. Les chiffres proviennent d'un script : le nommer dans `\tabsource`.8485## 8. Données synthétiques et réelles8687- Toute donnée simulée est identifiée : encadré `synthetique` à sa première apparition dans le chapitre (nom du fichier, script, graine, principes de calibration avec sources), `\synth{}` dans chaque `\tabsource`/`\figsource` qui en dépend, et mention `[données synthétiques]` dans la légende courte de figures.csv.88- Les paramètres de calibration (ordres de grandeur réalistes) sont documentés dans `data/synthetic/calibration.json` avec, pour chaque valeur, un `source_id` du registre. Une valeur sans source est marquée `"source_id": "NON_VERIFIE"` et signalée.89- Les quatre dossiers de cas : `data/synthetic/cas1_gatineau_*.csv`, `cas2_quebec_triplex_*.csv`, `cas3_montreal_12log_*.csv`, `cas4_portefeuille_*.csv` ; générés par `analysis/python/cases/generate_all.py`. Les chapitres 16-44 **réutilisent ces dossiers** pour leurs exemples quand c'est pertinent (cohérence des chiffres entre chapitres).9091## 9. Citations et sources9293- `\textcite{clé}` (sujet de phrase) / `\parencite{clé}` (parenthèse) ; lois : `\parencite[art.~1955]{ccq}`.94- Les clés existantes (`references/library.bib`) sont réutilisées ; une nouvelle entrée exige : titre exact, auteur/organisme, année, éditeur ou revue, DOI ou URL, `urldate`, `note` (version, date d'entrée en vigueur). Les entrées non vérifiées ne sont pas ajoutées : elles sont listées dans `verification/claims.csv` avec `statut=non_verifie`.95- Pas de reproduction de tableaux protégés (RSMeans, Marshall & Swift, normes OEAQ/IVS in extenso). On cite, on paraphrase, on renvoie.96- Registre des sources : `sources/registry.csv` (`id,type,titre,organisme,version_ou_date,url,date_consultation,statut,utilise_dans,notes`) ; `statut ∈ {verifie, partiellement_verifie, non_verifie, inaccessible}`.9798## 10. Vérification des calculs99100- Chaque exemple chiffré a un script `analysis/python/cases/chNN_<slug>.py` qui recalcule et **imprime** les valeurs ; un test `analysis/python/tests/test_chNN.py` vérifie les identités (ex. VAN au TRI = 0, solde d'amortissement nul, $V = \NOI/R$, somme des ajustements = écart ajusté) et les valeurs citées (tolérance déclarée).101- Inscrire chaque calcul dans `verification/calculations.csv` : `id,chapitre,description,script,test,resultat_attendu,resultat_obtenu,statut,date`.102- La bibliothèque commune `analysis/python/traite/` (finance, coût, comparables, hédonique, synthèse) est la **seule** source des formules financières : ne pas réécrire une fonction qui y existe ; l'enrichir (avec tests) si une fonction manque.103104## 11. Ce qui est interdit105106Placeholders (« à compléter », « lorem »), figures sans script, chiffres sans provenance, lois ou normes citées sans vérification, tableaux copiés de sources protégées, réordonnancement du plan sans décision de l'auteur, modification de `styles/` ou de `main.tex` par un rédacteur de chapitre (demander), compilation « supposée réussie ».107108## 12. Livraison d'un chapitre (liste de contrôle)109110- [ ] `tools/compile_chapter.sh NN` : OK, 0 référence non définie, overfull ≤ 3111- [ ] `python3 -m pytest -q analysis/python/tests/test_chNN.py` : vert112- [ ] figures PDF présentes + lignes dans `verification/figures.csv`113- [ ] lignes dans `verification/calculations.csv` et `verification/claims.csv`114- [ ] nouvelles sources dans `sources/registry.csv` + `references/library.bib`115- [ ] `solutions/chNN.tex` complet (une solution par exercice, calculs détaillés)116- [ ] rapport bref dans `verification/chapters/chNN.md` : mots, figures, tableaux, équations, exercices, points non vérifiés117