Utilisation¶

Cette section a pour objectif de guider les utilisateurs de SimGen dans l’utilisation de celui-ci. Dans un premier temps, les étapes d’utilisation et les différents choix possibles de paramètres sont présentés. Par la suite, un exemple de notebook/script est proposé afin de servir de point de départ aux utilisateurs pour le lancement de simulations et l’analyse des résultats.

Étapes¶

Lors de la rédaction d’un notebook ou d’un script Python, quatre étapes principales doivent être suivies afin d’obtenir des résultats de simulation avec SimGen:

1. Choix des paramètres d’utilisation¶

La première étapes consiste à choisir les paramètres qui guideront SimGen par rapport à la localisation de la base de données de départ et aux hypothèses de modélisation.

Chemin d’accès et nom du fichier de la BDSPS

Un premier paramètre d’utilisation à déterminer est le chemin d’accès et le nom du fichier .csv qui vous aura été fourni par l’équipe de la CREEi et qui correspond à une version épurée de la Base de données de simulation de politiques sociales (BDSPS). En début de notebook/script, il est suggéré de définir un objet qui comprend le chemin d’accès et le nom du fichier de la BDSPS selon l’endroit où vous aurez enregistré le fichier, et le nom que vous lui aurez donné:

donnees_brutes = '.../bdsps2017_slice.csv'

Cet objet servira d’intrant dans la fonction de formatage des données (bdsps_format()) à l’étape d’initialisation du modèle.

Année de fin

L’année de fin de la simulation détermine la durée des projections effectuées par SimGen. Les valeurs possibles vont de 2018 à 2100. La valeur minimale de l’année de fin correspond à 2018, puisque l’année de départ est fixée par défaut à 2017. Cette dernière valeur ne peut être choisie par l’utilisateur, puisque la base de données de départ date de 2017 et que l’année de départ doit correspondre à cette valeur.

Il est suggéré de définir, en début de notebook/script, un objet qui comprend l’année de fin choisie comme suit:

annee_fin = 2050

Cet objet sera utilisé à l’étape 2 lors du chargement des principaux intrants. Il en va de même pour tous les autres paramètres d’utilisation.

Nombre de réplications

Le nombre de réplications détermine le nombre de fois où SimGen simule l’ensemble de l’horizon de temps (année du début à l’année de fin) dans une simulation. Ce paramètre est fixé par défaut à 1. Lorsque le nombre de réplications est supérieur à 1, les résultats de la simulation correspondent à la moyenne des résultats des réplications.

Il est suggéré d’utiliser plus d’une réplication afin d’obtenir des résultats uniformes d’une simulation à une autre. Le nombre optimal de réplications varie selon les résultats utilisés. Les résultats précis comprenant un petit nombre d’observations (ex.: le nombre de personnes en couple de 95 ans) sont plus susceptibles de varier d’une simulation à une autre qu’un résultat global comportant un grand nombre d’observations (ex.: le nombre total de personnes en couple âgées de 15 à 65 ans). Les résultats précis nécessitent donc un plus grand nombre de réplications pour être stables (50 réplications) que les résultats globaux (10 réplications).

Il est suggéré de définir, en début de notebook/script, un objet qui comprend le nombre de réplications choisi comme suit:

nb_rep = 50

Hypothèses

Fécondité

Dans SimGen, il est possible de calibrer le nombre de naissances selon trois scénarios de fécondité issus du plus récent document de projection démographique de l’Institut de la statistique du Québec (ISQ). Les scénarios de fécondité supposent la convergence de l’indice synthétique de fécondité (ISF) vers les valeurs suivantes d’ici 2026, selon le scénario:

Fécondité	ISF
Faible (weak)	1,45
Référence (reference)	1,60
Forte (strong)	1,75

Dans le version actuelle de SimGen, les termes anglais weak, reference, et strong doivent être utilisés comme intrant dans la fonction d’hypothèse de fécondité. Il est suggéré de définir, en début de notebook/script, un objet qui comprend le nom du scénario de fécondité choisi comme suit:

fecondite = 'reference'

Mortalité

Il est possible de fixer les quotients de mortalité selon trois scénarios de mortalité issus du plus récent document de projection démographique de Statistique Canada. Les scénarios de mortalité supposent l’atteinte de trois valeurs possibles de l’espérance de vie à la naissance selon le genre d’ici 2062:

Mortalité	Hommes	Femmes
Faible (low)	89,8 ans	92,0 ans
Moyenne (medium)	87,5 ans	89,2 ans
Élevée (high)	85,9 ans	87,3 ans

