Skip to content

Chain Analysis

See Chain Analysis for the command-line interface and the tutorial for a worked example.

cmb_lensing.chain_analysis.main

main(chain_dir, nside=DEFAULT_NSIDE, theta_pix=DEFAULT_THETA_PIX, noise=DEFAULT_NOISE, pol=DEFAULT_POL, burn_in=DEFAULT_BURN_IN, ground_truth=GROUND_TRUTH, should_thin=True, out_dir=None, run_fisher=False, delensed_covariance=None, qe_filter=DEFAULT_QE_FILTER, phi_noise=None, include_bb=True, camb_lmax=CAMB_LMAX)

Analyse a directory of LCDM chains: the MCMC plots and, optionally, the comparison with a Fisher forecast.

Parameters:

Name Type Description Default
chain_dir

directory of sample_joint's history files, <param>_map_<seed>_chain_<index>_history.txt; the sampled parameters, maps and sub-chains are read off the file names

required
nside, theta_pix, noise

the box the chains ran on (pixels per side, arcmin, uK-arcmin); they label the triangle plot and set the forecast's box

required
pol

"I", "P" or "IP", the data the chains saw; it labels the triangle plot and is the data the forecast models

DEFAULT_POL
burn_in

sweeps removed from the start of every sub-chain

DEFAULT_BURN_IN
ground_truth

{param_name: value} the maps were simulated at (all five parameters)

GROUND_TRUTH
should_thin

thin each sub-chain by its integrated autocorrelation time before the per-parameter plots (the covariance always uses the unthinned chains)

True
out_dir

where the plots go (default <chain_dir>/chain_analysis_output)

None
run_fisher

also run the Fisher forecast for data of this pol and compare it with the chains. Needs delensed_covariance

False
delensed_covariance

a merged delensed_covariance.npz measured at this box, noise level and pol: the forecast's field blocks

None
qe_filter

"unlensed" (default) or "lensed": the spectra in the filter of the QE N0 the forecast uses as its phi noise (the response is always unlensed)

DEFAULT_QE_FILTER
phi_noise

a merged map_joint_phi_noise.npz / sampler_phi_noise.npz whose nphi replaces the QE N0

None
include_bb

for "P" / "IP" chains, whether the forecast counts the delensed BB block

True
camb_lmax

how far the forecast runs CAMB

CAMB_LMAX

Returns:

Type Description

