firecrown.app.analysis

Analysis building infrastructure for Firecrown.

Provides base classes and utilities for building complete analysis setups with data files, factory files, and framework-specific configurations.

Public API (backward compatibility guaranteed):

• AnalysisBuilder: Base class for building analyses

• Frameworks: Enum of supported frameworks

• Model: Model parameter definition

• Parameter: Individual parameter definition

Internal modules (prefixed with _) are implementation details and may change without notice. Only use the public API exported in __all__.

Attributes

Prior
COSMO_DESC
CCL_COSMOLOGY_MINIMAL_SET

Classes

AnalysisBuilder	Base class for Firecrown analysis builders.
Frameworks	Statistical analysis frameworks supported by Firecrown.
Model	Model definition with multiple parameters.
Parameter	Model parameter with sampling metadata.
ConfigGenerator	Abstract base for framework-specific configuration generators.
FrameworkCosmology	Level of cosmology computation required by the framework.
PriorUniform	Uniform (flat) prior over a bounded interval [lower, upper].
PriorGaussian	Gaussian (normal) prior with specified mean and standard deviation.
CCLCosmologySpec	CCL cosmology specification model.
CosmosisConfigGenerator	CosmoSIS configuration generator.
NumCosmoConfigGenerator	NumCosmo configuration generator.
CobayaConfigGenerator	Cobaya configuration generator.

Functions

get_generator(framework, output_path, prefix, ...[, ...])	Factory function to create framework-specific configuration generator.
download_from_url(url, output_file, console[, description])	Download file from URL with caching and progress indicator.
copy_template(template_module, output_file)	Copy template module file to output location.

Package Contents

class firecrown.app.analysis.AnalysisBuilder

Bases: firecrown.app.logging.Logging

Base class for Firecrown analysis builders.

Orchestrates the generation of complete analysis examples through a phased workflow:

1. Generate/download SACC data file

2. Generate likelihood factory file

3. Generate build parameters

4. Generate model parameters

5. Generate framework-specific configuration files

Subclasses implement data-specific methods while the base class handles workflow orchestration and framework configuration delegation.

description: ClassVar[str]

Human-readable description of what this analysis demonstrates.

output_path: Annotated[pathlib.Path, typer.Argument(help='Directory where example files will be generated', show_default=True)]

prefix: Annotated[str, typer.Option(help="Prefix for generated filenames (e.g., 'analysis1' creates 'analysis1.sacc')", show_default=True)]

target_framework: Annotated[firecrown.app.analysis._types.Frameworks, typer.Option(help='Framework to generate example for', show_default=True, case_sensitive=False)]

sacc_format: Annotated[firecrown.app.sacc.SaccFormat, typer.Option(help='SACC file format.', show_default=True)]

use_absolute_path: Annotated[bool, typer.Option(help='Use absolute file paths in configuration files', show_default=True)] = True

cosmology_spec: Annotated[pathlib.Path | None, typer.Option(help='Path to cosmology specification file', show_default=True)] = None

__post_init__()

Initialize and execute the complete analysis generation workflow.

Return type:

None

abstractmethod generate_sacc(output_path)

Generate or download the SACC data file.

Parameters:

output_path (pathlib.Path) – Directory where files should be created

Returns:

Path to the generated SACC file

Return type:

pathlib.Path

abstractmethod generate_factory(output_path, sacc)

Generate the likelihood factory Python file.

Parameters:

• output_path (pathlib.Path) – Directory where files should be created

• sacc (pathlib.Path) – Path to the SACC data file

Returns:

Path to the generated factory file

Return type:

str | pathlib.Path

abstractmethod get_build_parameters(sacc_path)

Create build parameters for likelihood initialization.

Parameters:

sacc_path (pathlib.Path) – Path to the SACC data file

Returns:

Build parameters (typically includes sacc_file path)

Return type:

firecrown.likelihood.NamedParameters

abstractmethod get_models()

Define model parameters for sampling.

Returns:

List of models with their parameters (priors, bounds, etc.)

Return type:

list[firecrown.app.analysis._types.Model]

abstractmethod required_cosmology()

Return whether the analysis requires a cosmology.

Returns:

True if the analysis requires a cosmology, False otherwise

Return type:

firecrown.app.analysis._types.FrameworkCosmology

cosmology_analysis_spec()

Return the cosmology analysis specification.

Returns:

The cosmology analysis specification

Return type:

firecrown.app.analysis._types.CCLCosmologySpec

get_sacc_file(sacc_path)

Return the path to the SACC data file.

Returns either an absolute or relative path based on the use_absolute_path setting. When use_absolute_path is True, returns the full absolute path. Otherwise returns just the filename.

Parameters:

sacc_path (pathlib.Path) – Path to the SACC data file

Returns:

Path to the SACC file as a string, either absolute or relative

Return type:

str

get_options_desc()

Return a description of the analysis options.

Subclasses can override this method to provide additional information about the options used in the analysis.

Returns:

