birdflow-science / BirdFlowR

BirdFlow R Package
https://birdflow-science.github.io/BirdFlowR/
MIT License
10 stars 2 forks source link

as_routes() - function to convert movement data to BirdFlowRoutes object. #158

Open ethanplunkett opened 9 months ago

ethanplunkett commented 9 months ago

as_route()

Alternate name possibilities: convert_to_route() as.BirdFlowRoutes() (method of generic as),

Most of the work is already done by snap_to_birdflow(), issue #155, pr #157

This would be a wrapper to snap_to_birdflow() that makes the output a formal BirdFlowRoutes object.

At a minimum it needs to:

  1. Call snap_to_birdflow()
  2. Create a (likely new) "route_id" that server as a unique ID for every combination of values in id_cols
  3. Assign the BirdFlowRoutes class
  4. Add information from bf to the attributes.
  5. Set metadata$route_type to something possibly set by an additional argument. Output of route() uses "synthetic" we need to figure out what types we allow for real data. I suspect it might be good to keep track of sensor type something like: "gps", "light" "modis", "banding". The MigConnectivity package has names it uses for different sensor types, be consistent with their terms if reasonable.
  6. Possibly collect other metadata (aggregation method, mean number of points per week, ???)

A few other related cleanup items:

  1. See if it's worth calling snap_to_birdflow() from interval_log_likelihood() to eliminate redundant code.
  2. Error codes in interval_log_likelihood() are slightly different than snap_to_birdflow() standardize them.
  3. BirdFlowRoutes produced by route() have a different column order than snap_to_birdflow(). Standardize.
  4. Possibly save some stats during aggregation on the dispersion of the points that were aggregated.
ethanplunkett commented 9 months ago

Specifications and expectations of BirdFlowRoute objects

  1. Single species.
  2. Maximum length of 1 year per route id. This is logistically required by plot_routes(). Unclear whether it's OK to start and end on the same timestep (OK with current synthetic routes, maybe not with @slager's working specification)
  3. At most one point per route per timestep.
  4. Dates are monotonic within a route ID (rows are ordered by date) and all routes are either forward or backwards within a single route object. Backwards only really makes sense with synthetic routes but is an option there.
  5. There can be gaps in timesteps but not NAs.
ethanplunkett commented 7 months ago

When calculating track stats we shouldn't be limiting the track to locations the model thinks is valid. Therefore this function and snap_to_birdflow() need an argument - maybe valid_only - that controls whether the output should be limited to valid locations.

ethanplunkett commented 3 months ago

plot_routes() is now used for real data and for synthetic routes generated in python, as well as for the output of route(). It needs to be more robust and make fewer assumptions about the data. Switching from cyclical to monotonic dates will help a lot. Dropping any use of timesteps in the plotting code would also be good.