spatial_suv_charact/src

Functions of spatial_suv_charact

Utilities for PET SUV NIfTI analysis, with emphasis on spatial properties of high-SUV tail regions.

The code is organized into focused modules instead of one long utils.py file. This keeps the data-management, image-processing, feature-extraction and plotting tasks separate and easier to test.

File organization

utils.py              -> remove or keep only temporary imports
metadata.py           -> dataframe / patient metadata utilities
image_io.py           -> NIfTI loading and segmentation application
suv_stats.py          -> simple SUV distribution features
spatial_features.py   -> tail features and helper functions
plotting.py           -> Plotly visualization

In this version, utils.py is kept as a thin compatibility layer that re-exports the functions from the focused modules. New code should import directly from the specific module.

Tail features currently computed

Basic tail intensity

• threshold
• tail_mean
• tail_median
• tail_max
• tail_std
• tail_cv
• tail_sum
• tail_excess_mean
• tail_excess_sum

Volume / voxel counts

• n_roi_voxels
• roi_volume_mm3
• n_tail_voxels
• tail_volume_mm3
• tail_fraction

Note: if the threshold is defined as a within-ROI percentile, tail_fraction is mostly determined by the chosen percentile. It is included mainly for checking and completeness.

Spatial spread

• tail_spread_mm2
• tail_weighted_spread_mm2

These measure how spatially dispersed high-SUV voxels are.

Local contrast

• tail_local_contrast
• tail_local_contrast_norm

tail_local_contrast is a continuous, non-discretized contrast-like measure:

mean over neighboring voxel pairs inside R_q of (SUV_i - SUV_j)^2

tail_local_contrast_norm divides this value by tail_mean ** 2, giving a dimensionless version that is easier to compare across patients.

Connected-component features

• n_components
• largest_component_voxels
• largest_component_volume_mm3
• largest_component_fraction
• component_entropy

These describe whether high-SUV voxels form one dominant region or many disconnected foci.

Shape feature

• largest_component_sphericity

This is an approximate marching-cubes-based sphericity of the largest connected component.

Connectivity

The connectivity argument controls both connected components and local contrast neighborhoods:

6  -> face neighbors
18 -> face + edge neighbors
26 -> face + edge + corner neighbors

For small or noisy PET regions, connectivity=26 and min_component_voxels=3 is a reasonable starting point.