Improve documentation of weight_streetnet

[agila5]

Hi @mpadge! I’ve created this issue since I would like to ask for better documentation regarding the behaviour of weight_streetnet. For example:

# packages
library(dodgr)
library(sf)
#> Linking to GEOS 3.11.2, GDAL 3.7.2, PROJ 9.3.0; sf_use_s2() is TRUE

# Just one segment
toy <- st_as_sf(
  data.frame(osm_id = 1, highway = "cycleway"), 
  geometry = st_sfc(
    st_linestring(rbind(c(0, 0), c(1, 1)))
  )
)
weight_streetnet(toy)[1:8]
#>   geom_num edge_id from_id from_lon from_lat to_id to_lon to_lat
#> 1        1       1       0        0        0     1      1      1
#> 2        1       2       1        1        1     0      0      0

Everything is fine! However, if I add a oneway field and set its value equal to “yes”, the function returns just one edge.

toy <- st_as_sf(
  data.frame(osm_id = 1, highway = "cycleway", oneway = "yes"), 
  geometry = st_sfc(
    st_linestring(rbind(c(0, 0), c(1, 1)))
  )
)
weight_streetnet(toy)[1:8]
#>   geom_num edge_id from_id from_lon from_lat to_id to_lon to_lat
#> 1        1       1       0        0        0     1      1      1

I totally understand (and I like!) this behaviour but, unfortunately, I think it’s a bit surprising. For example, I cannot find anywhere in the docs:

1. which field names modify the behaviour of weight_streetnet?
2. what are the possible values for these fields?

I think this information is crucial for users. Apologies for the noise if this is already documented somewhere, but I could find any reference.

Thanks!

^{Created on 2024-09-20 with reprex v2.0.2}

[mpadge]

That's a really good point @agila5, and one I'll definitely update docs somewhere to address. The code should probably be improved there as well, because it currently assumes tagging strictly adheres to OSM recommendations of "yes" and "no" only, but there will always be rogue values of "true", "false", "0" and "1". I'll get on to it asap. thanks

[mpadge]

@agila5 Could you please have a look over PR #251 and let me know what you think? Or suggest any edits or improvements you can think of? Thanks!

[mpadge]

Re-opening to address this reprex of @agila5:

library(dodgr)
library(sf)
#> Linking to GEOS 3.11.2, GDAL 3.7.2, PROJ 9.3.0; sf_use_s2() is TRUE

# The default mode of transport is "bicycle" which contains the following
# highway types:
weighting_profiles$weighting_profiles[67:88, "way"]
#>  [1] "motorway"       "trunk"          "primary"        "secondary"     
#>  [5] "tertiary"       "unclassified"   "residential"    "service"       
#>  [9] "track"          "cycleway"       "path"           "steps"         
#> [13] "ferry"          "living_street"  "bridleway"      "footway"       
#> [17] "pedestrian"     "motorway_link"  "trunk_link"     "primary_link"  
#> [21] "secondary_link" "tertiary_link"

# For example
toy <- st_as_sf(
  data.frame(highway = "primary", cycleway = c("A", "B"), osm_id = 1:2), 
  geometry = st_sfc(
    st_linestring(rbind(c(0, 0), c(1, 1))), 
    st_linestring(rbind(c(1, 1), c(2, 2)))
  )
)
weight_streetnet(toy) # cycleway is retained
#>   geom_num edge_id from_id from_lon from_lat to_id to_lon to_lat        d
#> 1        1       1       0        0        0     1      1      1 156899.6
#> 2        1       2       1        1        1     0      0      0 156899.6
#> 3        2       3       1        1        1     2      2      2 156876.1
#> 4        2       4       2        2        2     1      1      1 156876.1
#>   d_weighted highway way_id component cycleway     time time_weighted
#> 1   224142.2 primary      1         1        A 37655.90      53794.14
#> 2   224142.2 primary      1         1        A 37655.90      53794.14
#> 3   224108.8 primary      2         1        B 37650.28      53786.11
#> 4   224108.8 primary      2         1        B 37650.28      53786.11

# Same structure but considering 
toy <- st_as_sf(
  data.frame(highway = "primary", path = c("A", "B"), osm_id = 1:2), 
  geometry = st_sfc(
    st_linestring(rbind(c(0, 0), c(1, 1))), 
    st_linestring(rbind(c(1, 1), c(2, 2)))
  )
)
weight_streetnet(toy) # path is not retained
#>   geom_num edge_id from_id from_lon from_lat to_id to_lon to_lat        d
#> 1        1       1       0        0        0     1      1      1 156899.6
#> 2        1       2       1        1        1     0      0      0 156899.6
#> 3        2       3       1        1        1     2      2      2 156876.1
#> 4        2       4       2        2        2     1      1      1 156876.1
#>   d_weighted highway way_id component     time time_weighted
#> 1   224142.2 primary      1         1 37655.90      53794.14
#> 2   224142.2 primary      1         1 37655.90      53794.14
#> 3   224108.8 primary      2         1 37650.28      53786.11
#> 4   224108.8 primary      2         1 37650.28      53786.11