Merge pull request #15 from jbisits/exampleupdates

Doc updates

docs/Project.toml

@@ -1,6 +1,7 @@
 [deps]
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 NCDatasets = "85f8d34a-cbdd-5861-8df4-14fed0d494ab"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"

docs/make.jl

@@ -1,5 +1,5 @@
 using RasterHistograms
-using Documenter, Literate
+using Documenter, Literate, DocumenterCitations
 
 DocMeta.setdocmeta!(RasterHistograms, :DocTestSetup, :(using RasterHistograms); recursive=true)
 const EXAMPLES_DIR = joinpath(@__DIR__, "../examples")
@@ -28,7 +28,9 @@ pages = [
     "Library" => library_pages
 ]
 
-makedocs(;
+bib = CitationBibliography(joinpath(@__DIR__, "src/refs.bib"))
+
+makedocs(bib;
     modules=[RasterHistograms],
     authors="Josef Bisits <jbisits@gmail.com>",
     repo="https://github.com/jbisits/RasterHistograms.jl/blob/{commit}{path}#{line}",

docs/src/index.md

@@ -10,6 +10,6 @@ RasterHistograms.jl uses [empirical estimation from StatsBase.jl](https://julias
 Arguments that can be passed to [`fit(::Histogram)`](https://juliastats.org/StatsBase.jl/stable/empirical/#StatsAPI.fit-Tuple{Type{Histogram},%20Vararg{Any}}) can be passed to the constructors for the the various `AbstractRasterHistogram`s.
 The aim of the module is to provide functionality similar to python's [xhistogram](https://xhistogram.readthedocs.io/en/latest/index.html) for [xarray](https://docs.xarray.dev/en/stable/) in Julia.
 
-For information about how the module works [see here](@ref raster_hist_module) or take a look at the [example](@ref raster_hist_example)
+For information about how the module works [see here](@ref raster_hist_module) or take a look at the [example](@ref raster_hist_example).
 
-If you have find any bugs or have a feature request/suggestion please raise an issuu in the [RasterHistograms.jl repository](https://github.com/jbisits/RasterHistograms.jl).
+If you have find any bugs or have a feature request/suggestion please raise an issue in the [RasterHistograms.jl repository](https://github.com/jbisits/RasterHistograms.jl).

docs/src/refs.bib

@@ -0,0 +1,32 @@
+@article{Fukumori2022,
+abstract = {Information about how and when I accessed the ECCO dataset (v4r4). I accessed the data through EARTHDATA.},
+author = {Fukumori, Ichiro and Wang, Ou and Forget, Gael and Heimbach, Patrick and Ponte, R. M. and {Date accessed March 2022}},
+publisher = {ECCO Central Estimate},
+title = {{ECCO Version 4 Release 4 Dataset}},
+url = {https://search.earthdata.nasa.gov/search/granules?p=C1990404821-POCLOUD{\&}tl=1656394462.167!3!!},
+year = {2022}
+}
+@article{Fukumori2021,
+author = {Fukumori, Ichiro and Wang, Ou and Fenty, Ian and Forget, Gael and Heimbach, Patrick and Ponte, Rui M.},
+doi = {https://doi.org/10.5281/zenodo.4533349},
+journal = {Zenodo},
+pages = {1--17},
+title = {{Synopsis of the ECCO Central Production Global Ocean and Sea-Ice State Estimate, Version 4 Release 4 (Version 4 Release 4).}},
+volume = {3},
+year = {2021}
+}
+@article{Forget2015,
+abstract = {This paper presents the ECCO v4 non-linear inverse modeling framework and its baseline solution for the evolving ocean state over the period 1992-2011. Both components are publicly available and subjected to regular, automated regression tests. The modeling framework includes sets of global conformal grids, a global model setup, implementations of data constraints and control parameters, an interface to algorithmic differentiation, as well as a grid-independent, fully capable Matlab toolbox. The baseline ECCO v4 solution is a dynamically consistent ocean state estimate without unidentified sources of heat and buoyancy, which any interested user will be able to reproduce accurately. The solution is an acceptable fit to most data and has been found to be physically plausible in many respects, as documented here and in related publications. Users are being provided with capabilities to assess model-data misfits for themselves. The synergy between modeling and data synthesis is asserted through the joint presentation of the modeling framework and the state estimate. In particular, the inverse estimate of parameterized physics was instrumental in improving the fit to the observed hydrography, and becomes an integral part of the ocean model setup available for general use. More generally, a first assessment of the relative importance of external, parametric and structural model errors is presented. Parametric and external model uncertainties appear to be of comparable importance and dominate over structural model uncertainty. The results generally underline the importance of including turbulent transport parameters in the inverse problem.},
+author = {Forget, G. and Campin, J. M. and Heimbach, P. and Hill, C. N. and Ponte, R. M. and Wunsch, C.},
+doi = {10.5194/gmd-8-3071-2015},
+file = {:Users/Joey/Documents/Digital library/Forget et al.{\_}2015{\_}ECCO version 4 An integrated framework for non-linear inverse modeling and global ocean state estimation.pdf:pdf},
+issn = {19919603},
+journal = {Geoscientific Model Development},
+month = {oct},
+number = {10},
+pages = {3071--3104},
+publisher = {Copernicus GmbH},
+title = {{ECCO version 4: An integrated framework for non-linear inverse modeling and global ocean state estimation}},
+volume = {8},
+year = {2015}
+}

examples/raster_histograms.jl

@@ -4,7 +4,7 @@ using Rasters, NCDatasets, Downloads, CairoMakie
 # and the `RasterHistograms` package.
 using RasterHistograms
 # Using this package we can produce `Histogram`s from data that is in a `Raster`,
-# `RasterStack` or `RasterSeries`, which are N-dimensional arrays, in a similar way that
+# `RasterStack` or `RasterSeries`, which are named N-dimensional arrays, in a similar way that
 # [xhistogram](https://xhistogram.readthedocs.io/en/latest/index.html) works for xarray
 # in python. This example is structured similarly to the
 # [xhistogram tutorial](https://xhistogram.readthedocs.io/en/latest/tutorial.html).
@@ -25,10 +25,10 @@ hm = heatmap!(ax1, x, t, rs.data)
 Colorbar(fig[2, 1], hm; vertical = false, flipaxis = false)
 ax2 = Axis(fig[1, 2];
           title = "Histogram of Toy data",
-          xlabel = "Toy data", ylabel = "Counts")
+          xlabel = "Toy data", ylabel = "Frequency")
 plot!(ax2, rs_hist; color = :steelblue)
 fig
-# By default the `Histogram` has the counts in each bin. We can normalise the `Histogram`
+# By default we have a frequency `Histogram`. We can normalise the `Histogram`
 # by calling the `normalize!` function on `rs_hist` and choosing a `mode` of normalisation.
 # For more information about the possible modes of normalisation
 # [see here](https://juliastats.org/StatsBase.jl/latest/empirical/#LinearAlgebra.normalize).
@@ -50,10 +50,27 @@ fig
 #     Plotting using [Plots.jl](https://docs.juliaplots.org/latest/) is also possible.
 #     See the [module documentation](@ref raster_hist_module) for more info.
 # ## Real world data example
-# This package is mainly concerned with ocean variables, so we now look at temperature and
-# salinity distributions using ECCO model output.
-Downloads.download("https://opendap.earthdata.nasa.gov/providers/POCLOUD/collections/ECCO%2520Ocean%2520Temperature%2520and%2520Salinity%2520-%2520Daily%2520Mean%25200.5%2520Degree%2520(Version%25204%2520Release%25204)/granules/OCEAN_TEMPERATURE_SALINITY_day_mean_2007-01-01_ECCO_V4r4_latlon_0p50deg.dap.nc4", "ECCO_data.nc")
-# This example also shows how the module works for 2-dimensional `Histograms` though it can
+# We now look at temperature and salinity distributions using ECCOv4r4 [Fukumori2022](@cite),
+# [Fukumori2021](@cite), [Forget2015](@cite) model output. The
+# function uses `try` to download from NASA EarthData but this sometimes fails during the
+# docs build.
+# !!! info
+#     See the [NCDatasets.jl example](https://alexander-barth.github.io/NCDatasets.jl/latest/tutorials/#Data-from-NASA-EarthData)
+#     for information on how to download data from NASA EarthData.
+function download_ECCO()
+
+    try
+        Downloads.download("https://opendap.earthdata.nasa.gov/providers/POCLOUD/collections/ECCO%2520Ocean%2520Temperature%2520and%2520Salinity%2520-%2520Daily%2520Mean%25200.5%2520Degree%2520(Version%25204%2520Release%25204)/granules/OCEAN_TEMPERATURE_SALINITY_day_mean_2007-01-01_ECCO_V4r4_latlon_0p50deg.dap.nc4", "ECCO_data.nc")
+    catch
+        @info "dowloading from drive"
+        Downloads.download("https://drive.google.com/uc?id=1MNeThunqpY-nFzsZLZj9BV8sM5BJgnxT&export=download", "ECCO_data.nc")
+    end
+
+    return nothing
+
+end
+download_ECCO()
+# This example shows how the package works for 2-dimensional `Histograms` though it can
 # be generalised to N dimensions depending on the number of variables
 # (i.e. layers in the `RasterStack`) one is looking at.
 # ### Forming the `RasterStack`
@@ -62,12 +79,11 @@ Downloads.download("https://opendap.earthdata.nasa.gov/providers/POCLOUD/collect
 # dimensional. Note the order of the variables matters here for plotting purposes. The first
 # layer, in this case `:SALT` will be the x-axis, and the second layer `:THETA` will be
 # the y-axis.
-stack_TS = RasterStack("ECCO_data.nc"; name = (:SALT, :THETA))
+stack_TS = RasterStack("ECCO_data.nc", name = (:SALT, :THETA))
 edges = (31:0.025:38, -2:0.1:32)
 stack_hist = RasterStackHistogram(stack_TS, edges)
 # Now we can plot, the histogram and look at the unweighted distribtution of temperature and
-# salinity. By default the empty bins are plotted with the value of zero. To not plot
-# the empty bins argument we pass `show_empty_bins = false` to the plotting function.
+# salinity. By default the empty bins are plotted with the value of zero.
 fig = Figure(size = (500, 500))
 ax = Axis(fig[1, 1];
           title = "Temperature and salinity joint distribution (unweighted)",
@@ -78,8 +94,8 @@ Colorbar(fig[1, 2], hm)
 fig
 # ### Weighting the `Histogram`
 # The module also exports simple functions for calculating area and volume weights from the
-# dimensions of the grid and plot the data. Where weights are available from model data they
-# should be used in favour of the functions.
+# dimensions of the grid which can be used to weight an `AbstractRasterHistogram`.
+# Where weights are available from model data they should be used in favour of the functions.
 dV = volume_weights(stack_TS)
 weighted_stack_hist = RasterStackHistogram(stack_TS, dV, edges)
 fig = Figure(size = (500, 500))
@@ -90,3 +106,5 @@ ax = Axis(fig[1, 1];
 hm = heatmap!(ax, weighted_stack_hist; colorscale = log10)
 Colorbar(fig[1, 2], hm)
 fig
+# ```@bibliography
+# ```