Blooming Tree Hierarchical Structure Analysis Script

Version 1.9 — 2026.08

BlmTree identifies galaxy systems and substructures in spectroscopic redshift catalogs by building a hierarchical tree with projected binding energy as the linking quantity.

The script is developed by Dr. Heng Yu of Beijing Normal University with Prof. Antonaldo Diaferio of the University of Turin and the Caustic Group.

Requirements

Python 3.8 or later is recommended.

pip install numpy scipy matplotlib scikit-learn

scikit-learn is required only for sigma-plateau trimming.

Input catalog

The input catalog must contain at least three columns:

RA  DEC  redshift_or_cz  [additional columns ...]

Column	Meaning	Unit
1	Right ascension	degree
2	Declination	degree
3	Spectroscopic redshift z or c*z	dimensionless or km/s

Additional columns are allowed and are preserved in the prepared catalog. They are not used by the tree calculations.

Blank lines and lines beginning with # are ignored. Whitespace, comma, semicolon, and tab separators are supported. A single text header such as

RA  DEC  z

is accepted when the first three fields of the first data-like row are all non-numeric. The first three fields of every actual data row must be numeric.

The third-column convention is determined from its numerical range:

• max(abs(column_3)) <= 10: interpreted as spectroscopic redshift z;
• otherwise: interpreted as c*z in km/s.

The prepared catalog always stores column 3 as

cz = c * z_spec

with c = 299792.458 km/s.

For raw catalogs, the minimum analysis redshift is z = 0.01.

Prepared catalog

A raw catalog is filtered into an automatically numbered working catalog:

CATALOG.g00
CATALOG.g01
CATALOG.g02
...

The .gNN catalog is the actual input to the hierarchical-tree analysis.

RA  DEC  cz  [all retained source columns ...]

Its properties are:

• rows remain in filtered input order;
• all additional source columns are retained;
• only column 3 is normalized to c*z;
• tree calculations read only columns 1–3;
• tree leaf ID i corresponds to row i of .gNN;
• .glis uses the same row order as .gNN.

This row correspondence allows group members in .glis to be matched directly to IDs, magnitudes, or other information stored in the additional .gNN columns.

An existing .gNN file can be supplied directly as the analysis catalog.

Usage

The examples below use blmtree.py as the executable name.

Validate and prepare a catalog:

blmtree.py CATALOG test

sum is accepted as an alias for test.

Blooming Tree / dEta trimming:

blmtree.py CATALOG dEta=20

Binding-energy trimming:

blmtree.py CATALOG bEne=-1

Velocity-dispersion trimming:

blmtree.py CATALOG vdis=500

Eta trimming:

blmtree.py CATALOG eta=50

Node-ID trimming:

blmtree.py CATALOG node=1200

Sigma-plateau trimming is selected when no direct trimming keyword is supplied:

blmtree.py CATALOG mem=10

Apply a redshift range when preparing a raw catalog:

blmtree.py CATALOG dEta=20 z0=0.10 z1=0.20

Set separate detection and plotting limits:

blmtree.py CATALOG dEta=50 mem=20 mplot=25 vdislim=200 vdisplot=250

Reuse a prepared catalog:

blmtree.py CATALOG.g00 dEta=20
blmtree.py CATALOG.g00 vdis=500 mem=15

z0 and z1 define the tree sample only while a raw catalog is being prepared. When an existing .gNN file is supplied, they are used only for later plotting/group display.

Command-line parameters

Parameter names are case-insensitive.

Parameter	Meaning	Default / behavior
p	Fixed galaxy-mass scale. Each galaxy uses p * 10^11 M_sun / h.	10
bEne	Direct trimming threshold on .gtre binding energy.	Selects bEne mode.
bindE	Alias of bEne.	Same as bEne.
vdis	Direct trimming threshold on rest-frame velocity dispersion.	Selects vdis mode.
dEta	Blooming Tree eta-jump threshold.	Selects dEta mode.
eta	Direct trimming threshold on tree eta.	Selects eta mode.
node	Direct threshold on internal tree node ID.	Selects node mode.
z0	Lower redshift bound when preparing a raw catalog.	0.01 if only z1 is given; values below 0.01 are clamped.
z1	Upper redshift bound when preparing a raw catalog.	1 if only z0 is given.
mem	Minimum structure-size threshold. Selection uses N_mem > mem.	9 in parameterized CLI runs.
mplot	Minimum member threshold for displayed groups.	Same as mem.
vdisLim	Minimum velocity dispersion for accepted dEta structures.	100 km/s
vdisPlot	Minimum velocity dispersion for plotted/displayed groups and DS9 regions.	200 km/s

