diff --git a/README.rst b/README.rst index be103612..9071b3e3 100644 --- a/README.rst +++ b/README.rst @@ -66,8 +66,128 @@ Useful links Installation ============ -Using ``pip`` -------------- +Supported Python Versions +------------------------- + +The most recent version of GerryChain (as of February 2024) supports + +- Python 3.9 +- Python 3.10 +- Python 3.11 + +If you do not have one of these versions installed on you machine, we +recommend that you go to the +`Python website `_ and +download the installer for one of these versions. [1]_ + +A Note for Windows Users +++++++++++++++++++++++++ + + If you are using Windows and are new to Python, we recommend that you + still install Python using the installation package available on + the Python website. There are several versions of Python available + on the Windows Store, but they can be... finicky, and experience seems + to suggest that downloadable available on the Python website produce + better results. + + In addition, we recommend that you install the + `Windows Terminal `_ + from the Microsoft Store. It is still possible to use PowerShell or + the Command Prompt, but Windows Terminal tends to be more beginner + friendly and allows for a greater range of utility than the natively + installed terminal options (for example, it allows for you to install + the more recent version of PowerShell, + `PowerShell 7 `_, + and for the use of the Linux Subsystem for Windows). + + +Setting Up a Virtual Environment +-------------------------------- + +Once Python is installed on your system, you will want to open the terminal +and navigate to the working directory of your project. Here are some brief +instructions for doing so on different systems: + +- **MacOS**: To open the terminal, you will likely want to use the + Spotlight Search (the magnifying glass in the top right corner of + your screen) to find the "Terminal" application (you can also access + Spotlight Search by pressing "Command (⌘) + Space"). Once you have + the terminal open, type ``cd`` followed by the path to your working + directory. For example, if you are working on a project called + ``my_project`` in your ``Documents`` folder, you may access by typing + the command + + .. code-block:: console + + cd ~/Documents/my_project + + into the terminal (here the ``~`` is a shortcut for your home directory). + If you do not know what your working directory is, you can find it by + navigating to the desired folder in your file explorer, and clicking + on "Get Info". The path will be labeled "Where" and from there you + can copy the path to your clipboard and paste it in the terminal. + + +- **Linux**: Most Linux distributions have the keyboard shortcut + ``Ctrl + Alt + T`` set to open the terminal. From there you may navigate + to your working directory by typing ``cd`` followed by the path to your + working directory. For example, if you are working on a project called + ``my_project`` in your ``Documents`` folder, you may access this via + the command + + .. code-block:: console + + cd ~/Documents/my_project + + (here the ``~`` is a shortcut for your home directory). If you do not + know what your working directory is, you can find it by navigating to + the desired folder in your file explorer, and clicking on "Properties". + The path will be labeled "Location" and from there you can copy the path + to your clipboard and paste it in the terminal (to paste in the terminal + in Linux, you will need to use the keyboard shortcut ``Ctrl + Shift + V`` + instead of ``Ctrl + V``). + +- **Windows**: Open the Windows Terminal and type ``cd`` followed by the + path to your working directory. For example, if you are working on a + project called ``my_project`` in your ``Documents`` folder, you may + access this by typing the command + + .. code-block:: console + + cd ~\Documents\my_project + + into the terminal (here the ``~`` is a shortcut for your home directory). + If you do not know what your working directory is, + you can find it by navigating to the desired folder in your file + explorer, and clicking on "Properties". The path will be labeled + "Location" and from there you can copy the path to your clipboard + and paste it in the terminal. + + +Once you have navigated to your working directory, you will want to +set up a virtual environment. This is a way of isolating the Python +packages you install for this project from the packages you have +installed globally on your system. This is useful because it allows +you to install different versions of packages for different projects +without worrying about compatibility issues. To set up a virtual +environment, type the following command into the terminal: + +.. code-block:: console + + python -m venv .venv + +This will create a virtual environment in your working directory which +you can see if you list all the files in your working directory via +the command ``ls -a`` (``dir`` on Windows). Now we need to activate the +virtual environment. To do this, type the following command into the +terminal: + +- **Windows**: ``.venv\Scripts\activate`` +- **MacOS/Linux**: ``source .venv/bin/activate`` + +You should now see ``(.venv)`` at the beginning of your terminal prompt +now. This indicates that you are in the virtual environment, and are now +ready to install GerryChain. To install GerryChain from PyPI_, run ``pip install gerrychain`` from the command line. @@ -78,40 +198,120 @@ adjacencies or reading in shapefiles, then run This approach sometimes fails due to compatibility issues between our different Python GIS dependencies, like ``geopandas``, ``pyproj``, -``fiona``, and ``shapely``. For this reason, we recommend installing -from conda-forge for users that encounter difficulty with PyPI_. +``fiona``, and ``shapely``. If you run into this issue, try installing +the dependencies using the `geo_settings.txt <./geo_settings.txt>`_ +file. To do this, run ``pip install -r geo_settings.txt`` from the +command line. + +.. note:: + + If you plan on following through the tutorials present within the + remainder of this documentation, you will also need to install + ``matplotlib`` from PyPI_. This can also be accomplished with + a simple invocation of ``pip install matplotlib`` from the command + line. .. _PyPI: https://pypi.org/ +.. [1] Of course, if you are using a Linux system, you will either need to use your + system's package manager or install from source. You may also find luck installing + Python directly from the package manager if you find installing from source to be + troublesome. -Using conda -------------------------- +Making an Environment Reproducible +---------------------------------- -To install GerryChain from conda-forge_ using conda_, run +If you are working on a project wherein you would like to ensure +particular runs are reproducible, it is necessary to invoke -.. code-block:: console +- **MacOS/Linux**: ``export PYTHONHASHSEED=0`` +- **Windows**: - conda install -c conda-forge gerrychain + - PowerShell ``$env:PYTHONHASHSEED=0`` + - Command Prompt ``set PYTHONHASHSEED=0`` -For this command to work as intended, you will first need to activate -the conda environment that you want to install GerryChain in. If -the environment you want to activate is called ``vrdi`` (for example), -then you can do this by running +before running your code. This will ensure that the hash seed is deterministic +which is important for the replication of spanning trees across your runs. If you +would prefer to not have to do this every time, then you need to modify the +activation script for the virtual environment. Again, this is different depending +on your operating system: -.. code-block:: console +- **MacOS/Linux**: Open the file ``.venv/bin/activate`` located in your working + directory using your favorite text editor + and add the line ``export PYTHONHASHSEED=0`` after the ``export PATH`` command. + So you should see something like:: - conda activate vrdi + _OLD_VIRTUAL_PATH="$PATH" + PATH="$VIRTUAL_ENV/Scripts:$PATH" + export PATH -If this command causes problems, make sure conda is up-to-date by -running + export PYTHONHASHSEED=0 + + Then, verify that the hash seed is set to 0 in your Python environment by + running ``python`` from the command line and typing + ``import os; print(os.environ['PYTHONHASHSEED'])``. -.. code-block:: console +- **Windows**: To be safe, you will need to modify 3 files within your virtual + environment: + + - ``.venv\Scripts\activate``: Add the line ``export PYTHONHASHSEED=0`` after + the ``export PATH`` command. So you should see something like:: + + _OLD_VIRTUAL_PATH="$PATH" + PATH="$VIRTUAL_ENV/Scripts:$PATH" + export PATH + + export PYTHONHASHSEED=0 + + - ``.venv\Scripts\activate.bat``: Add the line ``set PYTHONHASHSEED=0`` to the + end of the file. So you should see something like:: + + if defined _OLD_VIRTUAL_PATH set PATH=%_OLD_VIRTUAL_PATH% + if not defined _OLD_VIRTUAL_PATH set _OLD_VIRTUAL_PATH=%PATH% + + set PATH=%VIRTUAL_ENV%\Scripts;%PATH% + rem set VIRTUAL_ENV_PROMPT=(.venv) + set PYTHONHASHSEED=0 + + - ``.venv\Scripts\Activate.ps1``: Add the line ``$env:PYTHONHASHSEED=0`` to the + end of the before the signature block. So you should see something like:: + + # Add the venv to the PATH + Copy-Item -Path Env:PATH -Destination Env:_OLD_VIRTUAL_PATH + $Env:PATH = "$VenvExecDir$([System.IO.Path]::PathSeparator)$Env:PATH" + + $env:PYTHONHASHSEED=0 + + # SIG # Begin signature block + +After you have made these changes, verify that the hash seed is set to 0 in your +Python environment by running ``python`` from the command line and typing +``import os; print(os.environ['PYTHONHASHSEED'])`` in the Python prompt. + +.. admonition:: A Note on Jupyter + :class: note + + If you are using a jupyter notebook, you will need to make sure that you have + installed the ``ipykernel`` package in your virtual environment as well as + either ``jypyternotebook`` or ``jupyterlab``. To install these packages, run + ``pip install `` from the command line. Then, to use the virtual + python environment in your jupyter notebook, you need to invoke + + .. code-block:: console + + jupyter notebook + + or + + .. code-block:: console + + jupyter lab - conda update conda - conda init + from the command line of your working directory *while your virtual environment + is activated*. This will open a jupyter notebook in your default browser. You may + then check that the hash seed is set to 0 by running the following code in a cell + of your notebook: -For more information on using conda to install packages and manage -dependencies, see `Getting started with conda`_. + .. code-block:: python -.. _`Getting started with conda`: https://conda.io/projects/conda/en/latest/user-guide/getting-started.html -.. _conda: https://conda.io/projects/conda/en/latest/ -.. _conda-forge: https://conda-forge.org/ + import os + print(os.environ['PYTHONHASHSEED'])