Citatations and better download

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/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

@@ -50,19 +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
-# We now look at temperature and salinity distributions using ECCOv4r4 model output. The
-# `try` block below is because sometimes downloading the data during the docs build from
-# NASA EarthData fails.
+# 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.
-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")
+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
-# This example also shows how the module works for 2-dimensional `Histograms` though it can
+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`
@@ -98,3 +106,5 @@ ax = Axis(fig[1, 1];
 hm = heatmap!(ax, weighted_stack_hist; colorscale = log10)
 Colorbar(fig[1, 2], hm)
 fig
+# ```@bibliography
+# ```