Is there a need to better document available data sources and measurement units on github or in the online documentation?

[Jo-Schie]

I think it is currently a bit difficult to get a quick and precise overview of the data that is supported by our package. If you look at similar packages this information is very prominent see e.g. here. I furthermore have the feeling, that we do not appropriatly acknoledge the scientific sources (cite papers) nor do we really link to the websites where our data comes from. In one case the documentation says for example: "This function allows to efficiently calculate the number of fire events occurred in the region of interest from the NASA FIRMS active fire polygon datasets." in another it says "This function allows to efficiently calculate area of mangrove from Global Mangrove Watch - World Conservation Monitoring Centre (WCMC) for polygons.".

there are several ways to get information on the functions of a package:

• github readme
• documentation (in our case the bookdown).
• calling in R ?something
• reading the pdf from CRAN (which basically contains the information from ?something

I think the most common access for most users are the first two options. The third and fourth furthermore do not allow a quick overview. We do provide an overview with names(available_resources()) but this does not fully serve as a quick reference guide. I was thinking of maybe something like a table in the documentation which goes like

|Indicator name | Website-Link | Scientific Source | unit of measurement|

where unit of measurement is the output of our package (took my quite a while to understand e.g. that the output in the case of mangroves is hectares.

What do you thin @fBedecarrats and @goergen95 and @melvinhlwong and @karpfen ?

[fBedecarrats]

From my perspective, the bookdown is the best.
I think that the github readme should focus on potential interested package contributors and direct users to the bookdown for anything related to the package use
The embeded help (appearing in ?something, in CRAN, and also in the bookdown "reference" section) should focus on the syntaxic/technical aspects direct users to the bookdown for more elaborate considerations
With these, the bookdown is really the center of the attention and there we can dedicate more effort/attention to have clean explainations, citations, etc.

[goergen95]

We (mostly) refer the reader to the actual source and the citation in the documentation for resources. This shows both on the website as well as ?resource.
For indicators (mostly) the output format as well as the units are described, both showing at the website and at ?indicator.
Maybe a better overview table in the README could be helpful. Also, some of these citations/links/unit descriptions could be improved. But in general I think we already do what you describe here @Jo-Schie.

[Jo-Schie]

but if I understand correctly, then you have to go into each ressource one by one with ?some_indicator, right? So there is not really an overview...

another column that came to my mind would be "time-period covered"... I am kind of indifferent if it was on github or the documentation but it would ease working with the package imho. maybe it would be also easier to update?

anyway I think it would be important to not double the effort. So if there was an overview table the documentation should refer to the table and not dublicate the information...right?

[goergen95]

I don't really understand what you mean. I my POV, resources and indicators are individually thoroughly documented (though of course improvements can be made). There is currently no comprehensive table overview with the categories you suggested, but of course we could create one either in README or somewhere else.

[goergen95]

An overview of the roxygen tags we currently use that show up in an R session using ? or help(), in the CRAN pdf documentation as well as in the reference section of the website:

• for resources:

  • description: a text informing about the original structure, measurments, etc.
  • format: a description of the data structure that is provided (e.g. global vector data set, global raster, tiled raster, etc.)
  • reference: the scientific reference for the data source
  • source: A link as close as possible to the actual source where we download the data

• for indicators:

  • description: a text describing the workflow of the indicator, required resources and arguments
  • format: a description of the shape of the output tibble, its columns and the measurement units

[goergen95]

Concerning the units issue, we maybe should return area estimates as units. That would also allow users to later simply change the unit of the measurments. See e.g. here:

library(mapme.biodiversity)
library(sf)
#> Linking to GEOS 3.11.1, GDAL 3.6.2, PROJ 9.1.1; sf_use_s2() is TRUE

poly <- st_read(system.file("extdata", "shell_beach_protected_area_41057_B.gpkg",
                           package = "mapme.biodiversity"))
#> Reading layer `shell_beach_protected_area_41057_B' from data source 
#>   `/home/darius/R/x86_64-pc-linux-gnu-library/4.2/mapme.biodiversity/extdata/shell_beach_protected_area_41057_B.gpkg' 
#>   using driver `GPKG'
#> Simple feature collection with 1 feature and 4 fields
#> Geometry type: POLYGON
#> Dimension:     XY
#> Bounding box:  xmin: -59.84866 ymin: 8.307999 xmax: -59.71 ymax: 8.364002
#> Geodetic CRS:  WGS 84
gmw <- st_read(system.file("res", "gmw", "gmw-extent_2016.gpkg",
                           package = "mapme.biodiversity"))
#> Reading layer `gmw-extent_2016' from data source 
#>   `/home/darius/R/x86_64-pc-linux-gnu-library/4.2/mapme.biodiversity/res/gmw/gmw-extent_2016.gpkg' 
#>   using driver `GPKG'
#> Simple feature collection with 31 features and 2 fields
#> Geometry type: POLYGON
#> Dimension:     XY
#> Bounding box:  xmin: -59.85667 ymin: 8.289778 xmax: -59.66778 ymax: 8.371111
#> Geodetic CRS:  WGS 84

area <- suppressWarnings(st_intersection(gmw, poly)) %>% st_area() %>% sum()
area
#> 12066068 [m^2]
units(area) <- "ha"
area
#> 1206.607 [ha]

^{Created on 2023-07-03 with reprex v2.0.2}