evalhyd.vigicrues.evalp

evalp(df_obs, df_prd, metrics, q_thr=None, events=None, c_lvl=None, q_lvl=None, t_msk=None, m_cdt=None, bootstrap=None, seed=None, diagnostics=None, return_format='dataframe')

Fonction pour évaluer des predictions probabilistes de débits.

Warning

La cohérence des unités pour les paramètres correspondant à des débits (à savoir df_obs, df_prd, q_thr, m_cdt) est de la responsabilité de l’utilisateur.rice. En effet, aucune vérification n’est effectuée par cette fonction.

Note

L’étendue temporelle des données d’observations fournies peut être plus large que celle des données de prédictions fournies : la fonction effectue la sélection des dates d’observations nécessaires pour évaluer les prédictions.

Paramètres:

df_obs: pandas.DataFrame

La dataframe contenant les observations de débits. Elle doit posséder un multi-index en lignes avec quatre niveaux nommés ‘entites’ et ‘dates_validite’ (respectivement de types str et pd.Timestamp) et une colonne nommée ‘valeur’ (de type float) contenant des débits dans une unité identique à celle de df_prd et q_thr. dimensions : (entités, temps)

Exemple de paramètre :

import numpy as np
import pandas as pd

df_obs = pd.DataFrame(
    data=np.random.randint(100, 400, 6),
    index=pd.MultiIndex.from_product(
        [['entité 1', 'entité 2', 'entité 3'],
         [pd.to_datetime('2001-08-07'), pd.to_datetime('2001-08-08')]],
        names=['entite', 'date_validite']
    ),
    columns=pd.Index(['valeur'])
)

df_prd: pandas.DataFrame

La dataframe contenant les prédictions de débits. Elle doit posséder un multi-index pour les lignes avec quatre niveaux nommés ‘entites’, ‘echeances’, ‘membres’/’tendances’ et ‘dates_validite’ (respectivement de types str, pd.Timedelta, str et pd.Timestamp) et une colonne nommée ‘valeur’ (de type float) contenant des débits dans une unité identique à celle de df_obs et q_thr. dimensions : (entités, échéances, membres/tendances, temps)

Exemple de paramètre :

import numpy as np
import pandas as pd

df_prd = pd.DataFrame(
    data=np.random.randint(100, 400, 24),
    index=pd.MultiIndex.from_product(
        [['entité 1', 'entité 2', 'entité 3'],
         [pd.to_timedelta('1 day')],
         ['a', 'b', 'c', 'd'],
         [pd.to_datetime('2001-08-07'), pd.to_datetime('2001-08-08')]],
        names=['entite', 'echeance', 'membre', 'date_validite']
    ),
    columns=pd.Index(['valeur'])
)

metrics: List[str]

La liste d’indicateurs d’évaluation à calculer. dimensions : (indicateurs,)

Voir aussi

Indicateurs probabilistes

q_thr: numpy.ndarray [dtype('float64')], optionnel

La matrice 2D contenant le(s) seuil(s) de débits à considérer pour les indicateurs évaluant les prédictions de dépassement de seuils. Si le nombre de seuils diffère entre les entités, numpy.nan peut être utilisé comme seuil pour les entités ayant moins de seuils que les autres. dimensions : (entités, seuils)

events: str, optionnel

Le type de dépassement de seuil à considérer pour les indicateurs basés sur des seuils de dépassement. Il peut être défini soit comme "high" pour l’évaluation d’événements de crues (c’est-à-dire quand le débit passe au-dessus du seuil) soit comme "low" pour l’évaluation d’événements d’étiages (c’est-à-dire quand le débit passe en-dessous du seuil). Il doit être fourni si q_thr est fourni.

c_lvl: numpy.ndarray [dtype('float64')], optionnel

Le vecteur d’intervalle(s) de confiance en pourcents à considérer pour les indicateurs basés sur des intervalles. dimensions : (intervalles,)

q_lvl: numpy.ndarray [dtype('float64')], optionnel

Le vecteur de quantiles auxquels correspondent les membres de l’ensemble. S’ils ne sont pas fournis, les quantiles sont déduits du nombre de membres qui sont considérés comme équiprobables. dimensions : (membres,)

t_msk: numpy.ndarray [dtype('bool')], optionnel

La matrice 4D contenant les masques permettant des générer des sous-ensembles des chroniques de débits (où True/ False est utilisé pour inclure/exclure les pas de temps dans un sous-ensemble donné). Si la matrice n’est pas fournie et m_cdt n’est pas fournie non plus, aucun sous-ensemble n’est produit et un seul jeu d’indicateurs correspondant à la période entière est généré. Si la matrice est fournie, autant de jeux d’indicateurs que de masques fournis sont générés. dimensions : (entités, échéances, sous-ensembles, temps)

m_cdt: numpy.ndarray [dtype('|S32')], optionnel

La matrice 2D contenant les conditions permettant de générer des sous-ensembles temporels. Chaque condition consiste en une chaîne de caractères et elle peut être spécifiée sur des valeurs débits observés ou prédits (moyenne, médiane, quantile) ou sur des indices temporels. Si la matrice est fournie et t_msk est également fourni, ce dernier est prioritaire et la matrice sera ignorée. Si la matrice n’est pas fournie et t_msk n’est pas fourni non plus, aucun sous-ensemble n’est produit et un seul jeu d’indicateurs correspondant à la période entière est généré. Si la matrice est fournie seule, autant de jeux d’indicateurs que de conditions fournies sont générés. dimensions : (entités, sous-ensembles)

bootstrap: dict, optionnel

Les valeurs des paramètres pour la méthode de bootstrap utilisée pour estimer l’incertitude d’échantillonnage dans l’évaluation des prédictions. Les trois paramètres sont : "n_samples" le nombre d’échantillons aléatoires, "len_samples" la longueur d’un échantillon en nombre d’années et "summary" les statistiques à calculer pour caractériser la distribution d’échantillonnage. Si les valeurs ne sont pas fournies, aucun bootstrap n’est effectué.

Exemple de paramètre :

bootstrap={"n_samples": 100, "len_sample": 10, "summary": 0}

seed: int, optionnel

Un nombre entier pour la graine utilisée par le générateur pseudo-aléatoire. Ce paramètre garanti la reproductibilité des valeurs d’indicateurs entre appels à la fonction.

diagnostics: List[str], optionnel

La liste de variables de diagnostic de l’évaluation à calculer. dimensions : (variables,)

return_format: str, optionnel

Le format désiré pour les indicateurs d’évaluation, soit 'dataframe' pour obtenir des pandas.DataFrame ou 'array' pour obtenir des numpy.ndarray. Si le format n’est pas fourni, des dataframes sont retournées.

Retourne:

dict de pandas.DataFrame ou de numpy.ndarray

Les valeurs des indicateurs d’évaluation (et des variables de diagnostic d’évaluation le cas échéant).

Note

Pour les indicateurs avec dimensions tels que le CRPS ou le QS, l’unité de l’indicateur est identique à l’unité des données fournies à df_obs, df_prd et q_thr.