GRASS logo

NAME

p.rank.cross - Cross-region ranking of landing-site candidates from multiple p.rank reports.

KEYWORDS

Planetary, Decision Support, ranking, landing

SYNOPSIS

p.rank.cross
p.rank.cross --help
p.rank.cross reports=name [region_ids=string] [weights=string] [area_transform=string] [n_top=integer] [output=name] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

reports=name [required]
Comma-separated p.rank JSON report files (one per region)
Each file is read; its `candidates` array is merged into the cross ranking. Region id defaults to the report filename stem and can be overridden via `region_ids`.
region_ids=string
Comma-separated region ids matching `reports` order (overrides filename stems)
weights=string
Composite-score weights as suit:<w>,area:<w>,borda:<w>
Each component is normalised to [0,1] across all merged candidates before being weighted. Component weights are renormalised to sum=1. Defaults: suit:0.6, area:0.25, borda:0.15.
Default: suit:0.6,area:0.25,borda:0.15
area_transform=string
Pre-normalisation transform for area_km2
log compresses orders-of-magnitude differences (typical when a region has both ~1 km² and ~1000 km² patches); linear preserves them.
Options: linear, log, sqrt
Default: log
n_top=integer
Maximum candidates retained in the cross-ranked output
Default: 20
output=name
Output JSON report (unified cross-region ranking)
Name for output file
Default: cross_ranking_report.json

Table of contents

DESCRIPTION

p.rank.cross ingests multiple p.rank JSON reports — one per region or per mission variant — and produces a single ranked table of the best candidates across all of them. It is the natural top-of-pipeline step when the same toolkit is run independently on N candidate regions (e.g. the NASA Artemis III shortlist of ~13 polar regions) and a unified ranking is needed for mission planning.

The composite score per candidate is a weighted combination of three normalised components:

composite = w_suit  · norm(suit_mean)
          + w_area  · norm(transform(area_km2))
          + w_borda · norm(borda_score)

where borda_score is an intra-region rank-based score (top candidate in a region with K candidates gets K points, …, last gets 1), optionally multiplied by the candidate's Monte-Carlo rank1_probability (from p.rank) so that weight-uncertainty information from the per-region analyses survives the cross-rank step.

The area transform defaults to log(1+area) which compresses the typical orders-of-magnitude spread between small inter-crater patches and ellipse-sized safe regions; linear and sqrt are also supported.

PARAMETERS

Parameter Default Description
reports required Comma-separated list of p.rank JSON report files
region_ids report stems Override region labels (must match reports order)
weights suit:0.6,area:0.25,borda:0.15 Composite-score component weights; renormalised to sum=1
area_transform log linear, sqrt or log (log1p)
n_top 20 Maximum candidates retained in the cross-ranked output
output cross_ranking_report.json Output JSON path

OUTPUT FORMAT

The output JSON has the schema tag p.rank.cross/v1 and contains:

EXAMPLES

Default cross-rank of three regions

p.rank.cross reports=region_a_report.json,region_b_report.json,region_c_report.json \
             output=cross_ranking.json

Up-weight area when small patches are not operationally viable

p.rank.cross reports=r1.json,r2.json,r3.json \
             weights=suit:0.4,area:0.5,borda:0.1 \
             area_transform=linear  output=area_first.json

NASA Artemis-style multi-region shortlist

# Run p.landing once per region with separate mapsets, then aggregate
p.rank.cross \
  reports=$(ls ~/grassdata/Moon_SouthPole_5m/artemis_*_report.json | paste -sd,) \
  region_ids=connecting_ridge,de_gerlache,malapert_massif,nobile_rim,mons_mouton \
  n_top=30 output=artemis_shortlist.json

NOTES

All input JSON files must have been produced by the same version of p.rank because the schema is validated for required keys. Per-region normalisation is applied before cross-region aggregation, so absolute suitability values need not be comparable across regions. The output JSON can be passed directly to g.gui.landing for visualisation.

SEE ALSO

p.rank, p.landing, p.mcdm.score

AUTHOR

Yann Chemin

SOURCE CODE

Available at: p.rank.cross source code (history)

Accessed: Sunday Nov 15 11:06:05 2026


Main index | Paint index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual