feat(datasets): blurb

SimpleSDMDatasets/Project.toml

@@ -1,11 +1,12 @@
 name = "SimpleSDMDatasets"
 uuid = "2c7d61d0-5c73-410d-85b2-d2e7fbbdcefa"
 authors = ["Timothée Poisot <[email protected]>"]
-version = "0.2.1"
+version = "0.2.2"
 
 [deps]
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
+Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 ZipFile = "a5390f91-8eb1-5f08-bee0-b1d1ffed6cea"
 
 [compat]

SimpleSDMDatasets/docs/src/interface.md

@@ -108,3 +108,28 @@ SimpleSDMDatasets.source
 ```@docs
 SimpleSDMDatasets.destination
 ```
+
+## URL for additional information
+
+The `url` method will display one URL re-directing users to either the
+description of the provider, or the description of the dataset. *A minima*, the
+version for the `RasterProvider` should be specified. Note that this must return
+a **Markdown** string.
+
+Most of the `RasterDataset` will have a *default* blurb, but more specific
+(*i.e.* adapted to a particular prodiver) ones can be provided.
+
+```@docs
+SimpleSDMDatasets.url
+```
+
+## Additional information about a dataset
+
+The `blurb` is a short text explaining what the dataset / provider is about. *A
+minima*, the version for the `RasterProvider` should be specified. In some
+cases, it is acceptable to only define a version for one `RasterDataset` and any
+`RasterProvider`, although a more specific dispatch can be implemented.
+
+```@docs
+SimpleSDMDatasets.blurb
+```

SimpleSDMDatasets/src/SimpleSDMDatasets.jl

@@ -3,6 +3,7 @@ module SimpleSDMDatasets
 import Downloads
 using Dates
 using ZipFile
+using Markdown
 
 # Set the potential paths for downloads
 const _data_storage_folders = first([
@@ -54,6 +55,9 @@ export RasterData, Projection
 include("interface.jl")
 export layers, layerdescriptions
 
+# Default blurbs
+include("blurbs.jl")
+
 # Providers
 include("providers/CHELSA/chelsa_v1.jl")
 include("providers/CHELSA/chelsa_future_v1.jl")

SimpleSDMDatasets/src/blurbs.jl

@@ -0,0 +1,68 @@
+function SimpleSDMDatasets.blurb(::RasterData{P, BioClim}) where {P <: RasterProvider}
+    return md"""
+    The BioClim variables are derived from monthly data about precipitation and
+    temperature, and convey information about annual variation, as well as
+    extreme values for specific quarters. These variables are usually thought to
+    represent limiting environmental conditions.
+    """
+end
+
+function SimpleSDMDatasets.blurb(::RasterData{P, Elevation}) where {P <: RasterProvider}
+    return md"""
+    Information about elevation, that usually comes from a DEM.
+    """
+end
+
+function SimpleSDMDatasets.blurb(::RasterData{P, MinimumTemperature}) where {P <: RasterProvider}
+    return md"""
+    Minimum temperature within each grid cell, usually represented in degrees,
+    and usually provided as part of a dataset giving daily, weekly, or monthly
+    temporal resolution.
+    """
+end
+
+function SimpleSDMDatasets.blurb(::RasterData{P, MaximumTemperature}) where {P <: RasterProvider}
+    return md"""
+    Maximum temperature within each grid cell, usually represented in degrees,
+    and usually provided as part of a dataset giving daily, weekly, or monthly
+    temporal resolution.
+    """
+end
+
+function SimpleSDMDatasets.blurb(::RasterData{P, AverageTemperature}) where {P <: RasterProvider}
+    return md"""
+    Average temperature within each grid cell, usually represented in degrees,
+    and usually provided as part of a dataset giving daily, weekly, or monthly
+    temporal resolution.
+    """
+end
+
+function SimpleSDMDatasets.blurb(::RasterData{P, Precipitation}) where {P <: RasterProvider}
+    return md"""
+    Precipitation (rainfall) within each grid cell, usually represented as the
+    total amount received, and usually provided as part of a dataset giving
+    daily, weekly, or monthly temporal resolution.
+    """
+end
+
+function SimpleSDMDatasets.blurb(::RasterData{P, Topography}) where {P <: RasterProvider}
+    return md"""
+    Information about the shape of terrain, that unlike `Elevation` can provide
+    information about more than the altitude.
+    """
+end
+
+function SimpleSDMDatasets.blurb(::RasterData{P, HabitatHeterogeneity}) where {P <: RasterProvider}
+    return md"""
+    Derived information about the topography, giving information about the local
+    heterogeneity within a grid cell.
+    """
+end
+
+function SimpleSDMDatasets.blurb(::RasterData{P, LandCover}) where {P <: RasterProvider}
+    return md"""
+    Information about the type of land-use within each pixel, that can be
+    communicated as a fraction (*i.e.* the proportion of the cell occupied by a
+    specific category), or as a consensus.
+    """
+end

SimpleSDMDatasets/src/interface.jl

@@ -224,5 +224,18 @@ bandnumber(::R, ::F; kwargs...) where {R <: RasterData, F <: Projection} = 1
 crs(::R) where {R <: RasterData} = _wgs84
 crs(data::R, ::F) where {R <: RasterData, F <: Projection} = crs(data)
 
-url(::R) where {R <: RasterData} = ""
+"""
+    url(::P) where {P <: DataProvider}
+
+The URL for the data provider - if there is no specific URL for each dataset, it
+is enough to define this one.
+"""
+url(::Type{P}) where {P <: RasterProvider} = ""
+url(::RasterData{P, D}) where {P <: RasterProvider, D <: RasterDataset} = url(P)
 url(data::R, ::F) where {R <: RasterData, F <: Projection} = url(data)
+
+"""
+    blurb(::Type{P}) where {P <: RasterProvider}
+"""
+blurb(::Type{P}) where {P <: RasterProvider} = ""
+blurb(::RasterData{P, D}) where {P <: RasterProvider, D <: RasterDataset} = blurb(P)

SimpleSDMDatasets/src/providers/CHELSA/chelsa_v1.jl

@@ -9,7 +9,8 @@ CHELSA1Dataset = Union{
 # Update provisioning
 provides(::Type{CHELSA1}, ::Type{T}) where {T <: CHELSA1Dataset} = true
 
-url(::RasterData{CHELSA1, D}) where {D <: CHELSA1Dataset} = "https://chelsa-climate.org/"
+url(::Type{CHELSA1}) = "https://chelsa-climate.org/"
+url(::RasterData{CHELSA1, BioClim}) = "https://chelsa-climate.org/bioclim/"
 
 # Update the layers
 layers(::RasterData{CHELSA1, BioClim}) = "BIO" .* string.(1:19)

docs/dataset_report.jl

@@ -95,6 +95,9 @@ function report(::Type{P}, ::Type{D}) where {P <: RasterProvider, D <: RasterDat
     _header = "## $(D)"
     # Short description
     _description = """
+
+    $(SimpleSDMDatasets.blurb(RasterData(P, D)))
+
     For more information about this dataset, please refer to: $(SimpleSDMDatasets.url(RasterData(P, D)))
 
     To access this dataset: