Scheme for naming resources and indicators

[goergen95]

As discussed in #236, we already implemented a better register functionality. We also raised the question there if re-naming (some) resources/indicators could be useful. Since this is not the first time we are considering renaming, I would like to use the opportunity to discuss a definition of how we would like to name things here.

I see the following items as relevant:

• names for resources should indicate the source as well as what the data represents. As en example consider get_chirps_prec() and get_worldclim_prec() where a simple get_prec() would not be sufficient to differentiate unless we were to merge the routines

• that also begs the question how granular we expect the get_*() functions to be. If we were to implement a get_prec() function from the example above, users would have to decide between using either of the sources. It is somewhat similar to what is happening in soilgrids which is currently framed as one resource but there are actually >10 underlying data layers. Should each of these actually get its own get_-function?

• for indicators I would propose to add a suffix to that indicates the type of indicator one can expect. The question is if the following vocabulary is comprehensive enough: area, stat, count

• similar to resources we will have to answer the question of granularity, e.g. is there only one calc_prec_stat() function of do we stay with an implementation like calc_worldclim_prec_stat() and calc_chirps_prec_stat()

• will we allow the same name between resources and indicators? Say we have get_gsw_change() and calc_gsw_change(), now ?gsw_change is ambiguous - does it refer to the resource or the indicator? If we allow this, the only way to get to the docs of a given resource/indicator will be to call the help on the function (e.g. ?get_gsw_change()).

• are there any other considerations currently missing here?

Edit: The Current column revers to the implementation in the dev branch which is bound to be merged and released end of April 2024.

With these considerations is mind here is a first proposal:

Resources

Current	New
get_chirps	get_chirps
get_esalandcover	get_gcls_lcc
get_fritz_et_al	get_iiasa_drivers
get_gfw_emissions	get_gfw_emissions
get_gfw_lossyear	get_gfw_lossyear
get_gfw_treecover	get_gfw_treecover
get_gmw	get_gmw_extent
get_global_surface_water_change	get_gsw_change
get_global_surface_water_transitions	get_gsw_transition
get_global_surface_water_seasonality	get_gsw_seasonality
get_global_surface_water_recurrence	get_gsw_reccurence
get_global_surface_water_occurrence	get_gsw_occurrence
get_nasa_firms	get_nasa_firms
get_nasa_grace	get_nasa_grace
get_nasa_srtm	get_nasa_srtm
get_nelson_et_al	get_traveltime
get_soilgrids	?get_soilgrids?
get_teow	get_teow
get_ucdp_ged	get_ucdp_ged
get_worldclim_min_temperature	get_worldclim_tmin
get_worldclim_max_temperature	get_worldclim_tmax
get_worldclim_precipitation	get_worldclim_prec
get_worldpop	get_worldpop_ucglobal

: Re-naming scheme for resources.

Indicators

Current	New
calc_active_fire_counts	calc_fire_count
calc_active_fire_properties	calc_fire_stat
calc_biome	calc_biome_area
calc_deforestation_drivers	calc_def_drivers_area
calc_drought_indicator	calc_soilwetness_stat
calc_ecoregion	calc_ecoregion_area
calc_elevation	calc_elevation_stat
calc_fatatlities	calc_fatalities_count
calc_gsw_change	calc_gsw_change_stat
calc_gsw_recurrence	calc_gsw_occurrence_area
calc_gsw_recurrence	calc_gsw_recurrence_area
calc_gsw_seasonality	calc_gsw_seasonality_area
calc_gsw_transition	calc_gsw_transitions_area
calc_landcover	calc_landcover_area
calc_mangroves_area	calc_mangroves_area
calc_population_count	calc_population_count
calc_precipitation_chirps	calc_chirps_prec_stat
calc_precipitation_wc	calc_worldclim_prec_sta
calc_soilproperties	calc_soilgrids_stat
calc_temperature_max_wc	calc_worldclim_tmax_stat
calc_temperature_min_wc	calc_worldclim_tmin_stat
calc_traveltime	calc_traveltime_stat
calc_treecover_area	calc_treecover_area
calc_treecoverloss_emissions	calc_treecover_emissions_stat
calc_treecover_area_and_emissions	calc_treecover_area_emissions
calc_tri	calc_tri_stat

: Re-naming scheme for indicators