Skip to content

SVReg v23a

Choose a tag to compare

View all tags
@dshattuck dshattuck released this 03 Sep 03:48
· 21 commits to main since this release
v23a
2352342

Release Downloads

MACOS LINUX WINDOWS MATLAB

Notes

  • Archived open-source release packages for SVReg v23a, extracted from the corresponding BrainSuite release.
  • Original release date: July 17, 2023.

Requirements

  • The release builds of SVReg 23a require the MATLAB 2023a runtime libraries.
  • If you don't have an active MATLAB 2023a installation, you can install the MATLAB runtime libraries for free using these links to the Mathworks MATLAB Runtime page:
MATLAB Runtime 2023b for 64-bit Mac MATLAB Runtime 2023a for 64-bit Win MATLAB Runtime 2023b for 64-bit Linux

Engineering Changelog: v21a → v23a

Date: October 26, 2023
Version Range: v21a (Legacy) to v23a (Current)
Status: Major Release
Prepared By: Principal Software Engineer

Executive Summary

The transition from v21a to v23a represents a feature-rich evolution focused on expanding neuroimaging capabilities while modernizing the internal I/O infrastructure. Unlike previous major versions, this update prioritizes architectural stability at the file-system level (no deleted files) but introduces significant internal refactoring regarding NIfTI handling, numerical stability, and data serialization. The primary shift involves migrating from legacy save routines to a unified dws_write_nii backend and enhancing cortical thickness analysis pipelines.

1. Core Features

New capabilities added to the toolbox, expanding analytical scope.

Neuroimaging Pipeline Expansion

The architecture has shifted from general image handling to specialized neuroimaging metrics, specifically targeting FreeSurfer-style cortical processing.

  • Cortical Thickness Specialization:
    • Added support for distinct calculation modes: thicknessISO (Isosurface) and thicknessLE (Layer/Linear Estimate).
    • Introduced decomposition utilities: split_thickness_map_iso and split_thickness_map_LE to enable multi-layer or regional analysis of cortical depth.
  • Atlas & ROI Integration:
    • Added map_isothickness2atlas for projecting surface-derived thickness data onto volumetric atlases.
    • Introduced get_list_rois to extract specific Region-of-Interest values, a capability absent in v21a.

Enhanced I/O Handling

  • Strict Data Preservation: New loaders (load_nii, load_untouch_nii_gz) and savers (save_untouch_nii_gz) introduced to preserve metadata, headers, and specific binary structures without modification.
  • Resource Robustness: Added fallback mechanisms in svreg_label_surf_hemi.m where missing hippocampus carve files now default to cerebrum masks, preventing runtime errors due to missing atlas assets.

2. Breaking API Changes

Changes that may require updates to user scripts or external integrations.

Function Signature Reductions

  • src/load_nii_BIG_Lab.m:
    • v21a: Returned four outputs [nii, reorient_matrix, sform_new, niifileFlag].
    • v23a: Reduced to a single output [nii].
    • Impact: Scripts relying on the secondary return values (reorientation matrices or file flags) will fail. Users must now inspect fields within the returned nii structure for metadata.

Dependency Shifts

  • I/O Backend Migration: The codebase has migrated from generic save functions (save_nii, save_untouch_nii_gz) to the domain-specific dws_write_nii.
    • Impact: Environments must ensure the dws toolkit is available. Scripts relying on the legacy save function signatures or specific file naming conventions generated by the old backend may encounter discrepancies in output paths (e.g., .map.img.nii.gz vs .map.nii.gz).

3. Architectural Upgrades

Internal refactoring, performance optimizations, and stability improvements.

I/O Backend Standardization

A unified write interface has been implemented across multiple modules to ensure spatial consistency and header fidelity.

  • Modules Affected: extend_deformation_laplacian_hippo.m, fix_surfreg_map.m, get_sub2tar_air_map.m, inv_svreg_map.m, make_map_better.m, svreg_elastic_vol_reg_nonlin_cg.m, svreg_volreg.m.
  • Change: Replaced legacy two-step processes (save + fixBSheader) with an atomic operation using dws_write_nii.
  • Header Management: Explicit extraction of spatial metadata via niftiinfo from reference files (e.g., .bfc.nii.gz) is now required before writing, ensuring validated headers rather than inferred ones.

Numerical Stability & Hardening

  • src/mymap_le_align_varsig_ini.m:
    • Implemented epsilon floors (max(eps, ...)) for division and magnitude calculations.
    • Benefit: Prevents Inf or NaN propagation during geometric projections when inputs approach zero (degenerate triangle states).
  • src/thicknessPVC.m:
    • Enforced explicit double-precision output (Datatype='double') for solution heatmaps to prevent precision loss.

Logic Simplification & Optimization

  • Graph Construction Removal (src/myclean_patch_cc.m):
    • Removed internal connectivity dependencies (triangles_connectivity) and adjacency matrix generation (sparse).
    • Benefit: Reduced memory overhead and simplified the data pipeline by decoupling from explicit graph construction.
  • Data Flow Optimization (src/inv_svreg_map.m):
    • Eliminated intermediate disk I/O loops. The function now utilizes in-memory volume structs (vww) instead of reloading temporary files (load_nii_z).
  • Control Flow Restructuring (src/refine_vol_labels.m):
    • Shifted from fixed intensity thresholds to label membership (ismember) for generic datasets, improving robustness against varying signal magnitudes.

State Management Updates

  • src/smooth_surf_function.m:
    • Refactored state dependency logic. Initialization of a2 now strictly depends on the existence and propagation of a1, ensuring consistent data caching between calls.

4. Deprecations

Legacy functions and patterns removed or disabled in favor of new standards.

Deprecated Functions (Commented/Removed)

The following functions have been effectively deprecated within the active codebase, replaced by newer I/O standards:

  • save_untouch_nii_gz (Replaced by dws_write_nii)
  • fixBSheader (Logic integrated into dws_write_nii)
  • save_nii (Replaced by niftiwrite or dws_write_nii)
  • make_nii (Removed in favor of direct struct assignment)

Deprecated Patterns

  • Intermediate Cleanup: In src/get_air_map.m, the automatic deletion of intermediate .mat files has been disabled. These are now expected to be managed by external processes or retained for downstream usage.
  • Hardcoded Paths: Removal of hardcoded file path examples in src/get_sub2tar_air_map.m to enforce generic argument-based usage.

5. File Integrity & Stability Note

  • No Deletions: The Deleted Files list is empty. All existing code structure from v21a remains intact within the src/ folder.
  • Backward Compatibility: Existing file paths and module locations are preserved. Users upgrading from v21a do not need to modify their directory structures, though they should update scripts calling load_nii_BIG_Lab.m or relying on specific I/O function signatures.

Full Changelog: v21a...v23a

Assets 3
Loading