bayspec.data package

Submodules

bayspec.data.data module

Container types that pair spectra with responses and binning policy.

A DataUnit bundles one source spectrum with its background, response (RMF/ARF or combined), statistic choice, channel noticing, grouping, optional rebinning, and time tag. A Data holds an ordered collection of DataUnit instances and exposes aggregated views of their counts, count rates, binned spectra, and responses, which the inference layer consumes.

Many Data properties are thin aggregators that broadcast the identically-named property over every contained DataUnit – consult the DataUnit property of the same name for the underlying formula.

class bayspec.data.data.Data(data=None)

Bases: object

Ordered collection of DataUnit objects.

Indexing with a key returns the stored DataUnit; assignment re-runs the aggregate update so cached views stay consistent.

Group docstring for aggregator properties. Every list-valued property on this class is the per-unit concatenation of the same-named property on DataUnit; for the formulas, read the unit-level property. The family covers these naming patterns (the _re_ infix uses the re-binned channel grid; the _error suffix returns 1-sigma uncertainties; the _f64 suffix forces float64):

• ebin, ewidth, nbin, tarr, ngrid, egrid, tgrid, bin_start, bin_stop;

• src_efficiency, bkg_efficiency, alpha;

• src_counts / src_counts_f64 / src_re_counts / src_errors / src_errors_f64 / src_re_errors;

• bkg_counts / bkg_counts_f64 / bkg_re_counts / bkg_errors / bkg_errors_f64 / bkg_re_errors;

• rsp_chbin, rsp_re_chbin, rsp_chbin_mean, rsp_re_chbin_mean, rsp_chbin_width, rsp_re_chbin_width, rsp_chbin_tarr, rsp_re_chbin_tarr;

• rsp_drm, rsp_re_drm, corr_rsp_drm, corr_rsp_re_drm, corr_src_efficiency/_f64, corr_bkg_efficiency/_f64;

• src_ctsrate/_error, src_ctsspec/_error and their _re_ variants; matching bkg_* and net_* families;

• npoints.

deconv_{pht,flx,erg}spec/_error and their _re_ variants are described on deconv_phtspec.

Variables:

• data – OrderedDict mapping names to DataUnit instances.

• names – Names of every unit in insertion order.

• srcs/bkgs/rsps – Per-unit Source/Background/Response.

• stats/notcs/grpgs/rebns/times/weights – Per-unit metadata lists.

• cdicts/pdicts – Per-unit config/parameter dictionaries.

property data

property cfg

Flat SuperDict of every config parameter across all units.

property par

Flat SuperDict of every free/fixed parameter across all units.

property pvalues

Tuple of current parameter values, preserving par order.

property all_config

List of per-config rows with component, label, and value.

property all_params

List of per-parameter rows with value, prior, posterior, and frozen flag.

property cfg_info

Tabular Info view of every configuration parameter.

property par_info

Tabular Info view of parameters, posterior column dropped.

property info

Tabular Info view of per-unit noticing, statistic, and time.

save(savepath)

Dump the per-unit info table to <savepath>/data.json.

Parameters:

savepath – Directory path. Created if missing.

property fit_with

Return the Model this data is bound to, or raise if unset.

Raises:

AttributeError – If no model has been assigned.

property ebin

property ewidth

property nbin

property bin_start

property bin_stop

property tarr

property ngrid

property egrid

property tgrid

property src_efficiency

property bkg_efficiency

property alpha

property src_counts

property src_counts_f64

property src_re_counts

property src_errors

property src_errors_f64

property src_re_errors

property bkg_counts

property bkg_counts_f64

property bkg_re_counts

property bkg_errors

property bkg_errors_f64

property bkg_re_errors

property rsp_chbin

property rsp_re_chbin

property rsp_chbin_mean

property rsp_re_chbin_mean

property rsp_chbin_width

property rsp_re_chbin_width

property rsp_chbin_tarr

property rsp_re_chbin_tarr

property rsp_drm

property rsp_re_drm

property corr_rsp_drm

property corr_rsp_re_drm

property corr_src_efficiency

property corr_src_efficiency_f64

property corr_bkg_efficiency

property corr_bkg_efficiency_f64

property src_ctsrate

property src_re_ctsrate

property src_ctsrate_error

property src_re_ctsrate_error

property src_ctsspec

property src_re_ctsspec

property src_ctsspec_error

property src_re_ctsspec_error

property bkg_ctsrate

property bkg_re_ctsrate

property bkg_ctsrate_error

property bkg_re_ctsrate_error

property bkg_ctsspec

property bkg_re_ctsspec

property bkg_ctsspec_error