En 2020, l’espérance de vie à la naissance est estimée à 80,6 ans pour les hommes et 84,0 ans pour les femmes (ISQ, mars 2021). Dans le version actuelle de SimGen, les termes anglais weak, medium, et strong doivent être utilisés comme intrant dans la fonction d’hypothèse de mortalité. Il est suggéré de définir, en début de notebook/script, un objet qui comprend le nom du scénario de mortalité choisi comme suit:

mortalite = 'low'

Immigration

Dans SimGen, le nombre de nouveaux immigrants par année est déterminé par le taux prospectif d’immigration internationale (proportion de nouveaux immigrants par rapport à la population totale). Ce paramètre est fixé par défaut à une valeur de 0,0066. Cette valeur correspond à 55 000 nouveaux immigrants internationaux en 2017 (sur une population totale de 8 302 063), conformément au scénario de référence du plus récent document de projection démographique de l’ISQ.

Le paramètre de taux prospectif d’immigration internationale peut être fixé à la valeur désirée (supérieure ou égale à 0). Ce paramètre reste toutefois fixe durant toutes les années de la simulation. Cette caractéristique implique une augmentation graduelle du nombre de nouveaux immigrants suivant la croissance de la population totale.

Si l’utilisateur souhaite modifier l’hypothèse d’immigration, il est suggéré de définir, en début de notebook/script, un objet qui comprend le taux d’immigration internationale choisi comme suit:

taux_immigration = 0.0066

Il est à noter que les caractéristiques des nouveaux immigrants sont celles des immigrants récents (depuis 5 ans ou moins) dans la BDSPS de 2017. Par ailleurs, la migration interprovinciale est prise en compte dans SimGen, mais il n’existe toutefois pas de paramètre d’utilisation par rapport à cet aspect (consultez la section Émigration pour les détails méthodologiques).

2. Initialisation du modèle¶

L’initialisation du modèle vise à charger en mémoire l’ensemble des informations nécessaires au lancement de la simulation. Cette étape se divise en plusieurs sous-étapes.

Importation des packages

SimGen utilise certains packages Python standards, qu’il est nécessaire d’importer:

import warnings
import pandas as pd
import numpy as np
from matplotlib import pyplot as plt
warnings.filterwarnings("ignore")

Importation des fonctions et des classes de SimGen

Il est ensuite nécessaire d’importer SimGen en tant que tel:

import simgen
from simgen import model, formating

Formatage données de départ

La fonction bdsps_format transforme la BDSPS de Statistique Canada afin de mettre en forme certaines variables et créer les registres des individus (dominants, conjoints et enfants). Cette fonction calibre également les poids des répondants, par âge et sexe, afin de s’arrimer à la population québécoise de 2017, selon l’ISQ. Enfin, cette fonction sauvegarde la base de données de départ en format pkl en lui donnant le nom de « startpop » et sauvegarde la banque de données des caractéristiques des nouveaux immigrants en format pkl en lui donnant le nom de « imm_pop ». La commande à utiliser est comme suit:

preparation_data=formating()
preparation_data.bdsps_format(donnees_brutes)

où donnees_brutes correspond au chemin d’accès et au nom du fichier .csv de la BDSPS dans votre système (ex.: donnees_brutes = “…/bdsps2017_slice.csv”).

Détails: bdsps_format()

class simgen.bdsps¶

Nettoyage de la BDSPS.

Fonction qui permet de mettre en forme la BDSPS.

Paramètres

year (int) – année de la base de départ (défaut=2017)
iprint (boolean) – switch pour imprimer ou non des outputs intermédiaires de cette fonction (défaut=False)

Création de l’instance du modèle

La commande suivante crée un gabarit permettant entre autres de stocker les résultats propres à la simulation selon les paramètres d’utilisation choisis:

base = model(stop_yr=annee_fin)

où annee_fin correspond à l’année de fin de la simulation (ex.: annee_fin = 2050). Si l’argument stop_yr n’est pas spécifié, SimGen fixe par défaut l’année de fin à 2100.

Détails: classe model()

class simgen.model(start_yr=2017, stop_yr=2100)¶

Modèle de simulation SimGen.

Cette classe permet de créer une instance d’un modèle de microsimulation.

Paramètres

start_yr (int) – année de départ de la simulation (défaut=2017)
stop_yr (int) – dernière année de la simulation (défaut=2100)

Pour être en mesure de lancer une deuxième simulation avec des paramètres d’utilisation différents et de comparer les résultats des deux simulations, vous n’avez qu’à réutiliser cette commande en donnant un nom différent au gabarit:

base2 = model(stop_yr=annee_fin)

et de suivre les mêmes étapes de programmation que pour le premier gabarit (base).

Chargement des principaux intrants

Tout d’abord, le chargement de la base de données de départ s’effectue à l’aide de la commande suivante:

base.startpop('start_pop')

