astrocook.recipes.absorbers module#

class astrocook.recipes.absorbers.RecipeAbsorbersV2(session_v2: SessionV2)[source]#

Bases: object

Recipes for identification, fitting, and management of absorption lines.

These methods are accessed via the session.absorbers attribute and delegate logic to SystemListV2, SpectrumV2, and the fitting engine.

__init__(session_v2: SessionV2)[source]#
components_auto(multiplets: str = 'CIV,SiIV,MgII,Ly_ab', score_threshold: str = '0.5', merge_dv: str = '10.0', min_pix_region: str = '3', mask_col: str = 'abs_mask', z_window_kms: str = '20.0', region_limit: str = 'None') → SessionV2[source]#

Auto-detect and fit components.

The Master Pipeline: Identifies candidates (doublets or singles), populates them as systems, and refits the spectrum. Supports masking by region. Delegates to identify_lines(), populate_from_identification(), and refit_all().

Parameters:

  • multiplets (str, optional) – Comma-separated list of multiplets to search for. Defaults to "CIV,SiIV,MgII,Ly_ab".

  • score_threshold (str, optional) – Min R^2 score (0-1) to accept a candidate. Defaults to "0.5".

  • merge_dv (str, optional) – Max velocity (km/s) to merge adjacent regions. Defaults to "10.0".

  • min_pix_region (str, optional) – Minimum width in pixels to count as a region. Defaults to "3".

  • mask_col (str, optional) – Name of the mask column (True=Absorbed). Defaults to "abs_mask".

  • z_window_kms (str, optional) – Velocity window for fitting (km/s). Defaults to "20.0".

  • region_limit (str, optional) – Limit search to 'red_side', 'lya_forest', or 'None'. Defaults to "None".

Returns:

A new SessionV2 with detected systems, or 0 on failure.

Return type:

SessionV2 or int

doublets_auto(multiplets: str = 'CIV,SiIV,MgII', score_threshold: str = '0.5', z_window_kms: str = '20.0') → SessionV2[source]#

Auto-fit metal doublets (Red Side).

Wrapper for components_auto() targeted at the red side (z < z_em). Finds CIV, SiIV, MgII.

Parameters:

  • multiplets (str, optional) – Multiplets to search for. Defaults to "CIV,SiIV,MgII".

  • score_threshold (str, optional) – Min R^2 score (0-1). Defaults to "0.5".

  • z_window_kms (str, optional) – Fit window (km/s). Defaults to "20.0".

Returns:

A new SessionV2 with detected doublets.

Return type:

SessionV2

lya_auto(score_threshold: str = '0.1', min_b: str = '10.0', z_window_kms: str = '100.0') → SessionV2[source]#

Auto-fit Ly-alpha forest.

Wrapper for components_auto() targeted at the forest. Includes filtering of interlopers based on the b-parameter. Delegates to astrocook.core.system_list.SystemListV2.filter_by_criteria().

Parameters:

  • score_threshold (str, optional) – Lower threshold for single lines (R^2). Defaults to "0.1".

  • min_b (str, optional) – Minimum b parameter (km/s) to keep. Defaults to "10.0".

  • z_window_kms (str, optional) – Fit window (km/s). Defaults to "100.0".

Returns:

A new SessionV2 with the forest model.

Return type:

SessionV2

forest_auto(score_threshold: str = '0.1', min_b: str = '10.0', z_window_kms: str = '20.0') → SessionV2[source]#

Auto-fit full Lyman series.

Pipeline that models the entire Lyman series (Ly-alpha to Ly-limit) simultaneously. Uses ‘Ly_a’ detection but maps it to ‘Lyman’ series.

Parameters:

  • score_threshold (str, optional) – Threshold for detection. Defaults to "0.1".

  • min_b (str, optional) – Minimum b parameter (km/s). Defaults to "10.0".

  • z_window_kms (str, optional) – Fit window (km/s). Defaults to "20.0".

Returns:

A new SessionV2 with Lyman series systems.

Return type:

SessionV2

metals_auto(ions: str = 'CIV,SiIV,NV,OVI,CII,MgII', aic_penalty: str = '5.0', z_window_kms: str = '20.0') → SessionV2[source]#

Check for associated metals.

Scans existing systems and attempts to add other common metal ions (e.g., NV, SiIV) at the same redshift, keeping them if fit quality holds. Delegates to astrocook.core.system_list.SystemListV2.add_component().

