ESI Functions#

spatialize.gs.esi.esi_griddata(points, values, xi, **kwargs)#

Perform ESI estimation for grid data. This is the function used to make an estimate with ESI in the case of sample data and unmeasured locations that are on a grid.

Parameters:

points (Array of input data points) – The input points. Contains the coordinates of known data points. This is an \(N_s \times D\) array, where \(N_s\) is the number of data points, and \(D\) is the number of dimensions.
values (Array of values corresponding to input data points.) – The input values associated with each point in points. This must be a 1D array of length \(N_s\).
xi (Array of points where estimation is desired.) – The interpolation points. If the data are gridded, they correspond to an array of grids of \(D\) components, each with the dimensions of one of the grid faces, \(d_1 \times d_2 = N_{x^*}\), where \(N_{x^*}\) is the total number of unmeasured locations to estimate. Each component of this array represents the coordinate matrix on the corresponding axis, as returned by the functions numpy.mgrid in Numpy, or meshgrid in Matlab or R.

Returns:

Examples

esi_griddata(points, values, (grid_x, grid_y),
         local_interpolator="idw",
         p_process="mondrian",
         data_cond=False,
         exponent=1.0,
         n_partitions=500, alpha=0.985,
         agg_function=af.mean)

spatialize.gs.esi.esi_nongriddata(points, values, xi, **kwargs)#

Perform ESI estimation for non-grid data. This function generates an estimate in ESI space, from a set of sample points (i.e. measured locations), at a set of unmeasured points at arbitrary locations in space.

Parameters:

points (Array of input data points) – The input points. Contains the coordinates of known data points. This is an \(N_s \times D\) array, where \(N_s\) is the number of data points, and \(D\) is the number of dimensions.
values (Array of values corresponding to input data points.) – The input values associated with each point in points. This must be a 1D array of length \(N_s\).
xi (Array of points where estimation is desired.) – The interpolation points. If the data are gridded, they correspond to an array of grids of \(D\) components, each with the dimensions of one of the grid faces, \(d_1 \times d_2 = N_{x^*}\), where \(N_{x^*}\) is the total number of unmeasured locations to estimate. Each component of this array represents the coordinate matrix on the corresponding axis, as returned by the functions numpy.mgrid in Numpy, or meshgrid in Matlab or R.

Returns:

The result as ESIResult().

spatialize.gs.esi.esi_hparams_search(points, values, xi)#

Perform a hyperparameter search for ESI.

Parameters:

points – The input points. Contains the coordinates of known data points. This is an \(N_s \times D\) array, where \(N_s\) is the number of data points, and \(D\) is the number of dimensions.
values – The input values associated with each point in points. This must be a 1D array of length \(N_s\).
xi –
The interpolation points. If the data are gridded, they correspond to an array of grids of \(D\) components, each with the dimensions of one of the grid faces, \(d_1 \times d_2 = N_{x^*}\), where \(N_{x^*}\) is the total number of unmeasured locations to estimate. Each component of this array represents the coordinate matrix on the corresponding axis, as returned by the functions numpy.mgrid in Numpy, or meshgrid in Matlab or R.

If the data are not gridded, they are simply the locations at which to evaluate the interpolation. It is then an \(N_{x^*} \times D\) array.

In both cases, \(D\) is the dimensionality of each location, which coincides with the dimensionality of the points.
kwargs – Additional keyword arguments.

Returns:

The grid search result.

class spatialize.gs.esi.ESIGridSearchResult(search_result_data, p_process)#

A class to represent the result of a grid search for ESI.

Parameters:

search_result_data – The search result data.
agg_function_map – The aggregation function map.
p_process – The partitioning process.

Methods

`best_result`(**kwargs)	Get the best result from the grid search.
`plot_cv_error`([theme, color, fig_args])	It shows a graph of the cross-validation errors of the hyperparameter search process.

load
save

best_result(**kwargs)#

Get the best result from the grid search.

Parameters:: kwargs – Additional keyword arguments.
Returns:: The best result.

