Merge branch 'master' into issue_420_richness_estimators

Updates issue #420

The following conflicts were edited.  Most likely we will just cherry pick the RichnessEstimation.pm file into master when we merge it all back, rather than merge all the changes.

	bin/BiodiverseGUI.pl
	bin/run_randomisation.pl
	etc/pp/build.pl
	etc/versions.txt
	example_scripts/import_rasters_and_analyse.pl
	lib/Biodiverse/BaseData.pm
	lib/Biodiverse/BaseStruct.pm
	lib/Biodiverse/Common.pm
	lib/Biodiverse/GUI/BasedataImport.pm
	lib/Biodiverse/GUI/Callbacks.pm
	lib/Biodiverse/GUI/Help.pm
	lib/Biodiverse/GUI/MatrixGrid.pm
	lib/Biodiverse/GUI/Project.pm
	lib/Biodiverse/GUI/Tabs/Labels.pm
	lib/Biodiverse/GUI/Tabs/Tab.pm
	lib/Biodiverse/Indices.pm
	lib/Biodiverse/Indices/PhyloCom.pm
	lib/Biodiverse/Indices/Phylogenetic.pm
	lib/Biodiverse/Indices/PhylogeneticRelative.pm
	lib/Biodiverse/Randomise.pm
	lib/Biodiverse/ReadNexus.pm
	lib/Biodiverse/Statistics.pm
	lib/Biodiverse/Tree.pm
	lib/Biodiverse/TreeNode.pm
	t/13-Tree.t
	t/lib/Biodiverse/TestHelpers.pm

Signed-off-by: Shawn Laffan <shawnlaffan@gmail.com>

Installation.txt

@@ -1,3 +1,3 @@
-Installation instructions for the different operating systems can be found at http://code.google.com/p/biodiverse/wiki/Installation
+Installation instructions for the different operating systems can be found at http://purl.org/biodiverse/biodiverse/wiki/Installation
 
-For more general help, see http://code.google.com/p/biodiverse/wiki/HelpOverview
+For more general help, see http://purl.org/biodiverse/wiki/HelpOverview

README.md

