{"id":22441998,"url":"https://github.com/mggg/gerrychain","last_synced_at":"2025-04-05T00:06:01.983Z","repository":{"id":33146069,"uuid":"136683696","full_name":"mggg/GerryChain","owner":"mggg","description":"Use MCMC to analyze districting plans and gerrymanders","archived":false,"fork":false,"pushed_at":"2024-08-12T22:03:30.000Z","size":140326,"stargazers_count":134,"open_issues_count":15,"forks_count":76,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-03-28T23:04:07.375Z","etag":null,"topics":["gerrymandering","gis","mcmc","python"],"latest_commit_sha":null,"homepage":"https://mggg.github.io/GerryChain/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mggg.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-09T02:22:44.000Z","updated_at":"2025-03-26T12:22:17.000Z","dependencies_parsed_at":"2024-04-12T21:29:17.271Z","dependency_job_id":"e48024df-61b8-48bf-ad3b-e310ae361329","html_url":"https://github.com/mggg/GerryChain","commit_stats":{"total_commits":971,"total_committers":35,"mean_commits":"27.742857142857144","dds":0.5427394438722966,"last_synced_commit":"ee00d5df47b1929c03b0d0ed302c258ec68c5db0"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mggg%2FGerryChain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mggg%2FGerryChain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mggg%2FGerryChain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mggg%2FGerryChain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mggg","download_url":"https://codeload.github.com/mggg/GerryChain/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266563,"owners_count":20910836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gerrymandering","gis","mcmc","python"],"created_at":"2024-12-06T02:17:16.677Z","updated_at":"2025-04-05T00:06:01.968Z","avatar_url":"https://github.com/mggg.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"==========\nGerryChain\n==========\n\n.. image:: https://circleci.com/gh/mggg/GerryChain.svg?style=svg\n    :target: https://circleci.com/gh/mggg/GerryChain\n    :alt: Build Status\n.. image:: https://codecov.io/gh/mggg/GerryChain/branch/master/graph/badge.svg\n    :target: https://codecov.io/gh/mggg/GerryChain\n    :alt: Code Coverage\n.. image:: https://readthedocs.org/projects/gerrychain/badge/?version=latest\n    :target: https://gerrychain.readthedocs.io/en/latest\n    :alt: Documentation Status\n.. image:: https://badge.fury.io/py/gerrychain.svg\n    :target: https://pypi.org/project/gerrychain/\n    :alt: PyPI Package\n\nGerryChain is a Python library for building ensembles of districting plans\nusing `Markov chain Monte Carlo`_. It is developed and maintained by the\n`Metric Geometry and Gerrymandering Group`_ and our network of volunteers.\nIt is distributed under the `3-Clause BSD License`_.\n\nThe basic workflow is to start with the geometry of an initial plan and\ngenerate a large collection of sample plans for comparison. Usually, we\nwill constrain these sampled plans in such a way that they perform at\nleast as well as the initial plan according to traditional districting\nprinciples, such as population balance or compactness. Comparing the\ninitial plan to the ensemble provides quantitative tools for measuring\nwhether or not it is an outlier among the sampled plans.\n\n.. _`Voting Rights Data Institute`: http://gerrydata.org/\n.. _chain: https://github.com/gerrymandr/cfp_mcmc\n.. _`Markov chain Monte Carlo`: https://en.wikipedia.org/wiki/Markov_chain_Monte_Carlo\n.. _`Metric Geometry and Gerrymandering Group`: https://www.mggg.org/\n.. _`3-Clause BSD License`: https://opensource.org/licenses/BSD-3-Clause\n\n\nGetting started\n===============\n\nSee our `Getting started guide`_ for the basics of using GerryChain.\n\n.. _`Getting started guide`: https://gerrychain.readthedocs.io/en/latest/user/quickstart/\n\nWe also highly recommend the resources prepared by Daryl R. DeFord of MGGG\nfor the 2019 MIT IAP course `Computational Approaches for Political Redistricting`_.\n\n.. _`Computational Approaches for Political Redistricting`: https://people.csail.mit.edu/ddeford//CAPR.php\n\n\nUseful links\n============\n\n- `Documentation`_\n- `Bug reports and feature requests`_\n- `Contributions welcome!`_\n\n.. _`Documentation`: https://gerrychain.readthedocs.io/en/latest/\n.. _`Bug reports and feature requests`: https://github.com/mggg/gerrychain/issues\n.. _`Contributions welcome!`: https://github.com/mggg/gerrychain/pulls\n\n\nInstallation\n============\n\nSupported Python Versions\n-------------------------\n\nThe most recent version of GerryChain (as of April 2024) supports\n\n- Python 3.9\n- Python 3.10\n- Python 3.11\n\nIf you do not have one of these versions installed on you machine, we\nrecommend that you go to the \n`Python website \u003chttps://www.python.org/downloads/\u003e`_ and\ndownload the installer for one of these versions. [1]_\n\nA Note for Windows Users\n++++++++++++++++++++++++\n\n  If you are using Windows and are new to Python, we recommend that you\n  still install Python using the installation package available on \n  the Python website. There are several versions of Python available\n  on the Windows Store, but they can be... finicky, and experience seems\n  to suggest that downloadable available on the Python website produce\n  better results.\n\n  In addition, we recommend that you install the \n  `Windows Terminal \u003chttps://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701?activetab=pivot:overviewtab\u003e`_\n  from the Microsoft Store. It is still possible to use PowerShell or \n  the Command Prompt, but Windows Terminal tends to be more beginner\n  friendly and allows for a greater range of utility than the natively\n  installed terminal options (for example, it allows for you to install\n  the more recent version of PowerShell, \n  `PowerShell 7 \u003chttps://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell\u003e`_,\n  and for the use of the Linux Subsystem for Windows).\n\n\nSetting Up a Virtual Environment\n--------------------------------\n\nOnce Python is installed on your system, you will want to open the terminal\nand navigate to the working directory of your project. Here are some brief\ninstructions for doing so on different systems:\n\n- **MacOS**: To open the terminal, you will likely want to use the\n  Spotlight Search (the magnifying glass in the top right corner of\n  your screen) to find the \"Terminal\" application (you can also access\n  Spotlight Search by pressing \"Command (⌘) + Space\"). Once you have\n  the terminal open, type ``cd`` followed by the path to your working\n  directory. For example, if you are working on a project called\n  ``my_project`` in your ``Documents`` folder, you may access by typing\n  the command\n\n  .. code-block:: console\n\n    cd ~/Documents/my_project\n      \n  into the terminal (here the ``~`` is a shortcut for your home directory).\n  If you do not know what your working directory is, you can find it by\n  navigating to the desired folder in your file explorer, and clicking\n  on \"Get Info\". The path will be labeled \"Where\" and from there you\n  can copy the path to your clipboard and paste it in the terminal.\n\n\n- **Linux**: Most Linux distributions have the keyboard shortcut\n  ``Ctrl + Alt + T`` set to open the terminal. From there you may navigate\n  to your working directory by typing ``cd`` followed by the path to your\n  working directory. For example, if you are working on a project called\n  ``my_project`` in your ``Documents`` folder, you may access this via\n  the command\n  \n  .. code-block:: console\n\n    cd ~/Documents/my_project\n\n  (here the ``~`` is a shortcut for your home directory). If you do not\n  know what your working directory is, you can find it by navigating to\n  the desired folder in your file explorer, and clicking on \"Properties\".\n  The path will be labeled \"Location\" and from there you can copy the path\n  to your clipboard and paste it in the terminal (to paste in the terminal\n  in Linux, you will need to use the keyboard shortcut ``Ctrl + Shift + V``\n  instead of ``Ctrl + V``).\n\n- **Windows**: Open the Windows Terminal and type ``cd`` followed by the\n  path to your working directory. For example, if you are working on a\n  project called ``my_project`` in your ``Documents`` folder, you may\n  access this by typing the command\n\n  .. code-block:: console\n\n    cd ~\\Documents\\my_project\n\n  into the terminal (here the ``~`` is a shortcut for your home directory). \n  If you do not know what your working directory is,\n  you can find it by navigating to the desired folder in your file\n  explorer, and clicking on \"Properties\". The path will be labeled\n  \"Location\" and from there you can copy the path to your clipboard\n  and paste it in the terminal.\n\n\nOnce you have navigated to your working directory, you will want to\nset up a virtual environment. This is a way of isolating the Python\npackages you install for this project from the packages you have\ninstalled globally on your system. This is useful because it allows\nyou to install different versions of packages for different projects\nwithout worrying about compatibility issues. To set up a virtual\nenvironment, type the following command into the terminal:\n\n.. code-block:: console\n\n  python -m venv .venv\n\nThis will create a virtual environment in your working directory which\nyou can see if you list all the files in your working directory via\nthe command ``ls -a`` (``dir`` on Windows). Now we need to activate the\nvirtual environment. To do this, type the following command into the\nterminal:\n\n- **Windows**: ``.venv\\Scripts\\activate``\n- **MacOS/Linux**: ``source .venv/bin/activate``\n\nYou should now see ``(.venv)`` at the beginning of your terminal prompt\nnow. This indicates that you are in the virtual environment, and are now\nready to install GerryChain.\n\nTo install GerryChain from PyPI_, run ``pip install gerrychain`` from\nthe command line. \n\nIf you plan on using GerryChain's GIS functions, such as computing\nadjacencies or reading in shapefiles, then run\n``pip install gerrychain[geo]`` from the command line.\n\nThis approach sometimes fails due to compatibility issues between our\ndifferent Python GIS dependencies, like ``geopandas``, ``pyproj``,\n``fiona``, and ``shapely``. If you run into this issue, try installing\nthe dependencies using the `geo_settings.txt \u003chttps://github.com/mggg/GerryChain/tree/main/docs/geo_settings.txt\u003e`_\nfile. To do this, run ``pip install -r geo_settings.txt`` from the\ncommand line.\n\n.. note::\n\n  If you plan on following through the tutorials present within the\n  remainder of this documentation, you will also need to install\n  ``matplotlib`` from PyPI_. This can also be accomplished with\n  a simple invocation of ``pip install matplotlib`` from the command\n  line.\n\n.. _PyPI: https://pypi.org/\n.. [1] Of course, if you are using a Linux system, you will either need to use your\n  system's package manager or install from source. You may also find luck installing\n  Python directly from the package manager if you find installing from source to be\n  troublesome.\n\nMaking an Environment Reproducible\n----------------------------------\n\nIf you are working on a project wherein you would like to ensure\nparticular runs are reproducible, it is necessary to invoke\n\n- **MacOS/Linux**: ``export PYTHONHASHSEED=0``\n- **Windows**: \n\n  - PowerShell ``$env:PYTHONHASHSEED=0``\n  - Command Prompt ``set PYTHONHASHSEED=0``\n\nbefore running your code. This will ensure that the hash seed is deterministic\nwhich is important for the replication of spanning trees across your runs. If you\nwould prefer to not have to do this every time, then you need to modify the\nactivation script for the virtual environment. Again, this is different depending\non your operating system:\n\n- **MacOS/Linux**: Open the file ``.venv/bin/activate`` located in your working\n  directory using your favorite text editor\n  and add the line ``export PYTHONHASHSEED=0`` after the ``export PATH`` command. \n  So you should see something like:: \n\n    _OLD_VIRTUAL_PATH=\"$PATH\"\n    PATH=\"$VIRTUAL_ENV/Scripts:$PATH\"\n    export PATH\n\n    export PYTHONHASHSEED=0\n  \n  Then, verify that the hash seed is set to 0 in your Python environment by\n  running ``python`` from the command line and typing \n  ``import os; print(os.environ['PYTHONHASHSEED'])``.\n\n- **Windows**: To be safe, you will need to modify 3 files within your virtual\n  environment:\n\n  - ``.venv\\Scripts\\activate``: Add the line ``export PYTHONHASHSEED=0`` after\n    the ``export PATH`` command. So you should see something like:: \n\n      _OLD_VIRTUAL_PATH=\"$PATH\"\n      PATH=\"$VIRTUAL_ENV/Scripts:$PATH\"\n      export PATH\n\n      export PYTHONHASHSEED=0\n\n  - ``.venv\\Scripts\\activate.bat``: Add the line ``set PYTHONHASHSEED=0`` to the\n    end of the file. So you should see something like::\n\n      if defined _OLD_VIRTUAL_PATH set PATH=%_OLD_VIRTUAL_PATH%\n      if not defined _OLD_VIRTUAL_PATH set _OLD_VIRTUAL_PATH=%PATH%\n\n      set PATH=%VIRTUAL_ENV%\\Scripts;%PATH%\n      rem set VIRTUAL_ENV_PROMPT=(.venv) \n      set PYTHONHASHSEED=0\n\n  - ``.venv\\Scripts\\Activate.ps1``: Add the line ``$env:PYTHONHASHSEED=0`` to the\n    end of the before the signature block. So you should see something like::\n\n      # Add the venv to the PATH\n      Copy-Item -Path Env:PATH -Destination Env:_OLD_VIRTUAL_PATH\n      $Env:PATH = \"$VenvExecDir$([System.IO.Path]::PathSeparator)$Env:PATH\"\n\n      $env:PYTHONHASHSEED=0\n\n      # SIG # Begin signature block\n\nAfter you have made these changes, verify that the hash seed is set to 0 in your\nPython environment by running ``python`` from the command line and typing \n``import os; print(os.environ['PYTHONHASHSEED'])`` in the Python prompt.\n\n.. admonition:: A Note on Jupyter\n  :class: note\n\n  If you are using a jupyter notebook, you will need to make sure that you have\n  installed the ``ipykernel`` package in your virtual environment as well as\n  either ``jypyternotebook`` or ``jupyterlab``. To install these packages, run\n  ``pip install \u003cpackage-name\u003e`` from the command line. Then, to use the virtual\n  python environment in your jupyter notebook, you need to invoke\n  \n  .. code-block:: console\n\n    jupyter notebook\n\n  or\n\n  .. code-block:: console\n\n    jupyter lab\n\n  from the command line of your working directory *while your virtual environment\n  is activated*. This will open a jupyter notebook in your default browser. You may\n  then check that the hash seed is set to 0 by running the following code in a cell\n  of your notebook:\n\n  .. code-block:: python\n\n    import os\n    print(os.environ['PYTHONHASHSEED'])\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmggg%2Fgerrychain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmggg%2Fgerrychain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmggg%2Fgerrychain/lists"}