Review Request : J. Stachelek

Dockerfile

@@ -0,0 +1,36 @@
+
+FROM achubaty/r-spatial-base
+
+MAINTAINER Joseph Stachelek <[email protected]>
+
+RUN apt-get update \
+	&& apt-get install -y \
+		git \
+		rsync \
+		imagemagick \
+		texlive \
+		texlive-latex-extra \
+		texlive-xetex \
+		texlive-bibtex-extra \
+		fonts-roboto-hinted \
+		fonts-roboto \
+		texlive-fonts-extra \
+		biber \
+		cabal-install
+
+RUN Rscript -e 'devtools::install_github("jsta/irlgraph", dependencies = TRUE)'
+RUN Rscript -e "install.packages('rmarkdown', repos = 'https://cran.rstudio.com')"
+
+RUN wget https://github.com/jgm/pandoc/releases/download/1.15.2/pandoc-1.15.2-1-amd64.deb \
+	&& dpkg -i pandoc-1.15.2-1-amd64.deb
+
+RUN cabal update \
+	&& cabal install pandoc-crossref-0.1.5.6
+
+RUN git clone https://github.com/jsta/ReScience-submission.git \
+	&& cd ReScience-submission \
+		&& git checkout STACHELEK \
+			&& make all
+
+
+

Makefile

@@ -0,0 +1,24 @@
+
+#update_code:
+#	rsync -av --exclude=.git --exclude='*.Rproj' --exclude='eth2012code' --exclude='.Rbuildignore' --exclude='.gitignore' --exclude='irlgraph_cache' --exclude='irlgraph_files' -- exclude='irlgraph.pdf' /home/jose/R/scripts/irlgraph code/
+
+code/irlgraph/vignettes/irlgraph.pdf: code/irlgraph/vignettes/irlgraph.Rmd
+	Rscript -e 'rmarkdown::render("code/irlgraph/vignettes/irlgraph.Rmd")'
+
+move_images: code/irlgraph/vignettes/irlgraph.pdf
+	rsync -av code/irlgraph/vignettes/irlgraph_files/figure-latex/ article
+
+panel-resize_images: move_images
+	cd article && make images
+
+build_article: panel-resize_images
+	cd article && make build
+
+all: panel-resize_images
+	@echo "figures built"
+
+clean:
+	rm -rf code/irlgraph/vignettes/irlgraph_cache
+	rm -rf code/irlgraph/vignettes/irlgraph_files
+	rm code/irlgraph/vignettes/irlgraph.pdf
+

README.md

@@ -1,56 +1,82 @@
 
