Function to calculate migratory connectivity metric from routes-like object

[slager]

https://doi.org/10.1111/2041-210X.12916

@adokter and I have been discussing the possibility of a function to calculate MC from a routes-like object. The idea would be to calculate MC for real banding data (for example) and compare it to MC calculated on simulated data from a BirdFlow model.

The "regions" used to calculate MC could be the cells in a BirdFlow model, and breeding and wintering ranges could be calculated using the ebirdst-defined seasons. The breeding and wintering based MC metric could also just be thought of as a specific or aggregate case of a more generalized MC metric that takes into account the full time resolution of a weekly birdflow model.

@ethanplunkett how feasible do you think this sounds?

[ethanplunkett]

Approaches to estimating migratory connectivity (MC) worked out with @slager via private communication:

1. For BirdFlow model transition probabilities

   • Use MigConnectivity::calcConnectivity() to calculate connectivity. It has four primary arguments:
     • originDist, targetDist The output from BirdFlowR::great_circle_distances()` subset based on the dynamic mask for the starting and ending timesteps.
     • originRelAbund This is BirdFlowR::get_distr(bf, start) subset based on dynamic mask.
     • psi (transition probabilities) this is the transition matrix from the starting to ending timesteps. This can be calculated by multiplying the intervening single step transition matrices together.

2. For tracking data
   This is similar to 1 but adds the complication of calculating the transition matrix from one season to the next from the tracking data. We'd tally how many birds from each starting cell ended up in each ending cell and then dividing by the total number of birds in the starting cell. Without a LOT of tracking data many of the transitions are likely to be poorly estimated and/or zero. I don't know whether that will be an issue.

I think it might make sense to test empirically how increasing cells size to get fewer larger cells with better estimates on transition probabilities changes the outcome for tracked birds. We could also do a model experiment to get at the interactions between number of tracks, resolution, and MC based on synthetic routes. This would be elegant because we'd have the "true" modeled MC based on the transition matrices to compare to.

[ethanplunkett]

calc_birdflow_mc() in BirdFlowExtras now does (1) above.