où start_pop est le nom donné par défaut à la base de données de départ à la suite du formattage de la BDSPS. Ce nom exacte doit être utilisé, puisqu’un message d’erreur vous sera envoyé en cas contraire.

Détails: fonction startpop()

class simgen.model(start_yr=2017, stop_yr=2100)

Modèle de simulation SimGen.

Cette classe permet de créer une instance d’un modèle de microsimulation.

Paramètres

start_yr (int) – année de départ de la simulation (défaut=2017)
stop_yr (int) – dernière année de la simulation (défaut=2100)

startpop(file)¶

Charger une population de départ.

Fonction membre qui permet de charger une population de départ.

Paramètres: file (str) – nom du fichier contenant la population de départ

Le chargement des hypothèses de la simulation s’effectue ensuite à l’aide des commandes suivantes et des objets définis à l’étape 1 (taux_immigration, fecondite, mortalite):

base.birth_assumptions(scenario=fecondite)
base.dead_assumptions(scenario=mortalite)
base.immig_assumptions(init='imm_pop', num=taux_immigration)

où imm_pop correspond à la la banque de données des immigrants récents produite par la fonction bdsps_format(). Ce nom exacte doit être utilisé pour l’argument init, puisqu’un message d’erreur vous sera envoyé en cas contraire. Si les arguments scenario des fonctions birth_assumptions et dead_assumptions ne sont pas spécifiés, SimGen utilise par défaut le scénario de fécondité de référence (reference) et le scénario de mortalité moyenne (medium). Pour l’immigration, SimGen fixe par défaut le taux d’immigration internationnale à 0,0066, si l’argument num n’est pas spécifié.

Détails: fonction _assumptions()

class simgen.model(start_yr=2017, stop_yr=2100)

Modèle de simulation SimGen.

Cette classe permet de créer une instance d’un modèle de microsimulation.

Paramètres

start_yr (int) – année de départ de la simulation (défaut=2017)
stop_yr (int) – dernière année de la simulation (défaut=2100)

birth_assumptions(scenario='reference', align=True)¶

Hypothèses de fécondité.

Fonction membre qui permet de spécifier les hypothèses de fécondité.

Paramètres

scenario (str) – Permet de choisir entre les différents scénarios de fécondité produits pas l’ISQ (weak, reference, strong)
aling (boolean) – paramètre permettant d’aligner le nombre d’immigrants sur l’ISQ

dead_assumptions(scenario='medium')¶

Hypothèses de mortalité.

Fonction membre qui permet de spécifier les hypothèses de mortalité.

Paramètres: scenario (str) – Permet de choisir entre les différents scénarios de mortalité produits pas l’STC (low, medium, high)

immig_assumptions(allow=True, num=0.0066, init=None)¶

Hypothèses d’immigration.

Fonction membre qui permet de spécifier les hypothèses d’immigration.

Paramètres

allow (boolean) – paramètre permettant d’aligner le nombre d’immigrants sur l’ISQ
num (float) – immigration totale (nombre); par défaut, scénario de référence de l’ISQ
init (str) – nom du fichier contenant la population d’immigrants

3. Lancement de la simulation¶

Le lancement de la simulation s’effectue à l’aide de la fonction suivante:

base.simulate(rep=nb_rep)

où nb_rep correspond au nombre de réplications de la simulation (ex.: nb_rep = 50). Si l’argument rep n’est pas spécifié, SimGen fixe par défaut le nombre de réplications à 1.

Il est à noter que cette commande a un temps d’exécution plus élevé que les commandes présentées précédemment. Le temps de simulation croît de manière substantielle avec l’année de fin et le nombre de réplications.

Détails: fonction simulate()

class simgen.model(start_yr=2017, stop_yr=2100)

Modèle de simulation SimGen.

Cette classe permet de créer une instance d’un modèle de microsimulation.

Paramètres

start_yr (int) – année de départ de la simulation (défaut=2017)
stop_yr (int) – dernière année de la simulation (défaut=2100)

simulate(rep=1)¶

Fonction déclenchant le lancement de la simulation.

Paramètres: stratas (rep) – Nombre de réplications

4. Production des résultats¶

Tout d’abord, le tableau ci-dessous présente la liste des variables pouvant servir lors de l’affichage des résultats de SimGen:

Variable	Nom	Type	Valeurs	Étiquette
Âge	age	Entier	0 à 110
Genre	male	Booléen	True False	Homme Femme
Statut d’études	insch	Booléen	True False	Aux études Études terminées
Scolarité complétée	educ	Caractères	none des dec uni	Sans diplôme Secondaire Collégial Universitaire (bacc. et supérieur)
Statut conjugal	married	Booléen	True False	En union Célibataire
Nombre d’enfants	nkids	Entier	0 à 3