Description of analysis options

Return type:

Sequence[tuple[str, str]]

class firecrown.app.analysis.Frameworks

Bases: enum.StrEnum

Statistical analysis frameworks supported by Firecrown.

Each framework has its own configuration generator that produces framework-specific files for cosmological parameter estimation.

COBAYA = 'cobaya'

COSMOSIS = 'cosmosis'

NUMCOSMO = 'numcosmo'

class firecrown.app.analysis.Model(/, **data)

Bases: pydantic.BaseModel

Model definition with multiple parameters.

Groups related parameters (e.g., all photo-z shifts, all galaxy biases) into a named model for organization in configuration files.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

description: str

parameters: list[Parameter]

model_post_init(context, /)

Validate that parameter names are unique.

Creates a dictionary of parameters by name.

Return type:

None

has_priors()

Check if any parameters have priors defined.

Returns:

True if at least one parameter has a prior; False otherwise

Return type:

bool

__getitem__(key)

Return the value for the given key.

If the key has not been used, add it to the set of used keys.

Parameters:

key (str) – key

Returns:

value

Return type:

Parameter

__contains__(key)

Return True if the key is in the map, False otherwise.

Parameters:

key (str) – key

Returns:

True if the key is in the map, False otherwise

Return type:

bool

class firecrown.app.analysis.Parameter(/, **data)

Bases: pydantic.BaseModel

Model parameter with sampling metadata.

Defines a single parameter for cosmological or systematic modeling, including its prior bounds, default value, and whether it’s free or fixed.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

symbol: str

lower_bound: float

upper_bound: float

scale: float = 0.0

abstol: float = 0.0

default_value: float

free: bool

prior: Prior | None = None

classmethod fill_defaults(data)

Validate that scale is positive if provided.

Parameters:

data (Any)

Return type:

Any

validate_bounds()

Validate that lower_bound < upper_bound.

Return type:

Parameter

classmethod from_tuple(name, symbol, lower_bound, upper_bound, default_value, free, prior=None)

Create Parameter from tuple of values.

Parameters:

• name (str)

• symbol (str)

• lower_bound (float)

• upper_bound (float)

• default_value (float)

• free (bool)

• prior (Prior | None)

class firecrown.app.analysis.ConfigGenerator

Bases: abc.ABC

Abstract base for framework-specific configuration generators.

Uses a builder pattern with phased state management: 1. Create generator with output settings 2. Add components: add_sacc(), add_factory(), add_build_parameters(), add_models() 3. Write configuration: write_config()

Subclasses implement write_config() to generate framework-specific files.

framework: ClassVar[Frameworks]

output_path: pathlib.Path

prefix: str

use_absolute_path: bool

cosmo_spec: CCLCosmologySpec

required_cosmology: FrameworkCosmology

sacc_path: pathlib.Path | None = None

factory_source: str | pathlib.Path | None = None

build_parameters: firecrown.likelihood.NamedParameters | None = None

models: list[Model] = []

add_sacc(sacc_path)

Add SACC data file path to generator state.

Parameters:

sacc_path (pathlib.Path) – Path to SACC data file

Return type:

None

add_factory(factory_source)

Add likelihood factory source to generator state.

Parameters:

factory_source (pathlib.Path | str) – Path to factory Python file or YAML module string

Return type:

None

add_build_parameters(build_parameters)

Add build parameters to generator state.

Parameters:

build_parameters (firecrown.likelihood.NamedParameters) – Parameters for likelihood initialization

Return type:

None

add_models(models)

Add model parameters to generator state.

Parameters:

models (list[Model]) – List of models with sampling parameters

Return type:

None

abstractmethod write_config()

Write framework-specific configuration files using accumulated state.

Return type:

None

class firecrown.app.analysis.FrameworkCosmology

Bases: enum.StrEnum

Level of cosmology computation required by the framework.

Controls whether frameworks include Boltzmann solvers (CAMB/CLASS) and what level of computation they perform.

NONE = 'none'

BACKGROUND = 'background'

LINEAR = 'linear'

NONLINEAR = 'nonlinear'

firecrown.app.analysis.Prior

class firecrown.app.analysis.PriorUniform(/, **data)

Bases: pydantic.BaseModel

Uniform (flat) prior over a bounded interval [lower, upper].

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

lower: float

upper: float

model_post_init(_, /)

Validate that lower < upper.

Return type:

None

class firecrown.app.analysis.PriorGaussian(/, **data)

Bases: pydantic.BaseModel

Gaussian (normal) prior with specified mean and standard deviation.

Parameters:

data (Any)

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

mean: float

sigma: float

model_post_init(_, /)

Validate that sigma > 0.

Return type:

None

class firecrown.app.analysis.CCLCosmologySpec(/, **data)

Bases: Model

CCL cosmology specification model.

A specialized Model that represents the cosmological parameters used in CCL-based analyses.

Parameters:

data (Any)

name: str = 'ccl_cosmology'

description: str = 'CCL cosmology specification'