Parameters:

  • ions (str, optional) – Comma-separated list of ions to check. Defaults to "CIV,SiIV,NV,OVI,CII,MgII".

  • aic_penalty (str, optional) – AIC improvement required to keep a new ion (Not currently used in logic). Defaults to "5.0".

  • z_window_kms (str, optional) – Fit window (km/s) for local island fitting. Defaults to "20.0".

Returns:

A new SessionV2 with added metals, or 0 on failure.

Return type:

SessionV2 or int

identify_lines(multiplets: str = 'CIV,SiIV,MgII,Ly_ab', mask_col: str = 'abs_mask', min_pix_region: str = '3', merge_dv: str = '10.0', score_threshold: str = '0.5', bypass_scoring: str = 'False', debug_rating: str = 'False') → SessionV2[source]#

Identify likely absorption systems.

Finds absorption regions, computes correlation signals for multiplets, and identifies the most likely candidates using a scoring system. Delegates to astrocook.core.spectrum.SpectrumV2.identify_lines().

Parameters:

  • multiplets (str, optional) – Multiplets to search for (comma-separated). Defaults to "CIV,SiIV,MgII,Ly_ab".

  • mask_col (str, optional) – Mask column (True=Unabsorbed, used to find absorptions). Defaults to "abs_mask".

  • min_pix_region (str, optional) – Minimum width in pixels to count as a region. Defaults to "3".

  • merge_dv (str, optional) – Max velocity (km/s) to merge adjacent regions. Defaults to "10.0".

  • score_threshold (str, optional) – Min R^2 score (0 to 1) to accept a doublet candidate. Defaults to "0.5".

  • bypass_scoring (str, optional) – If 'True', accept all kinematic candidates ignoring score. Defaults to "False".

  • debug_rating (str, optional) – If 'True', show debug plots. Defaults to "False".

Returns:

A new SessionV2 with identification maps in metadata, or 0 on failure.

Return type:

SessionV2 or int

populate_from_identification(region_id_col: str = 'abs_ids', series_map_json: str = None, z_map_json: str = None) → SessionV2[source]#

Populate components from identification.

Populates the system list using the regions and candidates found by identify_lines(). Delegates to astrocook.core.system_list.SystemListV2.add_component() and astrocook.core.spectrum.SpectrumV2.update_model().

Parameters:

  • region_id_col (str, optional) – Column containing region IDs. Defaults to "abs_ids".

  • series_map_json (str, optional) – JSON string mapping Region ID -> Series Name.

  • z_map_json (str, optional) – JSON string mapping Region ID -> Redshift.

Returns:

A new SessionV2 with populated systems and updated model, or 0 on failure.

Return type:

SessionV2 or int

add_component(series: str = 'Ly_a', z: str = '0.0', logN: str = '13.5', b: str = '10.0', btur: str = '0.0', z_window_kms: str = '20.0') → SessionV2[source]#

Add a single component.

Adds a new manual Voigt component at a specific redshift and auto-fits it. Delegates to astrocook.core.system_list.SystemListV2.add_component().

Parameters:

  • series (str, optional) – Transition or Multiplet name (e.g. 'CIV'). Defaults to "Ly_a".

  • z (str, optional) – Redshift. Defaults to "0.0".

  • logN (str, optional) – Column Density (log cm^-2). Defaults to "13.5".

  • b (str, optional) – Doppler parameter (km/s). Defaults to "10.0".

  • btur (str, optional) – Turbulent broadening (km/s). Defaults to "0.0".

  • z_window_kms (str, optional) – Max shift for initial fit (km/s). Defaults to "20.0".

Returns:

A new SessionV2 with the added component, or 0 on failure.

Return type:

SessionV2 or int

update_component(uuid: str, z: str = 'None', logN: str = 'None', b: str = 'None', btur: str = 'None', series: str = 'None', resol: str = 'None') → SessionV2[source]#

Update component parameters.

Modifies the physical parameters of an existing component. Delegates to astrocook.core.system_list.SystemListV2.update_component().

Parameters:

  • uuid (str) – Component UUID.

  • z (str, optional) – Redshift. Defaults to 'None'.

  • logN (str, optional) – Column Density (log). Defaults to 'None'.

  • b (str, optional) – Doppler parameter (km/s). Defaults to 'None'.

  • btur (str, optional) – Turbulent broadening (km/s). Defaults to 'None'.

  • series (str, optional) – Series name. Defaults to 'None'.

  • resol (str, optional) – Resolution (R or FWHM). Defaults to 'None'.

Returns:

A new SessionV2 with updated component, or 0 on failure.

Return type:

SessionV2 or int

update_components(uuids: list, z: str = 'None', logN: str = 'None', b: str = 'None', btur: str = 'None', series: str = 'None', resol: str = 'None') → SessionV2[source]#