Il est possible de produire deux types de résultats: 1) des fréquences et 2) des proportions.

Fréquences

La fonction stats.freq() calcule le nombre d’individus selon le sous-groupe spécifié. Par exemple:

population_hommes=base.stats.freq(sub='male==True')

Si l’argument sub n’est pas spécifié, la fonction renvoie le nombre de personnes dans l’ensemble de la population.

Détails: fonction stats.freq()

class simgen.statistics(stratas)¶

Classe pour créer les statistiques provenant d’une simulation.

Cette classe permet de capturer la distribution de la population par strate durant une simulation. Elle permet ensuite de faire plusieurs tableaux dynamiques à partir de ces distributions.

Paramètres: stratas (list of str) – liste des noms de variables du fichiers de dominants afin de stratifier la population et récolter les fréquences (pondérées)

freq(strata=None, bins=[0], sub=None)¶

Fonction de fréquences.

Fonction qui permet, à l’aide de counts, de calculer les fréquences pondérées pour une strate donnée. Deux options sont disponibles: l’une, bins, permet de modifier les catégories de la strate (par exemple le groupe d’âge), tandis que sub permet de définir un critère de sélection particulier pour le calcul des fréquences (en str).

Paramètres

strata (str) – nom de la variable par laquelle on veut découper les données; ne pas spécifier cette option revient à demander les fréquences totales
bins (list of int) – liste de valeurs pour découper les données selon la variable strata; fonctionne seulement avec des variables de types int (pas de str)
sub (str) – condition à respecter pour un sous-échantillon, p.ex. « age>=18 »

Renvoie

dataframe avec les fréquences par année (ligne) et valeur de la strate (colonne)

Type renvoyé

dataframe

Proportion

La fonction stats.prop() calcule pour sa part la proportion de la population respectant les caractéristiques spécifiées. Par exemple:

proportion_niveau_scolarite = base.stats.prop('educ', sub="age>=25 and age<=64 and insch==False")

Si l’argument sub n’est pas spécifié, la fonction renvoie la proportion de personnes selon les catégories de la variable spécifiée dans l’ensemble de la population.

Détails: fonction stats.prop()

class simgen.statistics(stratas)

Classe pour créer les statistiques provenant d’une simulation.

Cette classe permet de capturer la distribution de la population par strate durant une simulation. Elle permet ensuite de faire plusieurs tableaux dynamiques à partir de ces distributions.

Paramètres: stratas (list of str) – liste des noms de variables du fichiers de dominants afin de stratifier la population et récolter les fréquences (pondérées)

prop(strata, bins=[0], sub=None)¶

Fonction de proportions.

Fonction qui permet, à l’aide de counts, de calculer les proportions pondérées pour une strate donnée. Deux options sont disponibles: l’une, bins, permet de modifier les catégories de la strate (par exemple le groupe d’âge), tandis que sub permet de définir un critère de sélection particulier pour le calcul des proportions (en str).

Paramètres

strata (str) – nom de la variable par laquelle on veut découper les données
bins (list of int) – liste de valeurs pour découper les données selon la variable strata; fonctionne seulement avec des variables de types int (pas de str)
sub (str) – condition à respecter pour un sous-échantillon, p.ex. « age>=18 »

Renvoie

dataframe avec les proportions par année (ligne) et valeur de la strate (colonne)

Type renvoyé

dataframe

Sauvegarde des données des résultats

Enfin, il est possible de sauvegarder les résultats de la simulation dans un fichier .pkl à l’aide de la commande suivante:

base.stats.save('.../resultats_simgen')

Détails: fonction save()

class simgen.statistics(stratas)

Classe pour créer les statistiques provenant d’une simulation.

Cette classe permet de capturer la distribution de la population par strate durant une simulation. Elle permet ensuite de faire plusieurs tableaux dynamiques à partir de ces distributions.

Paramètres: stratas (list of str) – liste des noms de variables du fichiers de dominants afin de stratifier la population et récolter les fréquences (pondérées)

save(file)¶

Fonction pour sauvegarder les fichiers de fréquences.

Paramètres: file (str) – nom du fichier de sauvegarde, incluant l’extension pkl (format pickle)

Pour une description complète des classes et des fonctions de SimGen, consultez la page Dictionnaire (classes et fonctions).

Exemple¶

Simulation de base¶

Cet exemple de notebook permet de se familiariser avec l’utilisation de Simgen en effectuant une simulation et en présentant des résultats de base.

Téléchargement du notebook:: Cliquez ici, puis sauvegardez le fichier en format .ipynb.
Accès au notebook via Google Colab*:: Cliquez ici:

Il est à noter qu’il est nécessaire de posséder un compte Google pour utiliser Google Colab.