Use only one direct trimming keyword (bEne, bindE, vdis, dEta, eta, or node) in one command. If none is supplied, sigma-plateau trimming is used.

Science quantities

Redshift and rest-frame velocity

The catalog convention is

cz = c * z_spec

The rest-frame line-of-sight velocity difference used by the hard pair filter is

delta_v_rest = c * |z1 - z2| / (1 + (z1 + z2)/2)

Candidate pairs must satisfy

delta_v_rest < 10000 km/s

The binding-energy kinetic term uses the Serra geometric line-of-sight separation Pi, converted with H0/(1+z_mid).

Fixed galaxy mass

All galaxies use the same mass scale:

M_gal = p * 10^11 M_sun / h

with H0 = 67.4 km/s/Mpc.

Velocity dispersion

Group and node velocity dispersion is

sigma_v = std(cz) / (1 + z_center)

The reported uncertainty is

delta_sigma = sigma_v * 10^(-0.17) * N_mem^(-0.49)

Group center and projected radii

Group summaries use mean RA, mean DEC, and mean cz, with RA wraparound handled across 0/360 degrees.

r50 and r90 are the 50th and 90th percentiles of projected member radii around the group center, converted to comoving Mpc.

The .gtre quantity r_avg is the mean of all unique pairwise great-circle angular separations in the node multiplied by the node comoving distance.

Comoving distance

Comoving distance is interpolated from the distance table bundled in the script. The table covers approximately 0 <= z <= 1 and uses H0 = 67.4 km/s/Mpc.

Output naming

For dEta, bEne, vdis, node, and eta trimming:

CATALOG.gNN_<trim>_thr<THRESHOLD>_vdisL<VDISLIM>_M<MEM>

For sigma plateau:

CATALOG.gNN_sigpl_M<MEM>

Main data products

CATALOG.gNN

Prepared analysis catalog:

RA  DEC  cz  [additional source columns ...]

CATALOG.gNN.json

Metadata shared by prepared-catalog and tree-level products. It stores product hashes, source inputs, column definitions, units, relevant parameters, software version, timestamps, and science conventions.

CATALOG.gNN.gpwbe

Condensed pairwise projected binding-energy array.

This is a one-dimensional float32 binary array in SciPy condensed pair order:

(0,1), (0,2), ... (0,N-1), (1,2), ... (N-2,N-1)

It contains

N * (N - 1) / 2

values.

CATALOG.gNN.gtre

Main hierarchical-tree table with 14 columns:

#	Column	Meaning	Unit
1	nodeid	Internal tree node ID	—
2	lkid	Left child ID	—
3	rkid	Right child ID	—
4	bind_energy	Linkage projected binding energy	(km/s)^2 10^11 M_sun/h
5	N_mem	Number of member leaves	—
6	cz	Mean member c*z	km/s
7	vdis	Rest-frame velocity dispersion	km/s
8	r_avg	Mean pairwise projected scale	Mpc
9	r50	Projected 50-percent member radius	Mpc
10	distance	Comoving distance	Mpc
11	ra	Mean RA	degree
12	dec	Mean DEC	degree
13	eta	vdis / r_avg / sqrt(N_mem)	km/s/Mpc
14	deltav	6/N_mem * (2*vdis/(r_avg*H0))^2	dimensionless

For N leaves, leaf IDs are 0 ... N-1 and internal node IDs are N ... 2N-2.

CATALOG.gNN.gepr

Binding-energy profile used by dEta trimming:

node_id  profile_position  binding_energy

CATALOG.gNN_dEta_thr*_M*.gbrc

Blooming Tree branch-candidate table:

#	Column	Meaning	Unit
1	minimum_node	Local binding-energy minimum starting the branch	—
2	N_mem	Members under the selected key node	—
3	key_node	Absolute selected tree node ID	—
4	r50	Projected half-number radius	Mpc

CATALOG.gNN_dEta_thr*_M*.getap

Variable-length eta profile for each traced branch:

minimum_node  eta_0 eta_1 ... eta_k  N_0 N_1 ... N_k

CATALOG.gNN_dEta_thr*_vdisL*_M*.gsub