property bkg_re_ctsspec_error

property net_ctsrate

property net_re_ctsrate

property net_ctsrate_error

property net_re_ctsrate_error

property net_ctsspec

property net_re_ctsspec

property net_ctsspec_error

property net_re_ctsspec_error

property npoints

net_counts_upperlimit(cl=0.9)

Per-unit net-counts upper limit at confidence level cl.

Parameters:

cl – Target confidence level in (0, 1).

Returns:

List of per-unit upper limits.

net_ctsrate_upperlimit(cl=0.9)

Per-unit net-count-rate upper limit at confidence level cl.

property deconv_phtspec

net counts × model cts_to_pht.

Each deconvolved-spectrum property (deconv_phtspec, deconv_flxspec, deconv_ergspec, their _error and _re_ variants) multiplies per-unit net counts by the conversion factor published by the bound model.

Type:

Deconvolved photon spectrum

property deconv_re_phtspec

property deconv_phtspec_error

property deconv_re_phtspec_error

property deconv_flxspec

property deconv_re_flxspec

property deconv_flxspec_error

property deconv_re_flxspec_error

property deconv_ergspec

property deconv_re_ergspec

property deconv_ergspec_error

property deconv_re_ergspec_error

property expr

Best-effort identifier for this container inferred from caller scope.

get_obj_name()

Walk call frames and return the outermost local name bound to self.

Returns None if no binding is found.

class bayspec.data.data.DataUnit(src, bkg=None, rmf=None, arf=None, rsp=None, stat='pgstat', notc=None, grpg=None, rebn=None, time=None, weight=1)

Bases: object

One source/background/response triplet with binning and statistic.

Each of the constructor’s src/bkg/rmf/arf/rsp slots accepts either an already-constructed domain object (Source, Background, Redistribution, Auxiliary, Response) or a file handle. File handles may be a path string, a BytesIO, or a (file, index) tuple for multi-row PHA2/RSP2/ARF2 archives.

Changing any public attribute re-runs _update(), which rebuilds noticing, grouping, rebinning, and invalidates cached views.

Group docstring for computed properties. One-line computed properties are either trivial passes to an underlying object or a direct numerical shortcut; read the member for the formula. The _re_ infix toggles between the grouping-based grid and the rebinning-based grid. The family covers:

• ebin, ewidth, nbin, tarr, ngrid, egrid, tgrid – energy/time grids used by the model convolution;

• src_efficiency, bkg_efficiency, alpha – exposure and backscale combinations;

• src_counts/_re_ and src_errors/_re_, matching bkg_counts/bkg_errors – grouping-aggregated counts/errors;

• rsp_chbin/_re_, their _mean/_width/_tarr – channel-bin views of the response;

• rsp_drm/_re_ plus corr_rsp_drm/_re_ – response matrices (corr_ applies the rsp factor);

• corr_src_efficiency/corr_bkg_efficiency – efficiencies multiplied by the relevant Par factor;

• src_ctsrate/_error and src_ctsspec/_error plus their _re_ variants; matching bkg_* and net_* families.

Variables:

• rsp_ins (src_ins, bkg_ins, rmf_ins, arf_ins,) – Concrete loaded spectrum/response objects.

• qualifying/noticing/grouping/rebining – Per-channel flag arrays driving grouping_slice/rebining_slice.

• config/params – Per-unit config and fit parameters.

property src

property bkg

property rmf

property arf

property rsp

property completeness

True when both source and response are populated.

property stat

property notc

property grpg

property rebn

property time

property weight

property cfg

SuperDict indexed view of this unit’s config parameters.

property par

SuperDict indexed view of this unit’s fit parameters.

property pvalues

Tuple of current parameter values, preserving par order.

property info

Tabular Info view of the unit’s file names and settings.

save(savepath)

Dump the unit’s info table to <savepath>/dataunit.json.

Parameters:

savepath – Directory path. Created if missing.

property ebin

property ewidth

property nbin

property tarr

property ngrid

property egrid

property tgrid

property src_efficiency

property bkg_efficiency

property alpha

property src_counts

property src_re_counts

property src_errors

property src_re_errors

property bkg_counts

property bkg_re_counts

property bkg_errors

property bkg_re_errors

property rsp_chbin

property rsp_re_chbin

property rsp_chbin_mean

property rsp_re_chbin_mean

property rsp_chbin_width

property rsp_re_chbin_width

property rsp_chbin_tarr

property rsp_re_chbin_tarr

property rsp_drm

property rsp_re_drm

property corr_rsp_drm

property corr_rsp_re_drm

property corr_src_efficiency

property corr_bkg_efficiency

property src_ctsrate

