Inconsistent example in "Using the time_window parameter" Vignettes and more on time_window

The time windows examples given in the paragraphs and code sections are not consistent in https://ipeagit.github.io/r5r/articles/time_window.html.

In section 3.2, the paragraph says, "In this example we calculate the number of schools accessible from each location within a 60-minute time window departing between 2pm and 3pm."

While the code section shows the time_window parameter is set to 30


# estimate accessibility
acc <- r5r::[accessibility](https://ipeagit.github.io/r5r/reference/accessibility.html)(r5r_core = r5r_core,   
                          origins = points,
                          destinations = points, 
                          opportunities_colnames = 'schools',
                          mode = mode,
                          max_walk_time = max_walk_time,
                          decay_function = "step",
                          cutoffs = 45,
                          departure_datetime = departure_datetime,
                          progress = FALSE,
                          time_window = 30,
                          percentiles = [c](https://rdrr.io/r/base/c.html)(10, 20, 50, 70, 80)
                          )

Does the time_windowwork in such a way that it will calculate both the 30 minutes before and after the departure_time? I guess it will only calculate 30 minutes after the departure_time. Please let me know which one is true.

However, in section 3.3, the paragraph says, "Now let’s calculate all-to-all travel time estimates within a 60-minute time window departing between 2pm and 3pm and see how the output looks like."

While the code section shows the time_windowparameter is set to 20. This one clearly is not right.,


# estimate travel time matrix
ttm <- [travel_time_matrix](https://ipeagit.github.io/r5r/reference/travel_time_matrix.html)(r5r_core = r5r_core,   
                          origins = points,
                          destinations = points,    
                          mode = mode,
                          max_walk_time = max_walk_time,
                          max_trip_duration = max_trip_duration,
                          departure_datetime = departure_datetime,
                          progress = TRUE,
                          time_window = 20,
                          percentiles = [c](https://rdrr.io/r/base/c.html)(10, 20, 50, 70, 80)
                          )

[head](https://rdrr.io/r/utils/head.html)(ttm, n = 10)

Meanwhile, due to these inconsistencies, I am also wondering if other functions like detailed_itineraries also have the same mechanism; I know detailed_itineraries has a time_windowparameter though, but I am still not sure if it would work.

I am also facing performance issue due to large amounts of OD pairs, so it would be better if I can change the interval of the time_window. In that sense, instead of 1 minute, 2 or 5 minutes would be better.

Hi @luyuliu, thanks for the heads up. The text in the vignette says it will use a 60-minute time window but the code did not follow along. I will fix this in my next commit to make sure the code in the vignette reflects what the text says.

Regarding your question, the time_window parameter considers a time window from the departure time onwards. So if you set a departure time at 10am and a time window of 25 minutes, r5r will simulate multiple departure times between 10:00am and 10:25am. In functions like travel_time_matrix() or accessibility(), for example, users have the flexibility to set the number of draws_per_minute. This behavior is similar in the detailed_itineraries(), but slightly different.

the behavior or `time_window` in the `detailed_itineraries()`

In the detailed_itineraries() function, the number of Monte Carlo draws per minute is hardcoded to 1. This means that the function simulates only one departure per minute within the time_window. So if you set a time_window of 10 minutes, it would simulate 10 departures, one in each minute. This is largely because the time_window behaves slightly differently here.

See, functions like travel_time_matrix() or accessibility(), for example, return estimates of travel times or accessibility. In these cases, when we use the time_window parameter, these functions output selected percentiles of those estimates generated based on the distribution of all estimates that result from the multiple trip simulations.

The detailed_itineraries(), on the other hand, does not return travel times or accessibility estimates. It returns alternatives of trip journeys. In this case, when we use the time_window parameter, the function will return the optimal (or sub-optimal) trip itineraries found within the time window. It does not make sense to aggregate these itinerary options in percentiles.

This is explained in the documentation of detailed_itineraries(), but please let us know how you think this could be made clearer. I realize this was not explained in the vignette, but it should. I'm adding this explanation to the vignette in my next commit.

how to improve computation time when using `detailed_itineraries()`

Setting time_window = 1 would improve the computation time but it might also affect your results. Other ways to speed computation here is to set drop_geometry = TRUE and to use the output_dir parameter.

Thank you for the thorough explanation!

Thanks @luyuliu . Closing this issue for now.

ipeaGIT / r5r