mass_split: str = 'normal'

transfer_function: str | Any = 'boltzmann_camb'

matter_power_spectrum: str | Any = 'halofit'

extra_parameters: firecrown.modeling_tools.CAMBExtraParams | None = None

model_post_init(context, /)

Validate that all parameters are cosmological.

Return type:

None

to_ccl_cosmology()

Convert to CCL cosmology dictionary.

Returns:

Dictionary of cosmological parameters for CCL

Return type:

pyccl.Cosmology

classmethod vanilla_lcdm()

Create a vanilla LCDM cosmology analysis spec with standard parameters.

Return type:

CCLCosmologySpec

classmethod vanilla_lcdm_with_neutrinos()

Create a vanilla LCDM cosmology analysis spec with standard parameters.

Return type:

CCLCosmologySpec

get_num_massive_neutrinos()

Get the number of massive neutrinos defined in the cosmology.

Return type:

int

get_amplitude_parameter()

Get the amplitude parameter for the power spectrum.

Return type:

firecrown.modeling_tools.PoweSpecAmplitudeParameter

firecrown.app.analysis.COSMO_DESC

firecrown.app.analysis.CCL_COSMOLOGY_MINIMAL_SET = ['Omega_c', 'Omega_b', 'Omega_k', 'h', 'n_s', 'Neff', 'm_nu', 'w0', 'wa']

firecrown.app.analysis.get_generator(framework, output_path, prefix, use_absolute_path, cosmo_spec, required_cosmology=FrameworkCosmology.NONLINEAR)

Factory function to create framework-specific configuration generator.

Parameters:

• framework (firecrown.app.analysis._types.Frameworks) – Target framework (cosmosis, cobaya, numcosmo)

• output_path (pathlib.Path) – Directory where configuration files will be written

• prefix (str) – Prefix for generated filenames (e.g., ‘des_y1’ → ‘cosmosis_des_y1.ini’)

• use_absolute_path (bool) – Use absolute paths in configs (True) or relative paths (False)

• cosmo_spec (firecrown.app.analysis._types.CCLCosmologySpec) – Cosmology specification with parameters and priors

• required_cosmology (firecrown.app.analysis._types.FrameworkCosmology) – Level of cosmology computation (none/background/linear/nonlinear)

Returns:

Initialized configuration generator ready for component addition

Raises:

ValueError – If framework is not supported

Return type:

firecrown.app.analysis._types.ConfigGenerator

firecrown.app.analysis.download_from_url(url, output_file, console, description='Downloading...')

Download file from URL with caching and progress indicator.

This function implements a caching mechanism to avoid redundant downloads:

1. Checks if the file exists in $HOME/.firecrown/sacc_files cache

2. If cached, copies from cache to output location

3. If not cached, attempts to download from URL

4. On successful download, saves to both cache and output location

5. If download fails, provides helpful instructions for manual placement

This significantly improves performance in testing scenarios and handles offline usage gracefully.

Parameters:

• url (str) – URL to download from

• output_file (pathlib.Path) – Path where file will be saved

• console (rich.console.Console) – Rich console for output

• description (str) – Progress description text

Raises:

SystemExit – If download fails and file is not in cache

Return type:

None

firecrown.app.analysis.copy_template(template_module, output_file)

Copy template module file to output location.

Parameters:

• template_module (types.ModuleType) – Python module to copy

• output_file (pathlib.Path) – Destination path

Return type:

None

class firecrown.app.analysis.CosmosisConfigGenerator

Bases: firecrown.app.analysis._types.ConfigGenerator

CosmoSIS configuration generator.

Generates CosmoSIS INI files for parameter estimation: - cosmosis_{prefix}.ini: Pipeline configuration with modules and settings - cosmosis_{prefix}_values.ini: Parameter values and sampling bounds - cosmosis_{prefix}_priors.ini: Prior specifications (if priors defined)

framework

write_config()

Write CosmoSIS configuration.

Return type:

None

class firecrown.app.analysis.NumCosmoConfigGenerator

Bases: firecrown.app.analysis._types.ConfigGenerator

NumCosmo configuration generator.

Generates NumCosmo YAML files for parameter estimation:

• numcosmo_{prefix}.yaml: Experiment configuration with cosmology, dataset, likelihood, and priors

• numcosmo_{prefix}.builders.yaml: Model builder definitions for systematic/nuisance parameters

Configuration is written in a fresh subprocess to avoid GType conflicts.

framework

write_config()

Write NumCosmo configuration in a fresh subprocess (safe for GType).

Return type:

None

class firecrown.app.analysis.CobayaConfigGenerator

Bases: firecrown.app.analysis._types.ConfigGenerator

Cobaya configuration generator.

Generates a single YAML file for Cobaya parameter estimation:

• cobaya_{prefix}.yaml: Complete configuration with theory (CAMB), likelihood (Firecrown), parameters, and sampler settings

framework

write_config()

Write Cobaya configuration.

Return type:

None