README.md

feems

Fast Estimation of Effective Migration Surfaces (feems) is a python package implementing a statistical method for inferring and visualizing gene-flow in spatial population genetic data.

The feems method and software was developed by Joe Marcus and Wooseok Ha and advised by Rina Foygel Barber and John Novembre. We also used code from Benjamin M. Peter to help construct the spatial graphs.

For details on the method see our pre-print. Note that feems is in review so the method could be subject to change.

Note: MS Windows users will struggle to install feems directly in a Windows environment because at least one of the dependencies does not have a Windows port. A virtual Linux machine should be preferable if you are on a Windows machine.

Quick start using bioconda

Typically the simplest way to get started with feems is to install Anaconda or Miniconda, then install feems using the Bioconda recipe:

conda install -c bioconda feems -c conda-forge

See the next section for alternative ways to install feems, or if "conda install" worked for you, skip ahead to "Running feems".

Alternative installation instructions (Python 3.8)

As an alternative way to get started, setup a conda environment:

conda create -n=feems_e python=3.8.3 
conda activate feems_e

Some of the plotting utilities in the feems package require geos as a dependency which can be installed on mac with brew as follows:

brew install geos

Unfortunately some of the other dependencies for feems are not easily installed by pip so we recommend getting started using conda:

conda install numpy==1.22.3 scipy==1.5.0 scikit-learn==0.23.1
conda install matplotlib==3.2.2 pyproj==2.6.1.post1 networkx==2.4.0 
conda install shapely==1.7.1 
conda install fiona
conda install pytest==5.4.3 pep8==1.7.1 flake8==3.8.3
conda install click==7.1.2 setuptools pandas-plink
conda install msprime==1.0.0 statsmodels==0.12.2 PyYAML==5.4.1
conda install xlrd==2.0.1 
conda install openpyxl==3.0.7
conda install suitesparse=5.7.2
conda install scikit-sparse=0.4.4 
conda install cartopy=0.18.0

Jupyter and jupyterlab are also needed to explore some example notebooks but these are not necessary for the feems package.

Once the conda environment has been setup with these tricky dependencies we can install feems:

pip install git+https://github.com/NovembreLab/feems

You can also install feems locally by:

git clone https://github.com/NovembreLab/feems
cd feems/
pip install .

NOTE: Some users have reported a compatibility error arising at this step with the installation of shapely v1.7.1 (specificed in requirements.txt). If this arises, recreate the feems_e conda environment, and run pip install shapely --no-binary shapely==1.7.1 before the pip install feems command above.

Running feems

To help get your analysis started, we provide an example workflow in the getting-started.ipynb notebook. The notebook analyzes empirical data from North American gray wolves populations published in Schweizer et al. 2015.

An example workflow using a λ value estimated from a cross-validation procedure is highlighted in cross-validation.ipynb. We recommend using this procedure in choosing an appropriate λ value for the fit.