---

Introduction

HierarchiaPy is an optimized statistical package for hierarchy/dominance analysis methds. It is purely written in Python and mainly built on Pandas and NumPy. Interarction data can be parsed both from Pandas DataFrame and 2D Numpy array. The methods are implemented based on the original published papers and tests module designed to cross-check the results with the examples from the reference papers.

Dominance and hierarchy is one of the core concepts in the research field of animal social behaviour. The hierarchy (dominance) can be derived from the interactions between the individuals (dyadic relationships). There are numerous techniques to derive the dominance from such dataset. We can classify them into two categories; numerical matrix optimization for certain criteria which results in a rank order (1) and calculation of a certain dominance measure for each individual from which a rank can be computed (2).

The HierarchiaPy statistical python package aims to implement available methods from both categories, allowing the animal social scientists to derive dominance efficiently, easily and in a reproducible way.

Methods: Stable release

1. ELO rating
2. Randomized ELO rating
3. David's Scores
4. Normalized David's Scores
5. Average Dominance Index
6. Adagio
7. I&SI 98
8. Directional Consistency Index (DCI)
9. Steepness
10. Steepness Test
11. Planor Network Visualization

Linearity Tests: Stable release

1. Landau's h
2. Improved Landau's h
3. Kendall's K (Chi-square approximation & ECDF for n<10)
4. Unbiased Kendall's K (permutation of unknown relationships)

---

Methods: Under Development

3. I&SI 13

Quick Start

Installation

!pip install HierarchiaPy

Basic Usage

from HierarchiaPy import Hierarchia
import numpy as np

mat_hemelrijk_table_2_1 = np.array([[0, 6, 9, 8, 5],
                                    [0, 0, 4, 6, 0],
                                    [0, 2, 0, 4, 7],
                                    [1, 0, 5, 0, 3],
                                    [0, 0, 2, 3, 0]], dtype='int64')

hier_mat = Hierarchia(mat_hemelrijk_table_2_1, np.array(['a', 'b', 'c', 'd', 'e']))
davids_scores = hier_mat.davids_score()

print(davids_scores)

Output:

{'a': 8.4444, 'b': 1.6111, 'c': -2.3333, 'd': -3.6667, 'e': -4.0556}

Documentation

For full functionality and reference, see the documentation

Citation

Ipek, Nusret, et al. "Quantifying agonistic interactions between group-housed animals to derive social hierarchies using computer vision: a case study with commercially group-housed rabbits." Scientific Reports 13.1 (2023): 14138.

Change Log

v 0.1.0 - Initial release
v 0.2.0 - Inclusion of linearity statistics & tests
v 0.2.1 - Hot-fix for linearity tests
v 0.2.2 - I&SI 98, performance improvement
v 0.2.3 - Landau's h classic improvement
v 0.2.4 - Steepness, DCI and network vizualization added
v 0.2.5 - Performance improvement and vectorization of several modules
v 0.2.6 - Dependency management