evalhyd.vigicrues.evald

evald(df_obs, df_prd, metrics, transform=None, exponent=None, q_thr=None, events=None, epsilon=None, t_msk=None, m_cdt=None, bootstrap=None, seed=None, diagnostics=None, return_format='dataframe')

Fonction pour évaluer des predictions déterministes 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 index nommé ‘dates_validite’ (de type 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, 2),
    index=pd.Index(
        [pd.to_datetime('2001-08-07'), pd.to_datetime('2001-08-08')],
        name='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 deux niveaux nommés ‘echeances’ 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_obs et q_thr. dimensions : (entités, échéances, temps)

Exemple de paramètre :

import numpy as np
import pandas as pd

df_prd = pd.DataFrame(
    data=np.random.randint(100, 400, 2),
    index=pd.MultiIndex.from_product(
        [[pd.to_timedelta('1 day')],
         [pd.to_datetime('2001-08-07'), pd.to_datetime('2001-08-08')]],
        names=['echeance', 'date_validite']
    ),
    columns=pd.Index(['valeur'])
)

metrics: List[str]

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

Voir aussi

Indicateurs déterministes

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

Le vecteur contenant le(s) seuil(s) de débits à considérer pour les indicateurs évaluant les prédictions de dépassement de seuils. 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.

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

La matrice 2D 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, sous-ensembles, temps)

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

Le vecteur 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).