-### ReScience submission repository
-
-This is the submission repository for the [Re**Science** journal](https://rescience.github.io).
-
-
-### How to submit an article ?
-
-
-1. Create a [github](https://github.com) account
-
-2. [Fork](https://help.github.com/articles/fork-a-repo/) the [ReScience submission](https://github.com/ReScience/ReScience-submission) repository
-
-3. Clone this new repository into your desktop environment
-
-   ```
-   $ git clone https://github.com/YOUR-USERNAME/ReScience-submission
-   ```
-
-4. Create a branch (the branch name should be author names separated with dashes)
-
-   ```
-   $ git checkout -b AUTHOR1-AUTHOR2
-   ```
-
-
-5. Add your code & article (see [author guidelines](https://rescience.github.io/write)) and commit your changes:
-
-   ```
-   $ git commit -a -m "Some comment"
-   ```
-
-
-6. [Push](https://help.github.com/articles/pushing-to-a-remote/) to github
-
-   ```
-   $ git push origin AUTHOR1-AUTHOR2
-   ```
-
-7. Issue a [pull request](https://help.github.com/articles/using-pull-requests/) (PR) to Re**Science** with title "Review Request" and insert the following text in the description:
-
-  ```
-  **AUTHOR**
-
-  Dear @ReScience/editors,
-
-  I request a review for the reproduction of the following paper:
-
-  * References of the paper holding results you're replicating
-
-  I believed the original results have been faithfully reproduced as explained in the accompanying article.
-  ```
-
-8. Assign the PR to an editor from the [editorial board](https://rescience.github.io/board)
-
-9. Answer questions and requests made in the PR conversation page.
+\[Re\] Least-cost modelling on irregular landscape graphs, J. Stachelek, Re**Science**, 2015.
+
+**A reference implementation of** *Least-cost modelling on irregular landscape graphs*, T. Etherington, 27, 2012.
+
+**Keywords**: Least-cost path, Delaunay triangulation, Graph Theory
+
+##Figure Build Instructions (tested on Ubuntu 14.04 and 15.10)
+###Prequisites 
+ * git
+ * R
+ * GNU make
+ * pandoc
+
+In a console, type:
+
+```
+$ echo deb https://cran.rstudio.com/bin/linux/ubuntu trusty/ >> /etc/apt/sources.list
+$ sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E084DAB9  
+$ sudo apt-get update
+$ sudo apt-get -y install r-base
+$ sudo apt-get install git
+```
+
+###devtools + dependencies
+
+```
+$ sudo apt-get install libcurl4-gnutls-dev
+$ sudo apt-get install libxml2-dev
+$ sudo apt-get install libssl-dev
+$ sudo Rscript -e "install.packages('devtools', repos = 'https://cran.rstudio.com')"
+```
+
+###irlgraph + dependencies
+```
+$ sudo apt-get install libgeos-dev
+$ sudo Rscript -e "devtools::install_github('jsta/irlgraph', dependencies = TRUE)"
+```
+
+###pandoc + dependencies
+```
+$ sudo Rscript -e "install.packages('rmarkdown', repos = 'https://cran.rstudio.com')"
+$ sudo wget https://github.com/jgm/pandoc/releases/download/1.15.2/pandoc-1.15.2-1-amd64.deb
+$ sudo dpkg -i pandoc-1.15.2-1-amd64.deb
+$ sudo apt-get install texlive texlive-latex-extra
+```
+
+###imagemagick
+```
+$ sudo apt-get install imagemagick
+```
+
+###checkout source and build
+```
+$ git clone https://github.com/jsta/ReScience-submission.git
+$ cd ReScience-submission
+$ git checkout STACHELEK
+$ make all
+```
+
+##Docker Build Instructions
+###Prequisites 
+ * docker
+
+In a console, type:
+
+```
+$ docker pull jsta/irlgraph-test
+$ docker cp $(docker create jsta/irlgraph-test):ReScience-submission/article/article.pdf .
+```
+
+##PDF Build Instructions
+
+```
+$ sudo apt-get install texlive-xetex texlive-fonts-extra
+$ sudo apt-get install texlive-bibtex-extra biber
+$ sudo apt-get install cabal-install
+$ cabal update
+$ cabal install pandoc-crossref
+$ make all
+$ make build_article
+```

article/Makefile

@@ -0,0 +1,13 @@
+images:
+	convert print-mesh-1.png -gravity South -resize x340\! print-mesh-2.png
+	convert print-mesh-2.png -gravity South -extent 472x398 print-mesh-3.png
+	montage coord-id-1.png print-mesh-3.png -tile 2x -geometry +1+1 -bordercolor white -border 5x5 node-edge_selection.png
+	montage acc_cost-1.png impute_na-1.png -gravity North -tile 2x -geometry +1+1 -bordercolor white -border 5x5 irl-construction.png
+	montage processing_speed_1-1.png processing_speed_1-2.png -tile 2x -gravity south -geometry +1+1 -bordercolor white -border 5x5 processing-speed.png
+
+build:
+	pandoc --standalone --filter $(HOME)/.cabal/bin/pandoc-crossref --template=rescience-template.tex --latex-engine=xelatex --biblatex --bibliography=article.bib -M "crossrefYaml=crossref.yaml" --output article.tex article.md
+	xelatex article
+	biber article
+	xelatex article
+	xelatex article

article/README.md

@@ -17,10 +17,10 @@ $ cabal install pandoc-crossref
 In a console, type:
 
 ```
-pandoc --standalone --filter ~/.cabal/bin/pandoc-crossref --template=rescience-template.tex --latex-engine=xelatex --biblatex --bibliography=your_article_name.bib -M "crossrefYaml=crossref.yaml" --output your_article_name.tex your_article_name.md
-xelatex your_article_name
-biber your_article_name
-xelatex your_article_name
-xelatex your_article_name
+pandoc --standalone --filter ~/.cabal/bin/pandoc-crossref --template=rescience-template.tex --latex-engine=xelatex --biblatex --bibliography=article.bib -M "crossrefYaml=crossref.yaml" --output article.tex article.md
+xelatex article
+biber article
+xelatex article
+xelatex article
 ```
 

article/article.bib

@@ -0,0 +1,46 @@
+@misc{markdown,
+    author    = "John Gruber and Aaron Swartz",
+    title     = "The Markdown format",
+    year      = "2004",
+    url       = "http://daringfireball.net/projects/markdown/syntax"
+}
+
+@article{etherington2012least,
+  title={Least-cost modelling on irregular landscape graphs},
+  author={Etherington, Thomas R},
+  journal={Landscape ecology},
+  volume={27},
+  number={7},
+  pages={957--968},
+  year={2012},
+  publisher={Springer}
+}
+
+@Manual{gdistance,
+    title = {gdistance: Distances and Routes on Geographical Grids},
+    author = {Jacob van Etten},
+    year = {2015},
+    note = {R package version 1.1-9},
+    url = {http://CRAN.R-project.org/package=gdistance},
+  }
+
+@article{quickhull,
+  title={The quickhull algorithm for convex hulls},
+  author={Barber, C Bradford and Dobkin, David P and Huhdanpaa, Hannu},
+  journal={ACM Transactions on Mathematical Software (TOMS)},
+  volume={22},
+  number={4},
+  pages={469--483},
+  year={1996},
+  publisher={ACM}
+}
+
+@Article{igraph,
+    title = {The igraph software package for complex network research},
+    author = {Gabor Csardi and Tamas Nepusz},
+    journal = {InterJournal},
+    volume = {Complex Systems},
+    pages = {1695},
+    year = {2006},
+    url = {http://igraph.org},
+  }

article/article.md

@@ -0,0 +1,67 @@
+---
+Title: "Least-cost modelling on irregular landscape graphs"
+Author:
+  - name: Joseph Stachelek
+    affiliation: 1
+Address:
+  - code:    1
+    address: South Florida Water Management District, West Palm Beach, Florida, USA
+Contact:
+  - [email protected]
+Editor:
+  - Name Surname
+Reviewer:
+  - Name Surname
+  - Name Surname
+Publication:
+  received:  Sep,  1, 2015
+  accepted:  Sep, 1, 2015
+  published: Sep, 1, 2015
+  volume:    "**1**"
+  issue:     "**1**"
+  date:      Nov 2015
+Repository:
+  article:   "http://github.com/jsta/rescience-submission/tree/STACHELEK"
+  code:      "http://github.com/rescience/rescience-submission/tree/STACHELEK/code"
+  data:      
+  notebook:  
+Reproduction:
+  - "Least-cost modelling on irregular landscape graphs, T. Etherington, Landscape Ecology, 2012."
+Bibliography:
+  article.bib
+
+---
+
+# Introduction
+
+I propose a reference implementation of [@etherington2012least] that describes a method for generating accumulated cost surfaces using irregular landscape graphs. Accumulated cost surfaces are commonly used in landscape ecology, autonomous navigation, and civil engineering to represent travel costs and connectivity among points in a spatial domain. For the purposes of this paper, each accumulated cost surface will represent the connectivity between a single point _starting-node_ and the remaining points in the domain. The construction of these surfaces depends on an underlying landscape graph made up of nodes and distance-weighted edges. Conventionally, landscape graphs are constructed from a complete set of all possible nodes. The original article explored the use and constuction of irregular landscape graphs which are formed from an _intelligent_ subset of all possible points.
+
+According to the original article, irregular landscape graphs allow for faster processing speeds relative to regular landscape graphs and avoid directional bias artifacts. The original implementation was made in Python whose sources are available upon request to the author of the original article. The proposed reference implementation has been coded in R because of the strength of existing libraries for generating accumulated cost surfaces using regular landscape graphs [@gdistance]. 
+
+# Methods
+
+The following reference implementation was based on the model description and source code of the original implementation (requested from the author). I attempted to follow the structure, style, and order-of-operations of the original with a few exceptions. For example, the same underlying Fortran algorithm is used to compute the Delaunay triangulations [@quickhull] forming the basis of irregular landscape graph construction. One notable difference in the reference implementation relative to the original is that regular landscape graphs are constructed using matrix operations rather than nested loops (see `gdistance` source code [@gdistance]). 
+
+# Results
+
+![Node-edge selection ensures that all relevant landscape features are retained in the accumulated cost surface. Note that the triangulation in the second panel incudes Null data nodes. These are trimmed prior to construction of the final graph.](node-edge_selection.png) {#fig:nodeselection}
+
+First, I reproduced the basic output of Figures 3 and 4 using model inputs obtained from the author of the original article (Figures @fig:nodeselection , @fig:irlconstruction). I tested a range of different algorithms for producing Delaunay triangulations before settling on the same underlying algorithm as the original [@quickhull].
+
+![Accumlated cost surface construction begins by traversing the graph from the starting-node (open circle) to the remaining points in the landscape graph. In the final step, missing nodes are imputed according to a nearest neighbor selection.](irl-construction.png) {#fig:irlconstruction}
+
+Next, I reproduced the performance comparisons in Figure 7 (Figure @fig:performance). The results suggest a more nuanced interpretation of the relative performance of the two methods. Although initial construction was much faster for regular landscape graphs, at a sufficiently high number of starting nodes the initial performance penalty afforded to irregular landscape graphs was outweighed by a decrease in per starting-node processing time. These findings can be attributed to the fact that the simple structures of regular landscape graphs are amenable to matrix operations and that irregular landscape graphs have a lower number of node/edge features.
+
+![Performance comparisons between regular and irregular landscape graphs. Note that for only two source cells, the performance benefit realized by the irregular landscape graph was outweighed by a higher initialization cost.](processing-speed.png) {#fig:performance}
+
+Profiling of the reference implementation code revealed that the bulk of the processing time required to construct irregular landscape graphs was spent on Delaunay triangulation. Note that the proposed reference implementation uses compiled Fortran code [@quickhull] to implement Delaunay triangulations and compiled C code from the igraph package [@igraph] to construct graphs and calculate accumulated cost distances. 
+
+Finally, I reproduced the directional bias tests in Figure 8 (Figure @fig:directionalbias). As in the original article, I found that regular graphs produced directionally-biased cost surfaces. However, I was able to correct for these biases by scaling graph edge weights according to the diagonal distance between grid cells (see the `gdistance::geoCorrection` function [@gdistance]).
+
+![Comparison of directional bias between irregular, regular, and corrected-regular landscape graphs.](directional_bias-1.png) {#fig:directionalbias}
+
+# Conclusion
+
+I was able to replicate the finding of the original article that irregular landscape graphs provide a performance benefit relative to regular landscape graphs but this was true only under certain conditions. I found that although irregular landscape graphs suffer a high initialization cost relative to regular landscape graphs they have a lower individual (per-unit) starting-node processing time. Potential users of irregular landscape graphs should consider initialization and performance trade-offs prior to implementation.
+
+# References