geodels / biolec Goto Github PK

View Code? Open in Web Editor NEW

4.0 2.0 3.0 20.2 MB

Landscape Elevational Connectivity package https://biolec.readthedocs.io/

License: GNU General Public License v3.0

Jupyter Notebook 55.34% Python 32.29% Dockerfile 1.74% Shell 7.55% Makefile 0.47% TeX 2.62%

biolec's Introduction

bioLEC - Landscape Elevational Connectivity Package

bioLEC documentation is found at biolec.readthedocs.io

bioLEC is a parallel python package built to calculate the Landscape elevational connectivity (LEC).

LEC quantifies the closeness of a site to all others with similar elevation. It measures how easily a species living in a given patch can spread and colonise other patches. It is assumed to be elevation-dependent and the metric depends on how often a species adapted to a given elevation needs to travel outside its optimal elevation range when moving from its patch to any other in the landscape [Bertuzzo et al., 2016].

Installation

Dependencies

You will need Python 2.7 or 3.5+. Also, the following packages are required:

Installing using pip

You can install bioLEC using the pip package manager with either version of Python:

python2 -m pip install bioLEC
python3 -m pip install bioLEC

Installing using Docker

A more straightforward installation which does not depend on specific compilers relies on the docker virtualisation system.

To install the docker image and test it is working:

   docker pull geodels/biolec:latest
   docker run --rm geodels/biolec:latest help

To build the dockerfile locally, we provide a script. First ensure you have checked out the source code from github and then run the script in the Docker directory. If you modify the dockerfile and want to push the image to make it publicly available, it will need to be retagged to upload somewhere other than the GEodels repository.

git checkout https://github.com/Geodels/bioLEC.git
cd bioLEC
source Docker/build-dockerfile.sh

Usage

Binder & docker container

Launch the demonstration at mybinder.org

Notebooks environment will not be the best option for large landscape models and we will recommend the use of the python script: runLEC.py in HPC environment. the code will need to be

mpirun -np 400 python runLEC.py

Or using the Docker container available through Kitematic geodels/biolec.

Collaborations

How to contribute?

We welcome all kinds of contributions! Please get in touch if you would like to help out.

Everything from code to notebooks to examples and documentation are all equally valuable so please don't feel you can't contribute.

To contribute please fork the project make your changes and submit a pull request. We will do our best to work through any issues with you and get your code merged into the main branch.

If you found a bug, have questions, or are just having trouble with bioLEC, you can:

join the bioLEC User Group on Slack by sending an email request to: [email protected]
open an issue in our issue-tracker and we'll try to help resolve the concern.

Where to find support?

Please feel free to submit new issues to the issue-log to request new features, document new bugs, or ask questions.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/lgpl-3.0.en.html.

References

E. Bertuzzo, F. Carrara, L. Mari, F. Altermatt, I. Rodriguez-Iturbe & A. Rinaldo - Geomorphic controls on species richness. PNAS, 113(7) 1737-1742, DOI: 10.1073/pnas.1518922113, 2016.
T.R. Etherington - Least-cost modelling and landscape ecology: concepts, applications, and opportunities. Current Landscape Ecology Reports 1:40-53, DOI: 10.1007/s40823-016-0006-9, 2016.
S. van der Walt , J.L. Schönberger, J. Nunez-Iglesias, F. Boulogne, J.D. Warner, N. Yager, E. Gouillart & T. Yu - Scikit Image Contributors - scikit-image: image processing in Python, PeerJ 2:e453, 2014.
T.R. Etherington - Least-cost modelling with Python using scikit-image, Blog, 2017.

biolec's People

Contributors

Stargazers

Watchers

Forkers

kyleniemeyer courtneysmith32 l5d1l5

biolec's Issues

JOSS Review: Notebook file structure confusing

Another issue as part of my JOSS Review

I cloned the repo and tried to run the notebooks locally.

After running jupyter notebook from the top level Notebooks directory I opened the 0-StartHere.ipynb notebooks. I then ran into 404 errors with the links to the other notebooks. I assume this is because the are actually located in bioLEC/src/bioLEC/Notebooks

I'd recommend that there is one place for the file structure where the notebooks are located. If for some reason related to Docker that means they need to be in both of these places, perhaps make a note on the ReadTheDocs regarding how to run the notebooks locally).

I poked around in the repo trying to figure out a fix and found the documentation.py file. This may or not matter, but it was not at all clear to me whether the file is vestigial or whether I should have been able to use it to solve my 404 error issues.

JOSS Review: Statement of need in RTFD

@tristan-salles I thought that the statement of need was very clear in the the paper.md but not as clear on the RTFD page.

link to JOSS Review

JOSS Review: Links to API in RTFD

Another comment related to my JOSS Review...

There are a number of places in the docs where I expected a link to the api documentation. For example the landscapeConnectivity() at the top of the Quickstart.

The package is overall really well linked, this sort of issue was the only one where I wanted links that weren't there. I find that this sort of link helps a lot when one is trying to teach themself from the documentation.

JOSS Review: Improvements to docstrings related to connectivity/boundary conditions

Comments from my JOSS Review regarding the contents of the documentation.

@tristan-salles Overall I found the docstrings (and their representation on RTFD) really nice. There was, however, one case where I couldn't figure something out from the docs that I think I should have been able to figure out.

I was not able to figure out the periodic and symmetric keyword arguments without looking at the figure presented in the notebook bioLEC1-genericCase.ipynb. I would have liked to understand the values from the docstring alone, or to have an image reference to the notebook.

These two keywords brought up a few thoughts:

I think they are incompatible with one another, right? If so, the code presently doesn't raise an error if both are set to true.
(Perhaps not for this present release, but) I think it might make sense to consider each boundary (North, South, East, and West) independently. That is, you could have East and West boundaries as periodic, North as symmetric, and South as "normal".

In addition, I think it would be worth using a different name for the keyword argument connected. As I understand it, this pertains to D4/D8 connectivity. Perhaps "connectivity" (with valid values "axial" and "both") or "diagonals" with valid values (False, True). At the least, I'd recommend using the words D4 and D8 in the docstring and making the y direction paneling label in the bioLEC1-genericCase.ipynb figure reflect the keyword argument.

JOSS Review: No GitHub version listed

The version described in the JOSS submission is 1.0.0

There are presently no tags or releases listed on GitHub.

My assumption is that @tristan-salles is intentionally waiting to make changes indicated in review before tagging.

JOSS Review: Install instructions in many places

As part of my JOSS Review I've looked through the readme.md, the read the docs page, the source code, and the notebooks. I've found that the installation instructions are duplicated across these locations.

I can understand wanting to make the installation instructions easily accessible. My experience, however, is that it is much better to have the instructions in one place and provide links. That way, when installation instructions change, you don't need to change all the files.

@tristan-salles feel free to make modifications based on this recommendation or completely ignore it.

JOSS Review: Developer installation and test instructions almost worked

As part of my JOSS Review I'm testing the installation instructions. As I'll note in my review in that repo I'm testing the developer install (but not the other install instructions).

I found a few small errors in the install and testing. A forthcoming PR will describe the minor fixes that worked for me.

JOSS Review: lavavu might not be working on Binder

As part of my JOSS Review I'm testing the notebooks.

I couldn't get the parts that related to lavavu to run locally---but the rest of the notebooks worked for me just fine.

On Binder I got unexpected results for the cells that relate to lavavu (for example, the following screenshot).

I tried this on both Safari and Chrome with the same failed results.