Spatial and robust stats, intro documentation + Update of spatialstats.py with new scikit-gstat features

[rhugonnet]

EDIT PR ALMOST READY:

Partly resolves #152

Refactors

• Refactored spstats into spatialstats for clarity and consistency with other module names (spatial_tools will disappear soon, as discussed in Sort the mess in spatial_tools.py #157)

Added documentation

• Added Introduction
• Added Spatial statistics page
• Added Robust statistics page
• Added gallery example Non-stationarity in elevation measurement errors
• Added gallery example: Spatial correlation in elevation measurement errors
• Added structure for other pages: Bias corrections, Filters, all added to API

Added/Improved plotting functionalities

• Added plot_1d_binning, plot_2d_binning for results of nd_binning
• Improved plot_vgm for results of sample_multirange_variogram

Refined variogram sampling and implementation of random methods

• Modified sample_multirange_variogram to wrap methods pre-sampling of Raster point (functions not available for users such as _get_pdist_variogram, _subsample_wrapper) with different methods (circular, ring, random).
• Added new RasterEquidistantMetricSpace method of scikit-gstat into a wrapper function _get_cdist_variogram.
  Fits in one-line summary, but actually a lot of work:
  Easier support for raster data: custom bins, user-defined maxlag, return count, etc...  mmaelicke/scikit-gstat#111
  Add custom bins (callable, iterable) and count property mmaelicke/scikit-gstat#112
  Argument for optional model fitting mmaelicke/scikit-gstat#113
  Add RasterMetricSpace for improved pairwise sampling of large 2D grids mmaelicke/scikit-gstat#114
• All kwargs of skgstat.Variogram and skgstat.MetricSpace can be passed, those are automatically sorted by the sample_multirange_variogram function.
• Added support for random_state to pass seeds of random sequences, in order for tests and examples to have fixed results (added random_state argument to many functions, including the subsample_raster function written by Amaury). The random seeds are also passed down to scikit-gstat functions, when those use random sequences.
• Added better description of functions, and improved line-by-line comments

Tests and fixes

• Added more robust tests for all functions related to sample_multirange_variogram
• Refined tests of fit_sum_variogram
• Fixed some issues with patches_method, for it to run faster (@adehecq your convolution approach is probably still better, we should implement it!)

TODO (just thought about it):

• Add random_state for patches_method
• Improve tests for patches_method
• Fix bug in histogram of plot_vgm when log scale is used.
• Fix spatialstats.py for referencing code in Spatial statistics page.
• Clarify run and nruns arguments of sample_multirange_variogram

[erikmannerfelt]

This will be a fantastic resource!! I look forward to seeing the text be more integrated with figures, schematics and the xdem API. Let me know if there's something I can do!

[rhugonnet]

Is it correct that this PR is linked to #152? This would mean that the issue gets closed when this PR is merged.

It replaces uses with the subsampling function in spatialstats.py, but maybe not in other modules.
@adehecq Where else were you thinking we should update the subsampling when you raised this issue?

[rhugonnet]

99 commits! You can do it!!

It's done!! 🥳 🎈

[adehecq]

Is it correct that this PR is linked to #152? This would mean that the issue gets closed when this PR is merged.

It replaces uses with the subsampling function in spatialstats.py, but maybe not in other modules.
@adehecq Where else were you thinking we should update the subsampling when you raised this issue?

The two lines were this needed replacement are mentioned in the issue. So you can check that both are ok now.

[erikmannerfelt]

@rhugonnet, with this PR, there is now a minimum version requirement for scikit-gstat. Do you know which? If so, can you specify that in the environment file?

[rhugonnet]

@rhugonnet, with this PR, there is now a minimum version requirement for scikit-gstat. Do you know which? If so, can you specify that in the environment file?

@erikmannerfelt Done!
If it's all good for you, I think we can merge this PR.
There's still some TODOs left in the documentation, but those can be added step by step in the future!

[erikmannerfelt]

Great job!