@@ -0,0 +1,80 @@
+# Biodiverse
+
+Biodiverse is a tool for the spatial analysis of diversity using indices based on taxonomic, phylogenetic, trait and matrix-based (e.g. genetic distance) relationships, as well as related environmental and temporal variations. Biodiverse supports the following processes: 
+
+  1. Linked visualisation of data distributions in geographic, taxonomic, phylogenetic and matrix spaces;
+  1. Spatial moving window analyses including richness, endemism, phylogenetic diversity and beta diversity;
+  1. Spatially constrained agglomerative cluster analyses; 
+  1. Spatially constrained region grower analyses; 
+  1. Interactive visualisation of turnover patterns (for example beta-diversity); and 
+  1. Randomisations for hypothesis testing. 
+
+Biodiverse is open-source and supports user developed extensions. It can be used both through a graphical user interface (GUI) and through user written scripts.
+
+More than 250 indices are supported.  See the [Indices](https://purl.org/biodiverse/wiki/Indices) page.
+
+*Screen shots* can be found on the ScreenShots page.
+
+*Example* applications can be seen at the [publications page](https://purl.org/biodiverse/wiki/PublicationsList).
+
+*Help* can be located via the [help pages](https://purl.org/biodiverse/wiki/Home) (these are also accessible via the wiki link on the right of this page).
+
+A **discussion group** is at http://groups.google.com.au/group/biodiverse-users and a **blog** at http://biodiverse-analysis-software.blogspot.com.au/
+
+
+To cite Biodiverse or acknowledge its use, use the following details, substituting the version of the application that you used for "Version 0.17".
+
+*  Laffan, S.W., Lubarsky, E. & Rosauer, D.F. (2010) Biodiverse, a tool for the spatial analysis of biological and related diversity. [Ecography. Vol 33, 643-647 (Version 0.17)](http://dx.doi.org/10.1111/j.1600-0587.2010.06237.x).
+
+An overview of the system is also provided in Dan Rosauer's talk at TDWG2008:
+
+* Rosauer, D.F. & Laffan, S.W. (2008) Linking phylogenetic trees, taxonomy & geography to map phylogeography using Biodiverse. Taxonomic Data Working Group 2008, Perth, Australia. [PPT](http://www.tdwg.org/fileadmin/2008conference/slides/Rosauer_09_05_phyloTrees.ppt) [SWF with audio](http://www.tdwg.org/fileadmin/2008conference/slides/Rosauer_09_05_phyloTrees.swf). 
+
+For a list of **publications using Biodiverse**, see the [PublicationsList](https://purl.org/biodiverse/wiki/PublicationsList) page.  
+
+# Installation
+Installation instructions can be accessed through the [Installation](https://purl.org/biodiverse/wiki/Installation) page.
+
+# News 
+
+27-Oct-2014
+A new development release is now available.  It can be downloaded from https://purl.org/biodiverse/wiki/Downloads 
+
+The summary of changes is at https://purl.org/biodiverse/wiki/ReleaseNotes#version-099_005
+
+
+27-Oct-2014
+
+A new blog post describing some of the new features in the upcoming 1.0 release is available.  http://biodiverse-analysis-software.blogspot.com.au/2014_10_01_archive.html
+
+18-Sep-2014
+
+A new development release is now available.  It can be downloaded from https://purl.org/biodiverse/wiki/Downloads 
+
+The summary of changes is at https://purl.org/biodiverse/wiki/ReleaseNotes#version-099_004
+
+13-Aug-2014
+
+A Biodiverse pipeline for the CANAPE (Categorical Analysis of Neo and Palaeo Endemism) analyses described in [Mishler et al. (2014)](http://dx.doi.org/10.1038/ncomms5473) is now available.  See https://github.com/NunzioKnerr/biodiverse_pipeline 
+
+
+31-Oct-2013
+
+Biodiverse version 0.19 has been released.  It can be downloaded from https://bintray.com/shawnlaffan/Biodiverse/Biodiverse-releases .
+
+The summary of changes is at https://purl.org/biodiverse/wiki/ReleaseNotes#version-019
+
+
+
+# Acknowledgements 
+
+This research has been supported by Australian Research Council Linkage Grant LP0562070 (Laffan and West) and UNSW FRGP funding to Laffan.
+
+
+# Persistent URL 
+
+http://www.purl.org/biodiverse
+
+## Keywords 
+
+Biodiversity analysis tool, spatial analysis, phylogeography, spatial analysis, endemism, phylogenetic diversity, beta diversity, species turnover

bin/BiodiverseGUI.pl

@@ -212,7 +212,7 @@ sub get_iconfile {
             my $zip = Archive::Zip->new($ENV{PAR_PROGNAME})
               or die "Unable to open $ENV{PAR_PROGNAME}";
 
-            my $glade_zipped = $zip->extractMember ( $fname, $icon_str );
+            my $success = $zip->extractMember ( $fname, $icon_str );
 
             if (-e $icon) {
                 say "Using PAR icon file $icon";

bin/run_randomisation.pl

@@ -24,14 +24,15 @@
 
 use Getopt::Long;
 
-my ($in_file, $rand_name, $print_usage);
+my ($in_file, $rand_name, $print_usage, $bd_name);
 my %rest_of_args;
 my $iterations = 10;
 
 
 GetOptions (
     "basedata|bd=s"  => \$in_file,
     "rand_name|r=s"  => \$rand_name,
+    "bd_name|=s"     => \$bd_name,
     "iterations|iters|i:i" => \$iterations,
     "args:s{,}"      => \%rest_of_args,
     "help|h" => \$print_usage,
@@ -43,6 +44,7 @@
     $0,
     '--basedata  --bd Basedata file name',
     '--rand_name  --r Randomisation output name',
+    '--bd_name        Basedata object name to use (optional)',
     '--iterations --i Number of randomisation iterations [default is 10]',
     '--args           Rest of randomisation args as',
     '                 key=value pairs,',
@@ -65,6 +67,7 @@
 die "\nError: Randomisation name not specified\n$usage\n"
   if !defined $rand_name;
 
+
 my $tmp_bd     = Biodiverse::BaseData->new(CELL_SIZES => [100000, 100000]);
 my $extensions = join ('|', $tmp_bd->get_param('OUTSUFFIX'), $tmp_bd->get_param('OUTSUFFIX_YAML'));
 my $re_valid   = qr/($extensions)$/i;
@@ -76,6 +79,11 @@
     exit;
 }
 
+if ($bd_name) {
+    $bd->rename (new_name => $bd_name);
+}
+
+
 my $rand = $bd->get_randomisation_output_ref (name => $rand_name)
         // $bd->add_randomisation_output     (name => $rand_name);
 

etc/benchmark_scripts/bench_eval_for_div_by_zero.pl

@@ -0,0 +1,28 @@
+
+use Benchmark qw {:all};
+use 5.016;
+
+
+$| = 1;
+
+
+my $check_count = 1000;
+
+my $numerator = 5;
+my $x;
+
+no warnings 'uninitialized';
+
+foreach my $denominator (undef, qw /0 1 3 1000/){
+
+    cmpthese (
+        -1,
+        {
+            eval    => sub {$x = eval {$denominator / $numerator} || 0},
+            ternary => sub {$x = $denominator ? ($numerator / $denominator) : 0},
+            ifelse  => sub {if ($denominator) {$x = $numerator / $denominator} else {$x = 0}},
+        }
+    );
+
+}
+

etc/benchmark_scripts/bench_explicit_return.pl

@@ -0,0 +1,28 @@
+
+use Benchmark qw {:all};
+use 5.016;
+
+$| = 1;
+
+
+cmpthese (
+    -3,
+    {
+        er => sub {rand(); return},
+        nr => sub {rand(); },
+    }
+);
+
+
+__END__
+
+#  results:
+50_000_000
+        Rate   er   nr
+er 20517029/s   -- -45%
+nr 37202381/s  81%   --
+
+-3
+         Rate   er   nr
+er 18205338/s   -- -52%
+nr 37690645/s 107%   --

etc/benchmark_scripts/bench_get_params.pl

@@ -0,0 +1,47 @@
+
+use Benchmark qw {:all};
+use 5.016;
+use Data::Dumper;
+
+#use List::Util qw {:all};
+
+my @vals = 1 .. 20;
+my $self = {PARAMS => {label_hash1 => 5, @vals}};
+
+#my $n = 1000;
+#my @a1 = (0 .. $n);
+
+my $param = 'label_hash1';
+
+cmpthese (
+    3000000,
+    {
+        old1 => sub {old1 ($self, $param)},
+        new1 => sub {new1 ($self, $param)},
+        new2 => sub {new2 ($self, $param)},
+        new3 => sub {new3 ($self, $param)},
+    }
+);
+
+
+#say Dumper $self;
+
+sub old1 {
+    return if ! exists $_[0]->{PARAMS}{$_[1]};
+    return $_[0]->{PARAMS}{$_[1]};
+}
+
+
+sub new1 {
+    no autovivification;
+    return $_[0]->{PARAMS}{$_[1]};
+}
+
+sub new2 {
+    no autovivification;
+    $_[0]->{PARAMS}{$_[1]};
+}
+
+sub new3 {
+    exists $_[0]->{PARAMS}{$_[1]} && $_[0]->{PARAMS}{$_[1]};
+}

etc/benchmark_scripts/bench_hash_key_set.pl

@@ -0,0 +1,105 @@
+
+use Benchmark qw {:all};
+use 5.016;
+use Data::Dumper;
+
+my @keys;
+for (0..16000) {
+    push @keys, "$_:$_";
+}
+
+my @keys_outer = @keys[0..257];
+
+
+$| = 1;
+
+cmpthese (
+    3,
+    {
+        none       => sub {no_set_keys()},
+        outer      => sub {set_keys_outer()},
+        outer_init => sub {set_keys_outer_init()},
+        inner      => sub {set_keys_inner()},
+    }
+);
+
+
+sub no_set_keys {
+    state $run_count;
+    $run_count ++;
+    say 'nsk ' . $run_count if !($run_count % 5);
+    my %hash;
+    foreach my $key1 (@keys_outer) {
+        foreach my $key2 (@keys) {
+            $hash{$key1}{$key2}++;
+        }
+    }
+
+}
+
+sub set_keys_outer {
+    state $run_count;
+    $run_count ++;
+    say 'sko ' . $run_count if !($run_count % 5);
+
+    my %hash;
+    keys %hash = scalar @keys_outer;
+    foreach my $key1 (@keys_outer) {
+        foreach my $key2 (@keys) {
+            $hash{$key1}{$key2}++;
+        }
+    }
+}
+
+sub set_keys_outer_init {
+    state $run_count;
+    $run_count ++;
+    say 'skoi ' . $run_count if !($run_count % 5);
+
+    my %hash;
+    keys %hash = scalar @keys_outer;
+    foreach my $key1 (@keys_outer) {
+        $hash{$key1} //= {};
+        foreach my $key2 (@keys) {
+            $hash{$key1}{$key2}++;
+        }
+    }
+}
+
+sub set_keys_inner {
+    state $run_count;
+    $run_count ++;
+    say 'ski ' . $run_count if !($run_count % 5);
+
+    my %hash;
+    keys %hash = scalar @keys_outer;
+    foreach my $key1 (@keys_outer) {
+        $hash{$key1} //= {};
+        keys %{$hash{$key1}} = scalar @keys;
+        foreach my $key2 (@keys) {
+            $hash{$key1}{$key2}++;
+        }
+    }
+}
+
+__END__
+
+The differences are all in the noise.
+
+results on HPC with 5.20.0 using rand() as the keys:
+
+           s/iter outer_init      outer       none      inner
+outer_init   5.17         --        -0%        -0%        -2%
+outer        5.17         0%         --        -0%        -2%
+none         5.17         0%         0%         --        -2%
+inner        5.07         2%         2%         2%         --
+
+
+Small relative improvement when using "$_:$_" as the keys,
+but the absolute values are also far less than for rand() keys:
+
+           s/iter       none      outer outer_init      inner
+none         1.55         --        -1%        -2%        -5%
+outer        1.53         1%         --        -0%        -4%
+outer_init   1.52         2%         0%         --        -4%
+inner        1.47         6%         4%         4%         --