Route choice docs and adjusting

[pedrocamargo]

Adds route choice capabilities to AequilibraE. Items still missing:

• [x] Include treatment of cases where the network is disconnected for a given OD pair
• [x] Adding documentation for choice set generation (modeling_with_aequilibrae/route_choice/choice_set_generation.rst)
• [x] Adding example for the creation of route choice sets
• [x] Adding documentation for route choice (modeling_with_aequilibrae/route_choice/route_choice_model.rst)
• [x] Add a map with assignment results to the route choice example
• [x] Make the cutoff probability intuitive (I would expect a value of 0.01 to exclude all routes that have a probability os less than 1%)
• [x] Update API for route choice (prepare graph with utility and provide only path overlap parameter)

[janzill]

@Jake-Moss it looks like we calculate path overlap factors before excluding paths with the provided minimum probability parameter. However, we want to exclude these paths from the choice set, which means we want to calculate path overlap factors AFTER exclusion.

[janzill]

We might also want to think about using the minimum probability as an early stopping criterion for path searches.

[Jake-Moss]

@Jake-Moss it looks like we calculate path overlap factors before excluding paths with the provided minimum probability parameter. However, we want to exclude these paths from the choice set, which means we want to calculate path overlap factors AFTER exclusion.

Ah damn, we are too. Shouldn't be a difficult fix

[pedrocamargo]

@janzill , since we are saying that utility is positive and the negative sign is in the computation itself, then I think we should do three things:

• Make sure the math is correct also for the binary logit
• Document that assumption (needed to compute paths, actually)

[janzill]

@janzill , since we are saying that utility is positive and the negative sign is in the computation itself, then I think we should do three things:

• Make sure the math is correct also for the binary logit
• Document that assumption (needed to compute paths, actually)

Hm, maybe we should refer to cost instead of utility. The cost of a link is a measure that has to be positive for the shortest path algorithm to work, and we need our total cost to be the sum of link costs. The observed utility in the path size logit calculations is then the negative path cost plus parameter times path overlap term (which itself is calculated with link costs). I double-checked, the maths should be correct using cost.