Detailed dEta structure-node table with 17 columns:

#	Column	Meaning	Unit
1	sID	Structure ID	—
2	minID	Branch/local-minimum source ID	—
3	nodeID	Absolute selected tree node ID	—
4	lkid	Left child ID	—
5	rkid	Right child ID	—
6	E_bind	Node binding energy	(km/s)^2 10^11 M_sun/h
7	N_mem	Number of members	—
8	z	Mean spectroscopic redshift	—
9	Vdis	Rest-frame velocity dispersion	km/s
10	r_avg	Mean pairwise projected scale	Mpc
11	r50	Projected 50-percent member radius	Mpc
12	dist	Comoving distance	Mpc
13	centroid_x	Mean RA	degree
14	centroid_y	Mean DEC	degree
15	Eta	Tree eta value	—
16	deltaEta	Selected eta jump	—
17	base	Eta value below the selected jump	—

OUT.glis

Galaxy membership table. Row order is identical to the prepared .gNN catalog.

For dEta, bEne, vdis, node, and eta:

RA  DEC  z  group_id

group_id = 0 indicates no selected structure.

For sigma plateau:

RA  DEC  z  cluster_group_id  substructure_group_id

The final membership column is used by the standard plotting functions.

OUT.gsum

Structure summary table with 10 columns:

#	Column	Meaning	Unit
1	Cl_ID	Membership class ID	—
2	sub_ID	Group ID within the class	—
3	num	Number of members	—
4	RA	Mean RA	degree
5	DEC	Mean DEC	degree
6	z	Mean spectroscopic redshift	—
7	vdis	Rest-frame velocity dispersion	km/s
8	vdis_err	Velocity-dispersion uncertainty	km/s
9	r50	Projected 50-percent member radius	Mpc
10	r90	Projected 90-percent member radius	Mpc

For non-sigma-plateau trimming, Cl_ID = 0. For sigma plateau, class 0 is the parent cluster and class 1 contains substructures.

CATALOG.gNN_sigpl.gthr

Sigma-plateau threshold file:

v_disp  v_d_e  ID_cl  ID_sub  E_cl  E_sub  v_cl  v_sub  w  w/c  mtyp

Field	Meaning
v_disp	Mean of the selected Gaussian plateau component
v_d_e	Width of the selected Gaussian component
ID_cl	Tree-row index of the cluster-side boundary
ID_sub	Tree-row index of the substructure-side boundary
E_cl	Binding energy at the cluster boundary
E_sub	Binding energy at the substructure boundary
v_cl	Velocity dispersion at the cluster boundary
v_sub	Velocity dispersion at the substructure boundary
w	Gaussian-mixture weight
w/c	Component weight divided by its width
mtyp	Fixed mass parameter p

OUT.json

Metadata for one tree-cut analysis. The analysis section contains:

zrange
trim
threshold
mass_parameter
mem_limit
mem_plot
vdis_limit
vdis_plot

The same JSON document records metadata for .glis, .gsum, and, for dEta, .gsub.

Plot and display products

Product	Content
*_dtreep.pdf	Binding-energy profile for dEta analysis
branches/*.pdf	Per-branch dEta eta/structure diagnostics
*_sigpl_k*_vhst.png	Sigma-plateau velocity-dispersion profile and Gaussian-mixture histogram
*_k*_E.png	Sigma-plateau binding-energy profile
*_k*_eta.png	Sigma-plateau eta profile
*_dtree_y-*.pdf	Hierarchical dendrogram
*_1D2_m*.pdf	Group redshift distributions
*_2D_m*.pdf	RA-DEC sky distribution
*_zDt_m*.pdf	Transverse-position versus redshift diagram
*_stree_vdis*_m*.pdf	Simplified dEta velocity-dispersion hierarchy
*_stree_vdis*_m*.gtre	Data table for the simplified dEta hierarchy
*.reg	DS9 FK5 regions for selected members

Plot images do not have JSON metadata sidecars.

References

• Serra, A. L. et al. 2011, MNRAS, 412, 800 — sigma-plateau / caustic-tree framework.
• Yu, H. et al. 2018, ApJ, 860, 118 — Blooming Tree method.
• Yu, H. & Diaferio, A. 2025, ApJ, 991, 220 — velocity-dispersion uncertainty calibration.

License

BSD 3-Clause License. See LICENSE in the repository.