custom start and end for route_migration

[slager]

I think it could maybe be useful to also be able to pass custom start and end inputs to route_migration, that would be processed by lookup_timestep to replace the season argument. Running into this with a species where I disagree with the eBird S&T assigned dates for the end of migration. I could also see this being useful for plenty of other applications, like shorter-term predictions of where birds go.

[ethanplunkett]

I had thought of route() as the general purpose function and route_migration() as doing one very specific thing. That said, in addition to easily setting seasons (which we've now also added to route()) route_migration() handles sampling starting locations from the initial distribution where as route() doesn't. After the proposed change this sampling of starting locations will be the only difference, so I wonder if we should rename it: maybe route_from_distr() , route_from_sample() , or sample_and_route(). I don't love any of those new names but like the first best.

[ethanplunkett]

Currently route() has these arguments:

route(
  x,
  x_coord,  y_coord,
  n_each,
  row, col,   
  start,  end,  direction, season_buffer, n  # passed to lookup_timestep_sequence()
)

While route_migration() has:

route_migration(bf, 
                n, 
                migration = "prebreeding",
                season_buffer = 1)

After the change it would be:

route_migration(bf, 
                n_routes,    # Renamed to not conflict with n argument to lookup_timestep_sequence()
                start = "prebreeding",
                ... )  # additional arguments passed to lookup_timestep_sequence()

or

route_migration(bf, 
                n_routes,    # Renamed to not conflict with n argument to lookup_timestep_sequence()
                start = "prebreeding",  
                end,  direction, season_buffer, n)  #additional arguments passed to lookup_timestep_sequence() 

[ethanplunkett]

We could also add a function to customize the species metadata in a BirdFlow object, and/or you could edit the bf$species list directly. I have mixed feelings about this as it would be nice to make it clear that the resulting dates weren't from eBird S&T. We could for instance allow optional "custom_" versions in the species list that would be preferentially used (if present) when looking up the migration dates, along with a function set_custom_date(bf, name, date). I'm not pushing for this, just brainstorming.

[slager]

An alternative approach keeping things more modular could be to wrap this messy part into a helper function:

  locations <- sample_distr(get_distr(bf, start, from_marginals = TRUE), 
    n = n)
  if (n == 1) {
    ind <- which(as.logical(locations))
  }
  else {
    ind <- apply(locations, 2, function(x) which(as.logical(x)))
  }
  x <- i_to_x(ind, bf)
  y <- i_to_y(ind, bf)

And return list(x = ..., y= ...)

Then user could do something like this:

sample_distrib_new_fn(bf, start, n, from_marginals = TRUE) -> out
route(bf, out$x, out$y, lookup_timestep(mystart), lookup_timestep(myend))

[slager]

I think I'd rather think of the ebirdST data (prebreeding start, etc) within the bf object as coming directly from S&T and not modify it.

[ethanplunkett]

An alternative approach keeping things more modular could be to wrap this messy part into a helper function:
...
sample_distr() now handles the messy part.

start  <- 5
end <- 16
d <- get_distr(bf, 5)
xy <- sample_distr(d, n = 10, bf = bf, format = "xy")
rts <- route(bf, x_coord = xy$x, y_coord = xy$y, start = start, end = end)
plot_routes(rts, bf)

https://birdflow-science.github.io/BirdFlowR/reference/sample_distr.html

[ethanplunkett]

I think I'm going to merge route_migration() into route() so one function handles everything.

• Drop row and col arguments. I don't think anyone uses them and c_to_x() and r_to_y() can handle conversion if necessary.
• Make x and y optional. If they are missing then sample n_each starting locations from the starting timestep distribution.
• Replace start, end, direction, season_buffer, n with ... passed to lookup_timestep_sequence()
• Add from_marginals = FALSE to arguments. Set to TRUE to get distributions from marginals rather than the training eBird S&T distributions. [Added after comment below]

After #110 we then can replace route_migration(bf, n = 5) with route(bf, season = "prebreeding", n_each = 5) and still be able to specify specific starting positions e.g. with route(bf, x_coord = x, y_coord = y, ...)

@slager does that work for you? After the discussion above the only remaining difference between the two functions was whether the starting locations are sampled from the distributions.

[slager]

That works. It could be nice to have a flag to sample from ebirdst distribution or sample from model marginal distribution.

[ethanplunkett]

You can now do everything with route(). To have the function sample the starting locations leave x_coord and y_coord NULL:

rts <- route(bf, n = 10, season = "prebreeding") 

You can use any of the time arguments supported by lookup_timestep_sequence() so custom date or timestep ranges also work:

rts <- route(bf, n=10, start = "2023-04-07", end = "2023-07-14")