A dict: param_names, map_seeds, chains (load_chains' output), summaries

(per parameter: the product mean / std / z-score with their errors, the average

single-map std, R-hat per map and the acceptance rate), measured_covariance with

measured_covariance_error and measured_sigma_error (delete-one-map jackknife),

forecast_covariance (None without run_fisher) and out_dir.

Source code in cmb_lensing/chain_analysis.py
def main(chain_dir, nside = DEFAULT_NSIDE, theta_pix = DEFAULT_THETA_PIX, noise = DEFAULT_NOISE,
         pol = DEFAULT_POL, burn_in = DEFAULT_BURN_IN,
         ground_truth = GROUND_TRUTH, should_thin = True, out_dir = None, run_fisher = False,
         delensed_covariance = None, qe_filter = DEFAULT_QE_FILTER, phi_noise = None,
         include_bb = True, camb_lmax = CAMB_LMAX):
    """Analyse a directory of LCDM chains: the MCMC plots and, optionally, the comparison
    with a Fisher forecast.

    Args:
        chain_dir:  directory of sample_joint's history files,
                    `<param>_map_<seed>_chain_<index>_history.txt`; the sampled parameters,
                    maps and sub-chains are read off the file names
        nside, theta_pix, noise: the box the chains ran on (pixels per side, arcmin,
                    uK-arcmin); they label the triangle plot and set the forecast's box
        pol:        "I", "P" or "IP", the data the chains saw; it labels the triangle plot
                    and is the data the forecast models
        burn_in:    sweeps removed from the start of every sub-chain
        ground_truth: {param_name: value} the maps were simulated at (all five parameters)
        should_thin: thin each sub-chain by its integrated autocorrelation time before the
                    per-parameter plots (the covariance always uses the unthinned chains)
        out_dir:    where the plots go (default `<chain_dir>/chain_analysis_output`)
        run_fisher: also run the Fisher forecast for data of this `pol` and compare it with
                    the chains. Needs `delensed_covariance`
        delensed_covariance: a merged delensed_covariance.npz measured at this box, noise
                    level and `pol`: the forecast's field blocks
        qe_filter:  "unlensed" (default) or "lensed": the spectra in the filter of the QE N0
                    the forecast uses as its phi noise (the response is always unlensed)
        phi_noise:  a merged map_joint_phi_noise.npz / sampler_phi_noise.npz whose `nphi`
                    replaces the QE N0
        include_bb: for "P" / "IP" chains, whether the forecast counts the delensed BB block
        camb_lmax:  how far the forecast runs CAMB

    Returns:
        A dict: `param_names`, `map_seeds`, `chains` (load_chains' output), `summaries`
        (per parameter: the product mean / std / z-score with their errors, the average
        single-map std, R-hat per map and the acceptance rate), `measured_covariance` with
        `measured_covariance_error` and `measured_sigma_error` (delete-one-map jackknife),
        `forecast_covariance` (None without run_fisher) and `out_dir`.
    """
    #checked before the chains are analysed, not minutes later inside the forecast
    if run_fisher and delensed_covariance is None:
        raise ValueError("run_fisher needs delensed_covariance, a merged "
                         "delensed_covariance.npz: there is no analytic delensing fallback")

    if out_dir is None:
        out_dir = os.path.join(chain_dir, OUTPUT_DIR_NAME)
    joint_dir = os.path.join(out_dir, JOINT_DIR_NAME)
    os.makedirs(joint_dir, exist_ok = True)

    chains, map_seeds = load_chains(chain_dir, burn_in)
    param_names = list(chains.keys())
    summaries = {}
    for name in param_names:
        summaries[name] = per_param_analysis(chains[name], ground_truth[name], name,
                                             os.path.join(out_dir, name.lower()), should_thin)
    plot_z_score_table(summaries, ground_truth, joint_dir)

    forecast_cov_mat = None
    forecast_name = ""
    if run_fisher:
        forecast_cov_mat = get_forecasted_covariance(nside, theta_pix, noise, param_names,
                                                     delensed_covariance, pol = pol,
                                                     qe_filter = qe_filter,
                                                     phi_noise = phi_noise,
                                                     include_bb = include_bb,
                                                     ground_truth = ground_truth,
                                                     camb_lmax = camb_lmax)
        forecast_name = forecast_title(delensed_covariance, qe_filter, phi_noise)
    measured_cov_mat, measured_cov_sigma, measured_sigma_err = joint_param_analysis(
        chains, joint_dir, forecast_cov_mat = forecast_cov_mat, forecast_name = forecast_name,
        nside = nside, theta_pix = theta_pix, noise = noise, pol = pol)
    print(f"\nPlots written to {out_dir}")

    return {"param_names": param_names, "map_seeds": map_seeds, "chains": chains,
            "summaries": summaries, "measured_covariance": measured_cov_mat,
            "measured_covariance_error": measured_cov_sigma,
            "measured_sigma_error": measured_sigma_err,
            "forecast_covariance": forecast_cov_mat, "out_dir": out_dir}

cmb_lensing.chain_analysis.load_chains

load_chains(chain_dir, burn_in=DEFAULT_BURN_IN)

Read every post-burn-in sub-chain in a directory of sample_joint history files.

A sub-chain is kept when every parameter has its file. Its files are cut to their common length (they differ by a sweep when copied from a running job) BEFORE the burn-in is removed, so row k of every parameter is the same sweep; a sub-chain no longer than the burn-in is left out, and so is a map with no sub-chain left.

Parameters:

Name Type Description Default
chain_dir

directory holding <param>_map_<seed>_chain_<index>_history.txt files

required
burn_in

sweeps removed from the start of every sub-chain

DEFAULT_BURN_IN

Returns:

Type Description

(chains, map_seeds) - chains[param][map][sub_chain] is a 1D array for every

GROUND_TRUTH parameter with files, in GROUND_TRUTH's order, with maps and sub-chains

in the same order for every parameter; map_seeds lists the kept maps.

Source code in cmb_lensing/chain_analysis.py
def load_chains(chain_dir, burn_in = DEFAULT_BURN_IN):
    """Read every post-burn-in sub-chain in a directory of sample_joint history files.

    A sub-chain is kept when every parameter has its file. Its files are cut to their common
    length (they differ by a sweep when copied from a running job) BEFORE the burn-in is
    removed, so row k of every parameter is the same sweep; a sub-chain no longer than the
    burn-in is left out, and so is a map with no sub-chain left.

    Args:
        chain_dir: directory holding `<param>_map_<seed>_chain_<index>_history.txt` files
        burn_in:   sweeps removed from the start of every sub-chain

    Returns:
        (chains, map_seeds) - `chains[param][map][sub_chain]` is a 1D array for every
        GROUND_TRUTH parameter with files, in GROUND_TRUTH's order, with maps and sub-chains
        in the same order for every parameter; map_seeds lists the kept maps.
    """
    files = find_history_files(chain_dir)
    #every sampled parameter, in GROUND_TRUTH's (= PARAM_ORDER's) order
    params = [name for name in GROUND_TRUTH if name in files]
    shared_keys = sorted(set.intersection(*[set(files[name]) for name in params]))

    chains = {name: [] for name in params}
    map_seeds = []
    num_discarded = 0
    for map_seed in sorted({key[0] for key in shared_keys}):
        sub_chains = {name: [] for name in params}
        for key in [key for key in shared_keys if key[0] == map_seed]:
            histories = [np.atleast_1d(np.loadtxt(files[name][key])) for name in params]
            common_length = min(len(history) for history in histories)
            if common_length <= burn_in:
                num_discarded += 1
                continue
            for name, history in zip(params, histories):
                sub_chains[name].append(history[burn_in:common_length])
        if len(sub_chains[params[0]]) > 0:
            map_seeds.append(map_seed)
            for name in params:
                chains[name].append(sub_chains[name])
    print(f"Loaded {sum(len(sub_chains) for sub_chains in chains[params[0]])} sub-chains of "
          f"{len(map_seeds)} maps for {params}; discarded {num_discarded} no longer than the "
          f"burn-in of {burn_in}")
    return chains, map_seeds

cmb_lensing.chain_analysis.get_avg_covariance_matrix

get_avg_covariance_matrix(chains)

Map-averaged posterior covariance of the sampled parameters, with its jackknife error.

chains is load_chains' dict, whose sub-chains line up row by row across parameters. Each map's sub-chains are concatenated and give one covariance matrix, and those are averaged over maps. Samples from different maps are never pooled: each map is a different data realization with its own posterior mean, so pooling would add the scatter of those means to the diagonal. The average is a single-realization posterior, which is what a Fisher forecast predicts.

Returns:

Type Description

(avg_cov_mat, param_names, cov_err, sigma_err), the last two from measured_errors:

the element-wise error of the averaged covariance and the error of each width

sqrt(C_ii).

Source code in cmb_lensing/chain_analysis.py
def get_avg_covariance_matrix(chains):
    """Map-averaged posterior covariance of the sampled parameters, with its jackknife error.

    `chains` is load_chains' dict, whose sub-chains line up row by row across parameters.
    Each map's sub-chains are concatenated and give one covariance matrix, and those are
    averaged over maps. Samples from different maps are never pooled: each map is a
    different data realization with its own posterior mean, so pooling would add the scatter
    of those means to the diagonal. The average is a single-realization posterior, which is
    what a Fisher forecast predicts.

    Returns:
        (avg_cov_mat, param_names, cov_err, sigma_err), the last two from measured_errors:
        the element-wise error of the averaged covariance and the error of each width
        sqrt(C_ii).
    """
    param_names = list(chains.keys())
    num_maps = len(chains[param_names[0]])
    per_map_cov_mats = []
    for map_idx in range(num_maps):
        columns = [np.concatenate(chains[name][map_idx]) for name in param_names]
        per_map_cov_mats.append(np.atleast_2d(np.cov(np.column_stack(columns), rowvar = False)))
    per_map_cov_mats = np.array(per_map_cov_mats)
    cov_err, sigma_err = measured_errors(per_map_cov_mats)
    return np.mean(per_map_cov_mats, axis = 0), param_names, cov_err, sigma_err

cmb_lensing.chain_analysis.get_forecasted_covariance

get_forecasted_covariance(nside, theta_pix, noise, param_names, delensed_covariance, pol=DEFAULT_POL, qe_filter=DEFAULT_QE_FILTER, phi_noise=None, include_bb=True, ground_truth=GROUND_TRUTH, camb_lmax=CAMB_LMAX)

Fisher-forecast covariance of the sampled parameters, with white noise and no beam.

A thin wrapper of fisher_forecast.forecast. Its field blocks are the empirical delensed covariance of delensed_covariance (plus the analytic noise); its phi block's noise is the box QE N0 or a measured matrix. Build the delensed covariance's Wiener filter from the same N_phi.

Parameters:

Name Type Description Default
nside, theta_pix, noise

the chains' box (pixels per side, arcmin, uK-arcmin)

required
param_names

the sampled parameters; the others are held fixed

required
delensed_covariance

a merged delensed_covariance.npz at this box, noise level and pol (required)

required
pol

"I", "P" or "IP": the data the chains saw

DEFAULT_POL
qe_filter

"unlensed" (default) or "lensed": the spectra in the QE N0's filter. The response always uses the unlensed spectra

DEFAULT_QE_FILTER
phi_noise

a merged map_joint_phi_noise.npz / sampler_phi_noise.npz; its nphi then replaces the QE N0

None
include_bb

for "P" / "IP", whether the delensed BB block is counted

True
ground_truth

{param_name: value}, the fiducial point, all five parameters

GROUND_TRUTH
camb_lmax

how far CAMB is run

CAMB_LMAX

Returns:

Type Description

The covariance matrix F^-1 over param_names, rows and columns in

constants.PARAM_ORDER (the order load_chains returns its parameters in).

Source code in cmb_lensing/chain_analysis.py
def get_forecasted_covariance(nside, theta_pix, noise, param_names, delensed_covariance,
                              pol = DEFAULT_POL, qe_filter = DEFAULT_QE_FILTER,
                              phi_noise = None, include_bb = True, ground_truth = GROUND_TRUTH,
                              camb_lmax = CAMB_LMAX):
    """Fisher-forecast covariance of the sampled parameters, with white noise and no beam.

    A thin wrapper of fisher_forecast.forecast. Its field blocks are the empirical delensed
    covariance of `delensed_covariance` (plus the analytic noise); its phi block's noise is
    the box QE N0 or a measured matrix. Build the delensed covariance's Wiener filter from
    the same N_phi.

    Args:
        nside, theta_pix, noise: the chains' box (pixels per side, arcmin, uK-arcmin)
        param_names:         the sampled parameters; the others are held fixed
        delensed_covariance: a merged delensed_covariance.npz at this box, noise level and
                             `pol` (required)
        pol:                 "I", "P" or "IP": the data the chains saw
        qe_filter:           "unlensed" (default) or "lensed": the spectra in the QE N0's
                             filter. The response always uses the unlensed spectra
        phi_noise:           a merged map_joint_phi_noise.npz / sampler_phi_noise.npz; its
                             `nphi` then replaces the QE N0
        include_bb:          for "P" / "IP", whether the delensed BB block is counted
        ground_truth:        {param_name: value}, the fiducial point, all five parameters
        camb_lmax:           how far CAMB is run

    Returns:
        The covariance matrix F^-1 over param_names, rows and columns in
        constants.PARAM_ORDER (the order load_chains returns its parameters in).
    """
    is_sampled = {name: name in param_names for name in ground_truth}
    fisher, names = forecast(nside, theta_pix, noise, is_sampled, ground_truth,
                             delensed_covariance, pol = pol, qe_filter = qe_filter,
                             phi_noise = phi_noise, include_bb = include_bb,
                             camb_lmax = camb_lmax)
    return covariance_from_fisher(fisher, names)