# nercms-mmap/ra-lib architecture

> Architecture diagram of the GitHub repository nercms-mmap/ra-lib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nercms-mmap/ra-lib
- Repository: https://github.com/nercms-mmap/ra-lib

## Overview

RA-Lib is a Python rank-aggregation library and benchmarking environment. Its main workflow takes ranked or scored item lists from multiple voters, applies an aggregation method, and produces an ordered list; relevance labels can also support supervised or semi-supervised training and evaluation. The implementation separates input processing, evaluation, and unsupervised, supervised, and semi-supervised methods. The README documents a broad method catalog, while the sampled source is partial, so links between particular algorithms and shared utilities are shown only where supported.

Main entry points: [`src/rapython/datatools/data_io.py`](https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/datatools/data_io.py) (CSV input/output), [`src/rapython/evaluation/evaluation.py`](https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/evaluation/evaluation.py) (Ranking metrics), [`src/rapython/unsupervised/markovchain.py`](https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/unsupervised/markovchain.py) (Markov chains), [`src/rapython/unsupervised/borda_score.py`](https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/unsupervised/borda_score.py) (Borda Score)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data handling"]
  node_io["CSV input/output<br/>[data_io.py]"]
  node_processing["Rank processing<br/>[data_process.py]"]
  node_input_types["Input types<br/>[constant.py]"]
end

subgraph group_unsup["Unsupervised methods"]
  node_unsupervised_catalog["Unsupervised RA"]
  node_comb_methods["Comb methods<br/>[combsum.py]"]
  node_markov["Markov chains<br/>[markovchain.py]"]
  node_borda_score["Borda Score<br/>[borda_score.py]"]
end

subgraph group_sup["Supervised methods"]
  node_supervised_catalog["Supervised RA"]
  node_aggrankde["AggRankDE<br/>[aggrankde.py]"]
  node_crf["CRF<br/>[crf.py]"]
  node_csra["CSRA"]
end

subgraph group_semi["Semi-supervised methods"]
  node_ssra["SSRA<br/>[ssra.py]"]
end

subgraph group_eval["Evaluation"]
  node_evaluation["Ranking metrics<br/>[evaluation.py]"]
end

node_researcher(("Researcher"))
node_datasets["Benchmark data"]
node_rank_results["Aggregated rankings"]

node_researcher -->|"loads or saves"| node_io
node_datasets -->|"provides files"| node_io
node_io -->|"uses mapping"| node_processing
node_researcher -->|"selects method"| node_unsupervised_catalog
node_researcher -->|"invokes"| node_comb_methods
node_researcher -->|"invokes"| node_markov
node_researcher -->|"invokes"| node_borda_score
node_researcher -->|"selects method"| node_supervised_catalog
node_researcher -->|"trains or ranks"| node_aggrankde
node_researcher -->|"trains or ranks"| node_crf
node_researcher -->|"selects method"| node_csra
node_researcher -->|"trains or ranks"| node_ssra
node_researcher -->|"requests metrics"| node_evaluation
node_evaluation -->|"loads CSV"| node_io
node_aggrankde -->|"computes AP"| node_evaluation
node_crf -->|"computes NDCG"| node_evaluation
node_ssra -->|"writes rankings"| node_rank_results
node_markov -->|"saves rankings"| node_rank_results
node_borda_score -->|"writes rankings"| node_rank_results

click node_io "https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/datatools/data_io.py"
click node_processing "https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/datatools/data_process.py"
click node_input_types "https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/common/constant.py"
click node_unsupervised_catalog "https://github.com/nercms-mmap/ra-lib/tree/main/src/rapython/unsupervised"
click node_comb_methods "https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/unsupervised/combsum.py"
click node_markov "https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/unsupervised/markovchain.py"
click node_borda_score "https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/unsupervised/borda_score.py"
click node_supervised_catalog "https://github.com/nercms-mmap/ra-lib/tree/main/src/rapython/supervised"
click node_aggrankde "https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/supervised/aggrankde.py"
click node_crf "https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/supervised/crf.py"
click node_csra "https://github.com/nercms-mmap/ra-lib/tree/main/src/rapython/supervised/CSRA"
click node_ssra "https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/semi/ssra.py"
click node_evaluation "https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/evaluation/evaluation.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_io,node_processing,node_input_types toneBlue
class node_unsupervised_catalog,node_comb_methods,node_markov,node_borda_score toneAmber
class node_supervised_catalog,node_aggrankde,node_crf,node_csra toneMint
class node_ssra toneRose
class node_evaluation,node_researcher,node_datasets,node_rank_results toneIndigo
```

## Components

### Data handling

- [CSV input/output](https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/datatools/data_io.py): `src/rapython/datatools/data_io.py`
- [Rank processing](https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/datatools/data_process.py): `src/rapython/datatools/data_process.py`
- [Input types](https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/common/constant.py): `src/rapython/common/constant.py`

### Unsupervised methods

- [Unsupervised RA](https://github.com/nercms-mmap/ra-lib/tree/main/src/rapython/unsupervised): `src/rapython/unsupervised`
- [Comb methods](https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/unsupervised/combsum.py): `src/rapython/unsupervised/combsum.py`
- [Markov chains](https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/unsupervised/markovchain.py): `src/rapython/unsupervised/markovchain.py`
- [Borda Score](https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/unsupervised/borda_score.py): `src/rapython/unsupervised/borda_score.py`

### Supervised methods

- [Supervised RA](https://github.com/nercms-mmap/ra-lib/tree/main/src/rapython/supervised): `src/rapython/supervised`
- [AggRankDE](https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/supervised/aggrankde.py): `src/rapython/supervised/aggrankde.py`
- [CRF](https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/supervised/crf.py): `src/rapython/supervised/crf.py`
- [CSRA](https://github.com/nercms-mmap/ra-lib/tree/main/src/rapython/supervised/CSRA): `src/rapython/supervised/CSRA`

### Semi-supervised methods

- [SSRA](https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/semi/ssra.py): `src/rapython/semi/ssra.py`

### Evaluation

- [Ranking metrics](https://github.com/nercms-mmap/ra-lib/blob/main/src/rapython/evaluation/evaluation.py): `src/rapython/evaluation/evaluation.py`

### Other components

- **Researcher**
- **Benchmark data**
- **Aggregated rankings**

## Connections

- Researcher → CSV input/output: loads or saves
- Benchmark data → CSV input/output: provides files
- CSV input/output → Rank processing: uses mapping
- Researcher → Unsupervised RA: selects method
- Researcher → Comb methods: invokes
- Researcher → Markov chains: invokes
- Researcher → Borda Score: invokes
- Researcher → Supervised RA: selects method
- Researcher → AggRankDE: trains or ranks
- Researcher → CRF: trains or ranks
- Researcher → CSRA: selects method
- Researcher → SSRA: trains or ranks
- Researcher → Ranking metrics: requests metrics
- Ranking metrics → CSV input/output: loads CSV
- AggRankDE → Ranking metrics: computes AP
- CRF → Ranking metrics: computes NDCG
- SSRA → Aggregated rankings: writes rankings
- Markov chains → Aggregated rankings: saves rankings
- Borda Score → Aggregated rankings: writes rankings