Batch update component parameters.

Modifies the physical parameters of multiple existing components simultaneously. Delegates to astrocook.core.system_list.SystemListV2.update_components().

Parameters:

  • uuids (list) – List of component UUIDs to update.

  • z (str, optional) – Redshift. Defaults to 'None'.

  • logN (str, optional) – Column Density (log). Defaults to 'None'.

  • b (str, optional) – Doppler parameter (km/s). Defaults to 'None'.

  • btur (str, optional) – Turbulent broadening (km/s). Defaults to 'None'.

  • series (str, optional) – Series name. Defaults to 'None'.

  • resol (str, optional) – Resolution (R or FWHM). Defaults to 'None'.

Returns:

A new SessionV2 with updated components, or 0 on failure.

Return type:

SessionV2 or int

delete_component(uuid: str = None, uuids: list = None) → SessionV2[source]#

Delete component(s).

Removes specified components and updates the model. Delegates to astrocook.core.system_list.SystemListV2.delete_component() and astrocook.core.spectrum.SpectrumV2.update_model().

Parameters:

  • uuid (str, optional) – UUID of a single component to delete.

  • uuids (list, optional) – List of UUIDs to delete.

Returns:

A new SessionV2 with components removed.

Return type:

SessionV2

detect_anchor(sibling_name: str, trans_self: str, trans_sibling: str) → float[source]#

Detect doublet anchor redshift.

Finds the redshift of maximum overlap between this session and a sibling session (useful for doublet identification across orders/exposures). Delegates to astrocook.core.spectrum.SpectrumV2.detect_doublet_z().

Parameters:

  • sibling_name (str) – Name of the sibling session.

  • trans_self (str) – Transition in this session (e.g., 'OVI_1031').

  • trans_sibling (str) – Transition in sibling session (e.g., 'OVI_1037').

Returns:

The detected redshift, or 0.0 on failure.

Return type:

float

fit_component(uuid: str, max_nfev: str = '2000', z_window_kms: str = '20.0', group_depth: str = '2') → SessionV2[source]#

Fit component.

Fits the selected component (and its connected neighbors) using the Voigt engine. Delegates to astrocook.core.system_list.SystemListV2.fitting_context() and astrocook.fitting.voigt_fitter.VoigtFitterV2.

Parameters:

  • uuid (str) – Target Component UUID.

  • max_nfev (str, optional) – Max iterations for the optimizer. Defaults to "2000".

  • z_window_kms (str, optional) – Max velocity shift allowed during fit (km/s). Defaults to "20.0".

  • group_depth (str, optional) – Grouping depth (1=Neighbors, 2=FoF). Defaults to "2".

Returns:

A new SessionV2 with updated parameters and model, or 0 on failure.

Return type:

SessionV2 or int

update_constraint(uuid: str, param: str, is_free: bool = None, expression: str = None, target_uuid: str = None) → SessionV2[source]#

Update constraint.

Freeze, unfreeze, or link component parameters. Delegates to astrocook.core.system_list.SystemListV2.update_constraint().

Parameters:

  • uuid (str) – Component UUID.

  • param (str) – Parameter name (z, logN, b).

  • is_free (bool, optional) – Is the parameter free to vary?

  • expression (str, optional) – Math expression for linking (e.g., "p['uuid'].z").

  • target_uuid (str, optional) – UUID of the source component (for linking tracking).

Returns:

A new SessionV2 with updated constraints, or 0 on failure.

Return type:

SessionV2 or int

update_constraints_column(param: str, is_free: bool) → SessionV2[source]#

Bulk update constraints.

Updates the constraint status (free/frozen) for a specific parameter across ALL components in the session.

Parameters:

  • param (str) – Parameter name (z, logN, b, btur).

  • is_free (bool) – Set to True (free) or False (frozen).

Returns:

A new SessionV2 with updated constraints, or 0 on failure.

Return type:

SessionV2 or int

add_linked_system(series_list: str, z: float, logN: float = 13.5, b: float = 10.0, z_window_kms: float = 20.0) → SessionV2[source]#

Add linked system.

Add multiple components (e.g. CIV, SiIV) and link their redshifts to the first component in the list.

Parameters:

  • series_list (str) – Comma-separated list of series (e.g., "CIV,SiIV").

  • z (float) – Redshift.

  • logN (float, optional) – Column Density. Defaults to 13.5.

  • b (float, optional) – Doppler parameter. Defaults to 10.0.

  • z_window_kms (float, optional) – Fit window. Defaults to 20.0.

Returns:

