This release adds the capacity to run region-aware chains, makes some major updates to the documentation, and resolves quite a few of the long-standing issues on the repo.
What's Changed
- Major updates have been made to all of the documentation to try to make it
(i) More complete
(ii) More accessible for new Python users
- Bipartition Tree now has max_attempts default set to 100000 to prevent infinite loop conditions, but this value should also give plenty of time to sample sufficiently from the set of spanning trees.
- The `recom` method now has functionality for running region-aware chains which allow for the construction of ensembles of districting plans that try not to split a particular region or set of regions
- An updater `tally_region_splits` has been added to make quick tallying of the number of splits of a region type easy
- Many of the issue tickets have been resolved. See below for more info.
Deprecations
- Installation through conda-forge is no longer supported
- Python 3.8 is no longer supported due to deprecated support in dependencies
- We no longer support `gerrychain.random` for setting seeds. Instead, import the `random` module and set the random seed using `random.seed(<seed-number>)`
Resolved Issues
- \412 Resolved due to deprecation of conda-forge
- \409 Related to the following issue:
- \325 *SOME* Partition objects are pickle-able, but not all. Any partition that uses an updater defined in terms of a lambda function or which contains an inner function that uses nonlocal data will not be pickle-able, and we want to maintain this functionality. For those wishing to store an entire chain state, please see the [PCompress](https://github.com/mggg/pcompress) tool.
- \408 Resolved with deprecation of the conda-forge
- \364: The global random seed is no longer set in a custom random file. The user must now set the seed manually if they wish for their work to be reproducible.
- \319 is now fixed for recom. In `bipartition_tree` the user may now specify the parameter `allow_pair_reslection` as true or false. The default is false to maintain backward compatibility, but in the case where this parameter is set to true, an error is propagated back up to `recom` and a new pair is selected there. The selection of the new pair does not advance the chain. See the documentation for more information.
- \294 This is now a part of the "Good Data Practices" section of the documentation
- \288 `__repr__` methods have been added across the package
- \235 The MarkovChain class now has an alias `constraints` for the `is_valid` property that allows for the printing and editing of constraints. For example. one may print the constraints with the call `print(chain.constraints)` which will print something like `[<function single_flip_contiguous at 0x7f3d80f45b20>]`, and the constraints can be set with something like `chain.constraints = [contiguous]`. When set, the constraints are checked against the initial state of the chain. This improves the UX by making it so that you do not need to reinitialize a full MarkovChain object to experiment with different constraints.
- \279 This has been partially addressed in the documentation update and the remaining reference materials for how to plot data are left to the documentation of [matplotlib](https://matplotlib.org/) and [seaborn](https://seaborn.pydata.org/)
- \44 This is now a part of the documentation.
Acknowledgements
Special thanks to gabeschoenbach for his work on an earlier version of the Region Aware functionality for this release!
**Full Changelog**: https://github.com/mggg/GerryChain/compare/v0.2.22...v0.3.0