This repository contains the data analysis pipeline, spectral fitting routines, and kinematic modelling code accompanying the paper:
**"Before fragmentation: From uniform clouds to stellar clusters"** (Giannetti et al., 2026, Astronomy & Astrophysics).
The code processes combined ALMA Main Array (MA), Atacama Compact Array (ACA), and Total Power (TP) observations to study the transition from uniform gas to active cluster formation in massive clumps.
## Key Features
***Automated Spectral Decomposition:** Pixel-by-pixel multi-component line fitting (up to 3 components) using `pyspeckit`.
***Dynamic BIC Masking:** Progressive fitting strategy that relies on the Bayesian Information Criterion (BIC) and theoretical $3\sigma$ noise thresholds to prevent overfitting in diffuse regions.
***3D Kinematic Clustering:** Uses Bayesian Gaussian Mixture models (`scikit-learn`) in Position-Position-Velocity (PPV) space to isolate coherent physical structures.
***Velocity Gradient Fitting:** Extracts filamentary radial and longitudinal velocity gradients using 3D planar fits (`pyvista`).
***Volume Density Inference:** Computes gas-phase number densities directly from $\mathrm{CH_3OH}(2_K-1_K)$ integrated line intensity ratios using a censored likelihood MCMC model in `PyMC`.
***Feathering Validation:** Automated comparison between TP-only and feathered (ALMA+TP) cubes to verify extended flux recovery.
2. Create a virtual environment and install the required packages:
```bash
pip install-r requirements.txt
```
*Required packages include:*`astropy`, `astroquery`, `matplotlib`, `numpy`, `pandas`, `pymc`, `pyspeckit`, `PyYAML`, `scikit-learn`, `scipy`, `seaborn`, `spectral-cube`, `reproject`, `pyvista`, and the `trame` suite for interactive 3D rendering.
## Project Structure
The repository is structured into distinct pipeline stages:
```text
CoCoA_decomposition/
├── etl/ # Extraction, Transformation, Loading
│ ├── assets/ # Contains commons, constants, templates, and raw FITS data
│ └── config/ # Global configuration files
├── mdl/ # Modelling & Core Analysis
│ ├── config/ # Configurations for rest frequencies and line limits
│ ├── decomposition_results/ # Output maps from the spectral fitter
│ ├── inferred_densities/ # Outputs from the PyMC density inference
│ ├── mdl_psk_decomposition.py # Main PySpecKit multi-component fitting script
│ └── mdl_extract_clump_spectra_and_densities.py
├── prs/ # Presentation, Plotting & Kinematics
│ ├── pickles/ # Serialized arrays and velocity field masks
│ ├── figures/ # Final output plots for the manuscript
│ ├── prs_visfit_3d_velocities.py # 3D PPV clustering and planar gradient fitting
├── figures/ # Validation plots (e.g., TP vs Feather spectra)
└── stg_check_feather.py # Validates interferometric data combination
```
## Usage
### 1. Data Preparation
The ALMA FITS cubes are not included in this repository due to size constraints. Download the feathered cubes and TP data from the ALMA Science Archive (Project Code: `2018.1.00299.S`) and place them in the `etl/assets/data/` directory.
### 2. Spectral Fitting (`mdl/`)
Run the multi-component fitting routine. This script uses `pyspeckit` to fit $\mathrm{N_2H^+}$ and $\mathrm{CH_3OH}$, dynamically selecting the number of components based on the BIC threshold.
```bash
python mdl/mdl_psk_decomposition.py
```
### 3. Kinematic Analysis & 3D Rendering (`prs/`)
Extract the velocity fields, perform Gaussian Mixture clustering, and fit the 3D planar velocity gradients. This will also generate interactive 3D renderings using `pyvista`.
```bash
python prs/prs_visfit_3d_velocities.py
```
The 3D version of the figure is also accessible via a [Colab Notebook](https://colab.research.google.com/drive/1rKI06UAOoi60jMVzRfYv4Wkwhir5Qgq4?usp=sharing).