plot_cv_error(theme='alges', color=None, fig_args=None)#

It shows a graph of the cross-validation errors of the hyperparameter search process. The graph has two components: the first is the error histogram, and the second is the error level for each of the estimation scenarios generated by the gridded parameter search.

Parameters:

fig_args (Optional[Dict[str, Any]]) – Dictionary with figure configuration for plt.subplots(). Default assigns figsize=(10, 4) if not specified.
subplot_args – Dictionary with subplot configuration for plt.subplots_adjust(). Default assigns wspace=0.45 if not specified.
theme (Optional[str]) – Theme name. Available: ‘whitegrid’, ‘darkgrid’, ‘white’, ‘dark’, ‘alges’, ‘minimal’, ‘publication’
color (Optional[str]) – Color for the plots. If None, uses theme default or ‘skyblue’

Returns:

Tuple with matplotlib figure and tuple of axes (fig, (ax1, ax2))

Raises:

ValueError – If the specified theme does not exist.

class spatialize.gs.esi.ESIResult(estimation, esi_samples, griddata=False, original_shape=None, xi=None)#

Bases: EstimationResult

A class to represent the result of an ESI estimation.

As a result, this function also returns an object, which is an instance of the class ESIResult(), containing the preliminary estimate according to the provided arguments. This class provides a set of methods to display aspects of the result, such as the aggregate estimate, the scenarios of the different partitions, or a precision calculation based on some loss function.

Methods

`esi_samples`([raw])	The central concept for dealing with ESI estimation results is the ESI sample.
`estimation`()	Returns the estimated values at locations xi by aggregating all ESI samples using the aggregation function provided in the agg_function argument (in both function `esi_griddata()` and `esi_nongriddata()`).
`plot_estimation`([ax, w, h, theme, cmap])	Plots the estimation using matplotlib.
`plot_precision`([ax, w, h, theme, cmap])	Plot the precision of the estimation.
`precision`([loss_function])	Calculates the precision (or error) between the estimate and the ESI samples using the specified loss function.
`precision_cube`([loss_function])	It applies a loss (error) function to each ESI sample with respect to the current estimate.
`preview_esi_samples`([n_imgs, n_cols, ...])	Visualizes a preview of the ESI samples as a grid of colormap images.
`quick_plot`([w, h, theme, estimation_cmap, ...])	Quickly plot the estimation and precision.
`re_estimate`([agg_function])	Re-estimate the ESI samples using the given aggregation function.

esi_samples(raw=False)#

The central concept for dealing with ESI estimation results is the ESI sample. In this sense, it should be noted that each random partition delivers an estimate for each of the locations provided in the argument xi (for both gridded and non-gridded data). The set of estimates for a particular partition is what in Spatialize is considered an ESI sample.

This method then returns the set of all ESI samples, one for each random partition, calculated for the estimation.

Returns:: The ESI samples, an array of dimension \(N_{x^*} \times m\) (\(m\) = n_partitions in both function esi_griddata() and esi_nongriddata()), for non-gridded data, and of dimension \(d_1 \times d_2 \times m\) for gridded data – remember that, in this case, \(d_1 \times d_2 = N_{x^*}\)

estimation()#

Returns the estimated values at locations xi by aggregating all ESI samples using the aggregation function provided in the agg_function argument (in both function esi_griddata() and esi_nongriddata()). This estimate can be changed using another aggregation function with the re_estimate() method of this same class.

Returns:: An array of dimension \(N_{x^*}\), for non-gridded data, and of dimension \(d_1 imes d_2\) for gridded data – remember that, in this case, \(d_1 imes d_2 = N_{x^*}\)

plot_estimation(ax=None, w=None, h=None, theme='alges', cmap=None, **imshow_args)#

Plots the estimation using matplotlib.

Parameters:

