Module mjoindices.evaluation_tools

This module provides several methods that help evaluate the agreement of the OMI calculation by this package and the original calculation by Kiladis et al. (2014). It is probably not of major relevance for the user of this package.

mjoindices.evaluation_tools.calc_comparison_stats_for_eofs_all_doys(eofs_ref: EOFDataForAllDOYs, eofs: EOFDataForAllDOYs, eof_number, exclude_doy366: bool = False, percentage: bool = False, do_print: bool = False) → Tuple[source]

Calculates extended comparison statistics between calculated EOFs and reference EOFs.

Parameters:

  • recalc_eof – The EOFs to validate.

  • orig_eof – The reference EOFs.

  • exclude_doy366 – If True, DOY 366 will be included in the calculation (sometimes worse agreement depending on the leap year treatment mode).

  • percentage – If True: calculation results will be in percent of the mean of the absolute reference values.

  • do_print – If True, some characteristic values will we printed to the console.

Returns:

A tuple containing arrays with 366 or 365 elements each for the following quantities: correlation, mean of the differences, standard deviation of the differences, and percentiles of the absolute differences for 68%, 95%, and 99%.

mjoindices.evaluation_tools.calc_comparison_stats_for_explained_variance(ref_var: ndarray, calc_var: ndarray, do_print: bool = False, exclude_doy366: bool = False) → Tuple[source]

Calculates the comparison statistics of the explained variances for one EOF and all DOYs.

Parameters:

  • ref_var – The reference variances.

  • calc_var – The variances to compare.

  • do_print – If True, some statistical values will also be shown in the console.

  • exclude_doy366 – If True, the data for DOY 366 will not be considered in the statistics.

Returns:

A tuple containing values for the following quantities: correlation, mean of the differences, standard deviation of the differences, and percentiles of the absolute differences for 68%, 95%, and 99%.

mjoindices.evaluation_tools.calc_timeseries_agreement(ref_data: ndarray, ref_time: ndarray, data: ndarray, time: ndarray, exclude_doy366: bool = False, do_print: bool = False) → Tuple[source]

Calculates comparison values of two time series.

Parameters:

  • ref_data – The reference time series vector.

  • ref_time – The time grid of the reference.

  • data – The time series vector to validate.

  • time – The time grid of the time series to validate. It will be checked if this is similar to the time grid of the reference.

  • exclude_doy366 – If True, the data for DOY 366 will not be considered in the statistics.

  • do_print – If True, some statistical values will also be shown in the console.

Returns:

A tuple containing values for the following quantities: correlation, mean of the differences, standard deviation of the differences, and percentiles of the absolute differences for 68%, 95%, and 99%.

mjoindices.evaluation_tools.calc_vector_agreement(ref_vec: ndarray, vec: ndarray, percentage: bool = True, do_print: bool = False) → Tuple[source]

Calculates extended comparison statistics between two vectors.

Parameters:

  • ref_vec – The reference vector.

  • vec – The vector to validate.

  • percentage – If True: calculation results will be in percent of the mean of the absolute reference values.

  • do_print – If True, some statistical values will we printed to the console.

Returns:

A tuple containing values for the following quantities: correlation, mean of the differences, standard deviation of the differences, and percentiles of the absolute differences for 68%, 95%, and 99%.

mjoindices.evaluation_tools.compute_vector_difference_quantity(ref_vec: ndarray, vec: ndarray, percentage: bool = True) → ndarray[source]

Calculates a standardized difference between two vectors.

Parameters:

  • ref_vec – The reference vector.

  • vec – The vector to validate.

  • percentage – If True: calculation results will be in percent of the mean of the absolute reference values.

Returns:

A vector containing the difference.

mjoindices.evaluation_tools.load_omi_explained_variance(filename: str) → Tuple[source]

Loads original explained variance files provided by Juliana Dias.

Parameters:

filename – The file to load.

Returns:

A tuple containing two arrays, for EOF1 and EOF2, respectively.

mjoindices.evaluation_tools.plot_comparison_orig_calc_pcs(calc_pcs: PCData, orig_pcs: PCData, start_date: Optional[datetime64] = None, end_date: Optional[datetime64] = None)[source]

Plots both PC time series (one in a subplot each) of the recalculation and a reference.

The period to plot can be adjusted.