property src_re_ctsrate

property src_ctsrate_error

property src_re_ctsrate_error

property src_ctsspec

property src_re_ctsspec

property src_ctsspec_error

property src_re_ctsspec_error

property bkg_ctsrate

property bkg_re_ctsrate

property bkg_ctsrate_error

property bkg_re_ctsrate_error

property bkg_ctsspec

property bkg_re_ctsspec

property bkg_ctsspec_error

property bkg_re_ctsspec_error

property net_ctsrate

property net_re_ctsrate

property net_ctsrate_error

property net_re_ctsrate_error

property net_ctsspec

property net_re_ctsspec

property net_ctsspec_error

property net_re_ctsspec_error

property npoint

net_counts_upperlimit(cl=0.9)

Return the Bayesian net-counts upper limit at confidence cl.

Uses the Poisson formulation with the incomplete gamma function inverse; alpha accounts for the source/background exposure ratio.

Parameters:

cl – Target confidence level in (0, 1).

Returns:

Upper limit on the net counts.

net_ctsrate_upperlimit(cl=0.9)

Return the net-count-rate upper limit at confidence cl.

property name

User-assigned name if set, otherwise a best-effort caller-scope name.

get_obj_name()

Walk call frames and return the outermost local name bound to self.

Returns None if no binding is found.

bayspec.data.response module

Detector response containers: full DRM, pure redistribution, and ARF.

Provides the base Response (channel × photon redistribution matrix), Redistribution (RMF only), Auxiliary (ARF only), and the location-driven BalrogResponse used for Fermi/GBM localization-dependent responses. Redistribution * Auxiliary composes into a full Response.

class bayspec.data.response.Response(chbin, phbin, drm, ra=None, dec=None, factor=None)

Bases: object

Full detector response: channel bins, photon bins, and DRM.

Variables:

• chbin – (nchan, 2) array of channel energy bin edges.

• phbin – (nphot, 2) array of photon energy bin edges.

• drm – (nphot, nchan) detector redistribution matrix.

• ra – Optional right-ascension Par.

• dec – Optional declination Par.

• factor – Multiplicative Par applied during convolution.

classmethod from_rsp(rsp_file)

Load a single-extension OGIP RSP/RMF file.

Supports both SPECRESP MATRIX and legacy MATRIX extension names. Handles both variable-length (P-form) and fixed-length FCHAN/NCHAN columns.

Parameters:

rsp_file – Path to the FITS file, or a BytesIO.

Returns:

A new Response instance.

Raises:

ValueError – If rsp_file is neither a string nor BytesIO.

classmethod from_rsp2(rsp_file, ii=None)

Load extension ii of a multi-extension RSP2 file.

Accepts the row index via ii or via "path:ii".

Parameters:

• rsp_file – Path or BytesIO to the RSP2 file.

• ii – Extension index within SPECRESP MATRIX/MATRIX.

Returns:

A new Response instance.

Raises:

• ValueError – If rsp_file is neither a string nor BytesIO.

• AssertionError – If ii is not an int when required.

classmethod from_plain(rsp_file, ii=None)

Dispatch to from_rsp or from_rsp2 based on rsp_file form.

Parameters:

• rsp_file – Path (optionally "path:ii") or BytesIO.

• ii – Extension index; forces the RSP2 loader when given.

Returns:

A new Response instance.

classmethod from_rmf_arf(rmf, arf)

Compose a full response from a redistribution matrix and ARF.

Parameters:

• rmf – A Redistribution-like object carrying chbin, phbin, and drm.

• arf – An Auxiliary-like object carrying srp.

Returns:

A new Response whose DRM is rmf.drm * arf.srp.

Raises:

ValueError – If the photon-bin dimensions disagree.

property chbin

property phbin

property drm

property ra

property dec

property factor

property chbin_mean

Per-channel midpoint energy, computed from chbin.

property chbin_width

Per-channel bin width, computed from chbin.

property info

Return a tabular Info summary of bin counts.

property name

Best-effort identifier inferred from the caller scope.

get_obj_name()

Walk call frames and return the outermost local name bound to self.

Returns None if no binding is found.

class bayspec.data.response.DisableMethodsMeta(name, bases, dct)

Bases: type

Metaclass that hides inherited methods listed in methods_to_disable.

Each named method is replaced by a shim that raises AttributeError, so the class still advertises the inherited API surface but callers are told the method does not apply to this subclass.

static disable_method(method_name)

Return a function that raises AttributeError for method_name.

class bayspec.data.response.BalrogResponse(balrog_drm, ra=None, dec=None, factor=None)

Bases: Response