ax ((matplotlib.axes.Axes, optional)) – The Axes object to render the plot on. If None, a new Axes object is created.
w ((int, optional)) – The width of the image (if the data is reshaped).
h ((int, optional)) – The height of the image (if the data is reshaped).
theme ((str, optional)) – Theme name. Available: ‘whitegrid’, ‘darkgrid’, ‘white’, ‘dark’, ‘alges’, ‘minimal’, ‘publication’
cmap ((str, optional)) – Colormap for the plot. If None, uses theme default or ‘coolwarm’
**imshow_args ((optional)) – Additional keyword arguments passed to the _plot_data function (e.g., vmin, vmax, alpha).

plot_precision(ax=None, w=None, h=None, theme='alges', cmap=None, **imshow_args)#

Plot the precision of the estimation.

Parameters:

ax – The axis to plot on.
w – The width of the plot.
h – The height of the plot.
theme – Theme name. Available: ‘whitegrid’, ‘darkgrid’, ‘white’, ‘dark’, ‘alges’, ‘minimal’, ‘publication’.
cmap – Colormap for the plot. If None, uses theme default or ‘bwr’.
imshow_args – Additional imshow arguments to pass to the _plot_data function.

precision(loss_function=<decorated--spatialize.gs.esi.lossfunction.mse_loss>)#

Calculates the precision (or error) between the estimate and the ESI samples using the specified loss function.

Parameters:: loss_function – The loss function to use.
Returns:: The precision of the estimation.

precision_cube(loss_function=<decorated--spatialize.gs.esi.lossfunction.mse_cube>)#

It applies a loss (error) function to each ESI sample with respect to the current estimate. The difference with the precision() method is that it does not aggregate the result over the total calculated losses, returning the total data cube whose dimensions are the same as the ESI samples cube.

Parameters:: loss_function – The loss function to use.
Returns:: The precision cube of the estimation.

preview_esi_samples(n_imgs=9, n_cols=3, title_prefix='ESI sample', title=None, figsize=(10, 10), dpi=120, theme='alges', cmap=None, **imshow_args)#

Visualizes a preview of the ESI samples as a grid of colormap images.

This method displays a subset of the ESI samples using the plot_colormap_array function. The ESI samples are visualized in a grid layout, where each image corresponds to one ESI sample.

Parameters:

n_imgs – The number of ESI samples (images) to display. Defaults to 9.
n_cols – The number of columns in the grid layout. Defaults to 3.
title_prefix – A prefix to add to each subplot title (e.g., “ESI sample 1”, “ESI sample 2”).
title – The title for the entire plot.
figsize – Width, height of the figure in inches. Defaults to (10, 10).
dpi – The resolution of the figure in dots-per-inch. Defaults to 120.
theme – Theme name. Available: ‘whitegrid’, ‘darkgrid’, ‘white’, ‘dark’, ‘alges’, ‘minimal’, ‘publication’.
cmap – Colormap for the plot. If None, uses theme default or ‘coolwarm’.
imshow_args – Additional imshow arguments to pass to the plot_colormap_array function.

quick_plot(w=None, h=None, theme='alges', estimation_cmap=None, precision_cmap=None, **fig_args)#

Quickly plot the estimation and precision.

Parameters:

w – The width of the plot.
h – The height of the plot.
theme – Theme name. Available: ‘whitegrid’, ‘darkgrid’, ‘white’, ‘dark’, ‘alges’, ‘minimal’, ‘publication’.
estimation_cmap – Colormap for the estimation plot. If None, uses theme default or ‘coolwarm’.
precision_cmap – Colormap for the precision plot. If None, uses theme default or ‘bwr’.
fig_args – Additional figure arguments.

Returns:

The figure.

re_estimate(agg_function=<function mean>)#

Re-estimate the ESI samples using the given aggregation function. It recalculates the final estimate based on the aggregation function provided (e.g. by taking the mean of the ESI samples). This method updates the internal estimate and returns the new result. Then, the next time the estimation() method is called, this is the estimate it will return.

Parameters:: agg_function – The aggregation function to use.
Returns:: The re-estimated ESI samples.

ESI Functions#

This Page