Parameters:

  • calc_pcs – The recalculated PC time series.

  • orig_pcs – The reference PC time series.

  • start_date – Start of the period to plot. If None, the whole period will be plotted.

  • end_date – End of the period to plot. If None, the whole period will be plotted.

Returns:

The figure handle.

mjoindices.evaluation_tools.plot_comparison_stats_for_eofs_all_doys(recalc_eof: EOFDataForAllDOYs, orig_eof: EOFDataForAllDOYs, exclude_doy366: bool = False, do_print: bool = False) → Figure[source]

Plots extended comparison statistics between calculated EOFs and references EOFs.

Statistics of the differences will be shown for each DOY (DOY on the abscissa) and with one line each for EOF1 and EOF2.

Parameters:

  • recalc_eof – The EOFs to compare.

  • orig_eof – The reference eofs.

  • exclude_doy366 – If True, DOY 366 will be included in the plot (sometimes worse agreement depending on the leap year treatment mode).

  • do_print – If True, some characteristic values will we printed to the console.

Returns:

The figure handle

mjoindices.evaluation_tools.plot_comparison_stats_for_explained_variance(ref_var: ndarray, calc_var: ndarray, title: Optional[str] = None, do_print: bool = False, exclude_doy366: bool = False) → Figure[source]

Plots the comparison of the explained variances for one EOF and for all DOYs.

Parameters:

  • ref_var – The reference variances.

  • calc_var – The variances to validate.

  • title – A title for the figure.

  • do_print – If True, some statistical values will also be shown in the console.

  • exclude_doy366 – If True, the data for DOY 366 will not be considered in the statistics.

Returns:

The figure handle

mjoindices.evaluation_tools.plot_correlation_for_eofs_all_doys(recalc_eof: EOFDataForAllDOYs, orig_eof: EOFDataForAllDOYs, exclude_doy366: bool = False, do_print: bool = False, full_value_range: bool = True) → Figure[source]

Plots the correlations between calculated EOFs and reference EOFs.

Correlations will be shown for each DOY (DOY on the abscissa) and with one line each for EOF1 and EOF2.

Parameters:

  • recalc_eof – The EOFs to validate.

  • orig_eof – The reference EOFs.

  • exclude_doy366 – If False, DOY 366 will be included in the plot (sometimes worse correlation depending on the leap year treatment mode).

  • do_print – If True, some characteristic values will we printed to the console.

  • full_value_range – If True, the ordinate spans the range from 0 to 1 instead of the used value range only.

Returns:

A handle to the figure.

mjoindices.evaluation_tools.plot_individual_eof_map_comparison(orig_eof: EOFData, compare_eof: EOFData, doy: Optional[int] = None) → Figure[source]

Shows the maps of EOFs 1 and 2 and a respective reference together with a map of differences between both.

Parameters:

  • orig_eof – The reference EOF data.

  • compare_eof – The EOF data to validate.

  • doy – The DOY, which is evaluated (only used for the figure title).

Returns:

The figure handle.

mjoindices.evaluation_tools.plot_timeseries_agreement(ref_data: ndarray, ref_time: ndarray, data: ndarray, time: ndarray, title: Optional[str] = None, do_print: bool = False) → Figure[source]

Plots a graphical comparison of 2 time series.

Shows 4 subplots with 1) the data, 2) the difference, 3) a scatterplot of the data, and 4) a histogram of the differences.

Parameters:

  • ref_data – The time series reference vector.

  • ref_time – The time grid of the reference.

  • data – The time series vector to validate.

  • time – The time grid of the data to validate. It will be checked if this is similar to the time grid of the reference.

  • title – A title for the plot. Use this to explain the quantity which is compared evaluated with the plot.

  • do_print – If True, some statistical values will also be shown in the console.

Returns:

The figure handle.

mjoindices.evaluation_tools.plot_vector_agreement(ref_data: ndarray, data: ndarray, title: Optional[str] = None, do_print: bool = False) → Figure[source]

Plot a graphical comparison of 2 vectors.

Shows 4 subplots with 1) the data, 2) the difference, 3) a scatterplot of the data, and 4) a histogram of the differences.

Parameters:

  • ref_data – The reference vector.

  • data – The vector to validate.

  • title – A title for the plot. Use this to explain the quantity which is evaluated with the plot.

  • do_print – If True, some statistics values will also be shown in the console.

Returns:

The figure handle.