Location-driven Fermi/GBM response backed by a balrog DRM.

Recomputes the response matrix whenever ra or dec change. The file-based factory methods inherited from Response are disabled since the DRM is produced by the balrog provider.

methods_to_disable = ('from_rsp', 'from_rsp2', 'from_plain', 'from_rmf_arf')

property balrog_drm

property chbin

Channel bins derived from the balrog ebounds array.

property phbin

Photon bins derived from monte_carlo_energies.

property drm

Response matrix at the current (ra, dec); NaNs are coerced to 0.

from_plain(**kwargs)

Dispatch to from_rsp or from_rsp2 based on rsp_file form.

Parameters:

• rsp_file – Path (optionally "path:ii") or BytesIO.

• ii – Extension index; forces the RSP2 loader when given.

Returns:

A new Response instance.

from_rmf_arf(**kwargs)

Compose a full response from a redistribution matrix and ARF.

Parameters:

• rmf – A Redistribution-like object carrying chbin, phbin, and drm.

• arf – An Auxiliary-like object carrying srp.

Returns:

A new Response whose DRM is rmf.drm * arf.srp.

Raises:

ValueError – If the photon-bin dimensions disagree.

from_rsp(**kwargs)

Load a single-extension OGIP RSP/RMF file.

Supports both SPECRESP MATRIX and legacy MATRIX extension names. Handles both variable-length (P-form) and fixed-length FCHAN/NCHAN columns.

Parameters:

rsp_file – Path to the FITS file, or a BytesIO.

Returns:

A new Response instance.

Raises:

ValueError – If rsp_file is neither a string nor BytesIO.

from_rsp2(**kwargs)

Load extension ii of a multi-extension RSP2 file.

Accepts the row index via ii or via "path:ii".

Parameters:

• rsp_file – Path or BytesIO to the RSP2 file.

• ii – Extension index within SPECRESP MATRIX/MATRIX.

Returns:

A new Response instance.

Raises:

• ValueError – If rsp_file is neither a string nor BytesIO.

• AssertionError – If ii is not an int when required.

class bayspec.data.response.Redistribution(chbin, phbin, drm)

Bases: Response

Pure redistribution matrix (RMF); combines with Auxiliary via *.

methods_to_disable = ('from_rmf_arf',)

classmethod from_rmf(rmf_file)

Alias for Response.from_rsp() that returns an RMF.

classmethod from_rmf2(rmf_file, ii=None)

Alias for Response.from_rsp2() that returns an RMF.

classmethod from_plain(rmf_file, ii=None)

Dispatch to from_rmf or from_rmf2 based on rmf_file form.

property info

Return a tabular Info summary labelled as a redistribution.

from_rmf_arf(**kwargs)

Compose a full response from a redistribution matrix and ARF.

Parameters:

• rmf – A Redistribution-like object carrying chbin, phbin, and drm.

• arf – An Auxiliary-like object carrying srp.

Returns:

A new Response whose DRM is rmf.drm * arf.srp.

Raises:

ValueError – If the photon-bin dimensions disagree.

class bayspec.data.response.Auxiliary(phbin, srp)

Bases: Response

Auxiliary response (ARF): effective area per photon bin.

Variables:

• phbin – (nphot, 2) array of photon energy bin edges.

• srp – 1D array of effective-area values aligned with phbin.

methods_to_disable = ('from_rsp', 'from_rsp2', 'from_rmf_arf')

property srp

classmethod from_arf(arf_file)

Load a single-extension OGIP ARF file.

Parameters:

arf_file – Path to the ARF FITS file, or a BytesIO.

Returns:

A new Auxiliary instance.

Raises:

ValueError – If arf_file is neither a string nor BytesIO.

classmethod from_arf2(arf_file, ii=None)

Load extension ii of a multi-extension ARF2 file.

Parameters:

• arf_file – Path or BytesIO to the ARF2 file; may use the "path:ii" convention.

• ii – Extension index within SPECRESP.

Returns:

A new Auxiliary instance.

classmethod from_plain(arf_file, ii=None)

Dispatch to from_arf or from_arf2 based on arf_file form.

from_rmf_arf(**kwargs)

Compose a full response from a redistribution matrix and ARF.

Parameters:

• rmf – A Redistribution-like object carrying chbin, phbin, and drm.

• arf – An Auxiliary-like object carrying srp.

Returns:

A new Response whose DRM is rmf.drm * arf.srp.

Raises:

ValueError – If the photon-bin dimensions disagree.

from_rsp(**kwargs)

Load a single-extension OGIP RSP/RMF file.

