--------------------------------------------------------------------------------
    mdendro: An R Package for Extended Agglomerative Hierarchical Clustering
    Alberto Fernandez, Sergio Gomez
    Journal of Statistical Software
--------------------------------------------------------------------------------

Radatools is a set of executable programs whose source code is freely available in Radalib:
- Radalib main page: https://webs-deim.urv.cat/~sergio.gomez/radalib.php
- Radalib GitHub: https://github.com/sergio-gomez/Radalib

In particular, Radatools contains the program Hierarchical_Clustering, which can count the
number of structurally different binary dendrograms. Its source code can be found in the
Radalib folder radalib/tools.

To reproduce the calculation of the number of structurally different binary dendrograms in
Section 2.1 of the paper, use the corresponding script:
- Windows:      Binary_Dendrograms_Count.bat
- Linux/MacOS:  binary_dendrograms_count.sh

These scripts contain the instructions to run them (as comments), but they can be summarized as:
1. Download Radatools for your platform (Windows, Linux or MacOS) from:
     https://webs-deim.urv.cat/~sergio.gomez/radatools.php
2. No installation needed, just uncompress the downloaded file.
3. Save program Hierarchical_Clustering.exe included in folder Data, input file cultivars.txt and
   the corresponding script file in the same folder.
4. In Linux/MacOS, ensure Hierarchical_Clustering.exe and the script files are executable:
     > chmod 755 Hierarchical_Clustering.exe binary_dendrograms_count.sh
5. Run the corresponding script:
     Windows:      > Binary_Dendrograms_Count.bat
     Linux/MacOS:  > ./binary_dendrograms_count.sh


The usage of Hierarchical_Clustering is the following:

===================================================================
== Hierarchical_Clustering.exe                                   ==
===================================================================
== Agglomerative Hierarchical Clustering with MultiDendrograms   ==
== and Binary Dendrograms, for distances and similarities        ==
== Algorithms implemented:                                       ==
==   - (VL) Versatile linkage       - (HL) Harmonic linkage      ==
==   - (SL) Single linkage          - (WD) Ward                  ==
==   - (CL) Complete linkage        - (CD) Centroid              ==
==   - (AL) Arithmetic linkage      - (BF) Beta flexible         ==
==   - (GL) Geometric linkage                                    ==
==                                                               ==
== Equivalences between clustering algorithms for distances:     ==
==   Arithmetic Linkage Unweighted  = UPGMA                      ==
==   Versatile Linkage (param +1.0) = Complete Linkage           ==
==   Versatile Linkage (param +0.1) = Arithmetic Linkage         ==
==   Versatile Linkage (param  0.0) = Geometric Linkage          ==
==   Versatile Linkage (param -0.1) = Harmonic Linkage           ==
==   Versatile Linkage (param -1.0) = Single Linkage             ==
==   Beta Flexible     (param  0.0) = Arithmetic Linkage         ==
== For similarities, the signs of param must be exchanged        ==
==                                                               ==
== MultiDendrograms generates always a unique dendrogram         ==
== For Binary Dendrograms, in case of ties, many dendrograms     ==
== may exist, and this tool can enumerate or count all of them,  ==
== or choose the one with maximum cophenetic correlation         ==
== See also                                                      ==
==   http://deim.urv.cat/~sergio.gomez/mdendro.php               ==
==   http://deim.urv.cat/~sergio.gomez/multidendrograms.php      ==
===================================================================


Usage:  Hierarchical_Clustering.exe  proximities_name  output_prefix  dendrogram_type  proximity_type  [ precision ]  clustering_type  [ weighting_type ]  [ clustering_parameter ]  [ dendrogram_mode ]  [ internal_nodes_prefix ]

   proximities_name      :  name of the proximities file, either in matrix or list form
                              in matrix form, the names may be in first column, first row, or none
                              in list form, missing values are filled with:
                                Double'Last for Distances
                                0.0         for Similarities

   output_prefix         :  prefix of the output files

   dendrogram_type       :  MD | BD
                              also lowercase symbols
                              also case-insensitive short and full names (Multidendrogram, ...)
                              MD | Multidendrogram
                              BD | Binary_Dendrogram

   proximity_type        :  D | S
                              also lowercase symbols
                              also case-insensitive short and full names (Distance, ...)
                              D | DIST | Distance
                              S | SIM  | Similarity

   precision             :  Number of decimal significant digits of the data and for the calculations
                              if not specified, is that of the value with largest number of decimal digits

   clustering_type       :  VL | SL | CL | AL | GL | HL | WD | CD | BF
                              also lowercase symbols
                              also case-insensitive short and full names (Versatile_Linkage, ...)
                              VL = Versatile_Linkage
                              SL = Single_Linkage
                              CL = Complete_Linkage
                              AL = Arithmetic_Linkage
                              GL = Geometric_Linkage
                              HL = Harmonic_Linkage
                              WD = Ward
                              CD = Centroid
                              BF = Beta_Flexible

   weighting_type        :  W | UW
                              also lowercase symbols
                              also case-insensitive short and full names (Weighted, ...)
                              W  = Weighted
                              UW = Unweighted
                              default => Unweighted

   clustering_parameter  :  Clustering parameter, between -1.0 and +1.0, necessary for
                              VL = Versatile_Linkage
                              BF = Beta_Flexible
                              default => 0
                              ignored for the other clustering types
                              for VL
                                -1.0 corresponds to SL for DIST, and to CL for SIM
                                -0.1 corresponds to HL for DIST, and to AL for SIM
                                 0.0 corresponds to GL
                                +0.1 corresponds to AL for DIST, and to HL for SIM
                                +1.0 corresponds to CL for DIST, and to SL for SIM
                              for BF
                                 0.0 corresponds to AL

   dendrogram_mode       :  Sorted | Unsorted | Best | Count
                              also case-insensitive full names
                              default => Sorted
                              mode discarded for MultiDendrograms

   internal_nodes_prefix :  Prefix for the names of the internal nodes
                              if 'None' (case insensitive) no names are assigned to internal nodes
                              default => Cluster_


Note that, for Versatile Linkage, the parameter 'p' in mdendro and MultiDendrograms can take any
real value (between minus and plus infinity), as defined in the original paper, whereas the
Hierarchical_Clustering program in Radatools makes use of a normalized hyperbolic tangent scaling
of 'p' into the range [-1.0, 1.0]. In particular, param = 0.1 (-0.1) represents Arithmetic linkage
and param = -0.1 (0.1) represents Harmonic Linkage for distances (similarities). The relationship
between parameters 'p' and 'param', assigning S1 := 0.1, is the following:
- For distances:
    p := Log((1.0 + param) / (1.0 - param)) / Log((1.0 + S1) / (1.0 - S1));
- For similarities
    p := Log((1.0 - param) / (1.0 + param)) / Log((1.0 + S1) / (1.0 - S1));