A new SessionV2 with linked components fitted, or 0 on failure.

Return type:

SessionV2 or int

optimize_system(uuid: str, max_components: str = '5', threshold_sigma: str = '2.5', aic_penalty: str = '0.0', z_window_kms: str = '100.0', min_dv: str = '10.0', group_depth: str = '2', patience: str = '2') → SessionV2[source]#

Optimize system (Iterative Fit).

Iteratively adds components to a system to minimize residuals using the Akaike Information Criterion (AIC). Delegates to astrocook.core.system_list.SystemListV2.optimize_hierarchy().

Parameters:

  • uuid (str) – Target Component UUID (seed).

  • max_components (str, optional) – Max extra components to try. Defaults to "5".

  • threshold_sigma (str, optional) – Residual threshold (sigma) to trigger new component. Defaults to "2.5".

  • aic_penalty (str, optional) – Min AIC improvement to accept new component. Defaults to "0.0".

  • z_window_kms (str, optional) – Velocity window (km/s) to analyze. Defaults to "100.0".

  • min_dv (str, optional) – Min separation (km/s). Defaults to "10.0".

  • group_depth (str, optional) – Grouping depth. Defaults to "2".

  • patience (str, optional) – Trials allowed without AIC improvement. Defaults to "2".

Returns:

A new SessionV2 with optimized systems, or 0 on failure.

Return type:

SessionV2 or int

fit_bayesian(uuids: list[str] = None, engine: str = 'mcmc', nsteps: str = '500', nlive: str = '250', group_depth: str = '2') → int[source]#

Run Bayesian sampling (MCMC or Nested) on a group of components.

Parameters:

  • uuids (list of str, optional) – A list of component UUIDs to fit. If not provided, a single component must be specified via other means (not supported here).

  • engine ({'mcmc', 'nested'}, optional) – The sampling engine to use (default: ‘mcmc’).

  • nsteps (str, optional) – Number of MCMC steps (default: ‘500’).

  • nlive (str, optional) – Number of live points for Nested Sampling (default: ‘250’).

  • group_depth (str, optional) – Depth of connected group search (FoF) to define the fitting group (default: ‘2’).

refit_all(max_nfev: str = '100', z_window_kms: str = '100.0', group_depth: str = '0', max_group_size: str = '20', region_limit: str = 'None', selected_uuids: list = None) → SessionV2[source]#

Refit all systems.

Iteratively fits all disjoint groups of components (islands) in the spectrum. Uses chunking for large groups. Delegates to astrocook.core.system_list.SystemListV2.get_connected_group() and astrocook.fitting.voigt_fitter.VoigtFitterV2.

Parameters:

  • max_nfev (str, optional) – Max iterations per group. Defaults to "100".

  • z_window_kms (str, optional) – Fit window around lines (km/s). Defaults to "100.0".

  • group_depth (str, optional) – Grouping depth (0=Iterative Single, 1=Neighbors). Defaults to "0".

  • max_group_size (str, optional) – Max components per fit group (chunking). Defaults to "20".

  • region_limit (str, optional) – Limit fitting to 'red_side' or 'lya_forest'. Defaults to "None".

Returns:

A new SessionV2 with all systems refitted, or 0 on failure.

Return type:

SessionV2 or int

clean_negligible(min_logN: str = '11.5', max_b: str = '80.0', min_b: str = '3.0', combined_check: str = 'True') → SessionV2[source]#

Clean negligible components.

Removes unphysical or negligible components from the system list. This is useful for cleaning up results after automated fitting procedures, which may produce artifacts such as extremely broad, shallow lines (ghosts) or narrow noise spikes.

The cleaning criteria are: 1. Narrow Spikes: Components with b < min_b. 2. Weak Lines: Components with logN < min_logN. 3. Broad/Ghost Lines: Components with b > max_b.

If combined_check is True, broad lines are only removed if they are also weak (logN < 13.0). This protects strong, broad features like DLA wings or OVI absorbers.

Parameters:

  • min_logN (str, optional) – Minimum column density (log cm-2) to keep. Defaults to "11.5".

  • max_b (str, optional) – Maximum Doppler parameter (km/s). Components broader than this may be removed. Defaults to "80.0".

  • min_b (str, optional) – Minimum Doppler parameter (km/s). Components narrower than this are always removed. Defaults to "3.0".

  • combined_check (str, optional) – If "True", broad components (b > max_b) are only removed if they are also weak (logN < 13.0). If "False", all broad components are removed. Defaults to "True".

Returns:

A new SessionV2 with the flagged components removed.

Return type:

SessionV2