Supports both SPECRESP MATRIX and legacy MATRIX extension names. Handles both variable-length (P-form) and fixed-length FCHAN/NCHAN columns.

Parameters:

rsp_file – Path to the FITS file, or a BytesIO.

Returns:

A new Response instance.

Raises:

ValueError – If rsp_file is neither a string nor BytesIO.

from_rsp2(**kwargs)

Load extension ii of a multi-extension RSP2 file.

Accepts the row index via ii or via "path:ii".

Parameters:

• rsp_file – Path or BytesIO to the RSP2 file.

• ii – Extension index within SPECRESP MATRIX/MATRIX.

Returns:

A new Response instance.

Raises:

• ValueError – If rsp_file is neither a string nor BytesIO.

• AssertionError – If ii is not an int when required.

property info

Return a tabular Info summary labelled as an auxiliary.

bayspec.data.spectrum module

OGIP-style spectrum containers for source and background observations.

class bayspec.data.spectrum.Spectrum(counts, errors, exposure, quality=None, grouping=None, backscale=1.0, factor=None)

Bases: object

Channel-binned spectrum with exposure, quality, and scaling metadata.

The object holds raw per-channel counts and errors, the observing exposure, optional quality and grouping flags, the backscale, and a multiplicative scaling parameter used during fitting.

Variables:

• counts – Per-channel counts.

• errors – Per-channel uncertainties.

• exposure – Observing exposure in seconds.

• quality – Per-channel quality flags; zero marks good channels.

• grouping – Per-channel OGIP grouping flags.

• backscale – Ratio of source-to-background extraction geometry.

• factor – Par scaling applied during model convolution.

property counts

property errors

property exposure

property quality

property grouping

property backscale

property factor

set_zero()

Zero out both counts and errors in place.

property info

Return a tabular Info summary of name, channels, and counts.

property name

Best-effort identifier for this spectrum inferred from caller scope.

get_obj_name()

Walk call frames and return the outermost local name bound to self.

Used to label spectra by the variable name the user chose. Returns None if no binding is found.

class bayspec.data.spectrum.Source(counts, errors, exposure, quality=None, grouping=None, backscale=1.0, factor=None)

Bases: Spectrum

Source-region spectrum, constructed from OGIP FITS files.

classmethod from_src(src_file)

Load a source spectrum from a single-row OGIP PHA file.

Falls back to RATE if COUNTS is absent, and synthesizes Poisson errors if STAT_ERR is missing.

Parameters:

src_file – Path to the PHA file, or a BytesIO holding its bytes.

Returns:

A new Source instance.

Raises:

ValueError – If src_file is neither a string nor BytesIO.

classmethod from_src2(src_file, ii=None)

Load row ii of a multi-row PHA2 source spectrum.

The row index may be passed explicitly via ii or appended to the path as "file.pha2:ii".

Parameters:

• src_file – Path or BytesIO to the PHA2 file.

• ii – Zero-based row index within the SPECTRUM extension.

Returns:

A new Source instance for the selected row.

Raises:

• ValueError – If src_file is neither a string nor BytesIO.

• AssertionError – If ii is not an int when required.

classmethod from_plain(src_file, ii=None)

Dispatch to from_src or from_src2 based on src_file form.

Parameters:

• src_file – PHA/PHA2 path (optionally "path:ii") or BytesIO.

• ii – Row index; when given, forces the PHA2 loader.

Returns:

A new Source instance.

class bayspec.data.spectrum.Background(counts, errors, exposure, quality=None, grouping=None, backscale=1.0, factor=None)

Bases: Spectrum

Background-region spectrum, constructed from OGIP FITS files.

classmethod from_bkg(bkg_file)

Load a background spectrum from a single-row OGIP PHA file.

Mirrors Source.from_src(); quality and grouping are not read.

Parameters:

bkg_file – Path to the PHA file, or a BytesIO.

Returns:

A new Background instance.

Raises:

ValueError – If bkg_file is neither a string nor BytesIO.

classmethod from_bkg2(bkg_file, ii=None)

Load row ii of a multi-row PHA2 background spectrum.

Mirrors Source.from_src2().

Parameters:

• bkg_file – Path or BytesIO to the PHA2 file; may use the "path:ii" convention.

• ii – Zero-based row index.

Returns:

A new Background instance.

classmethod from_plain(bkg_file, ii=None)

Dispatch to from_bkg or from_bkg2 based on bkg_file form.

Parameters:

• bkg_file – PHA/PHA2 path (optionally "path:ii") or BytesIO.

• ii – Row index; when given, forces the PHA2 loader.

Returns:

A new Background instance.

Module contents

Spectral data containers: spectra, responses, and the unit aggregator.