From 2b8a4bacf0be3faaff152de3d91497be5fc43d75 Mon Sep 17 00:00:00 2001 From: peterrrock2 Date: Wed, 28 Feb 2024 22:44:53 -0700 Subject: [PATCH 1/9] Change to min sp. tree and make region-preferential cut selector --- .gitignore | 1 + docs/user/recom.rst | 65 +++--- gerrychain/proposals/tree_proposals.py | 22 +- gerrychain/tree.py | 135 ++++++++++--- tests/test_region_aware.py | 265 ++++++++++++++----------- tests/test_reproducibility.py | 2 +- 6 files changed, 291 insertions(+), 199 deletions(-) diff --git a/.gitignore b/.gitignore index ccc4a583..1b4b309f 100644 --- a/.gitignore +++ b/.gitignore @@ -64,6 +64,7 @@ target/ # pyenv python configuration file .python-version .venv +.docs_venv junit.xml # crapple diff --git a/docs/user/recom.rst b/docs/user/recom.rst index 5e45f9b9..7334a772 100644 --- a/docs/user/recom.rst +++ b/docs/user/recom.rst @@ -176,7 +176,7 @@ Fortunately, ``gerrychain`` has a built-in functionality that allows for region-aware ReCom chains which create ensembles of districting plans that try to keep particular regions of interest together. And it only takes one extra line of code: we simply update -our proposal to include a ``weight_dict`` which increases the importance of the +our proposal to include a ``region_surcharge`` which increases the importance of the edges within the municipalities. .. code-block:: python @@ -187,7 +187,7 @@ edges within the municipalities. pop_target=ideal_population, epsilon=0.01, node_repeats=2, - weight_dict={"muni": 0.8}, + region_surcharge={"muni": 0.8}, ) And this will produce the following ensemble: @@ -210,7 +210,7 @@ and so it is not going to be possible to keep all of the water districts togethe and all of the municipalities together in one plan. However, we can try to keep the water districts together as much as possible, and then, within those water districts, try to be sensitive to the boundaries of the municipalities. Again, -this only requires for us to edit the ``weight_dict`` parameter of the proposal +this only requires for us to edit the ``region_surcharge`` parameter of the proposal .. code-block:: python @@ -220,7 +220,7 @@ this only requires for us to edit the ``weight_dict`` parameter of the proposal pop_target=ideal_population, epsilon=0.01, node_repeats=2, - weight_dict={"muni": 0.2, "water": 0.8}, + region_surcharge={"muni": 0.2, "water": 0.8}, ) Since we are trying to be sensitive to multiple bits of information, we should probably @@ -251,45 +251,44 @@ while also being sensitive to the municipalities :align: center The last map in the ensemble from the 10000 step region-aware ReCom chain with - weights of 0.2 for the municipalities and 0.8 for the water districts. + surcharges of 0.2 for the municipalities and 0.8 for the water districts. .. raw:: html
- +
Municipalities of Gerrymandria
- +
Water Districts of GerryMandria
-.. _weight-dict-warning: -.. attention:: +.. .. attention:: - The ``weight_dict`` parameter is a dictionary that assigns a weight to each - edge within a particular region that is determined by the keys of the dictionary. - In the event that multiple regions are specified, the weights are added together, - and if the weights add to more than 1, then the following warning will be printed - to the user: +.. The ``region_surcharge`` parameter is a dictionary that assigns a surcharge to each +.. edge within a particular region that is determined by the keys of the dictionary. +.. In the event that multiple regions are specified, the surcharges are added together, +.. and if the surcharges add to more than 1, then the following warning will be printed +.. to the user: - .. code-block:: console +.. .. code-block:: console - ValueWarning: - The sum of the weights in the weight dictionary is greater than 1. - Please consider normalizing the weights. +.. ValueWarning: +.. The sum of the surcharges in the surcharge dictionary is greater than 1. +.. Please consider normalizing the surcharges. - It is generally inadvisable to set the weight of a region to 1 or more. When - using :meth:`~gerrychain.proposals.recom` with a ``weight_dict``, the proposal - will try to draw a minimum spanning tree using Kruskal's algorithm where, - the weights are in the range :math:`[0,1]`, then the weights from the weight - dictionary are added to them. In the event that - many edges within the tree have a weight above 1, then it can sometimes - cause the biparitioning step to stall. +.. It is generally inadvisable to set the surcharge of a region to 1 or more. When +.. using :meth:`~gerrychain.proposals.recom` with a ``region_surcharge``, the proposal +.. will try to draw a minimum spanning tree using Kruskal's algorithm where, +.. the surcharges are in the range :math:`[0,1]`, then the surcharges from the surcharge +.. dictionary are added to them. In the event that +.. many edges within the tree have a surcharge above 1, then it can sometimes +.. cause the biparitioning step to stall. What to do if the Chain Gets Stuck @@ -334,7 +333,7 @@ district, then the chain will get stuck and throw an error. Here is the setup: pop_target=ideal_population, epsilon=0.01, node_repeats=1, - weight_dict={"muni": 1.0, "water_dist": 1.0}, + region_surcharge={"muni": 1.0, "water_dist": 1.0}, ) recom_chain = MarkovChain( @@ -355,10 +354,6 @@ This will output the following sequence of warnings and errors .. code-block:: console - ValueWarning: - The sum of the weights in the weight dictionary is greater than 1. - Please consider normalizing the weights. - BipartitionWarning: Failed to find a balanced cut after 50 attempts. If possible, consider enabling pair reselection within your @@ -374,12 +369,6 @@ Let's break down what is happening in each of these: .. raw:: html