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)[source]

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.

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 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 alpha
property bin_start
property bin_stop
property bkg_counts
property bkg_counts_f64
property bkg_ctsrate
property bkg_ctsrate_error
property bkg_ctsspec
property bkg_ctsspec_error
property bkg_efficiency
property bkg_errors
property bkg_errors_f64
property bkg_re_counts
property bkg_re_ctsrate
property bkg_re_ctsrate_error
property bkg_re_ctsspec
property bkg_re_ctsspec_error
property bkg_re_errors
property cfg

Flat SuperDict of every config parameter across all units.

property cfg_info

Tabular Info view of every configuration parameter.

property corr_bkg_efficiency
property corr_bkg_efficiency_f64
property corr_rsp_drm
property corr_rsp_re_drm
property corr_src_efficiency
property corr_src_efficiency_f64
property data
property deconv_ergspec
property deconv_ergspec_error
property deconv_flxspec
property deconv_flxspec_error
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_phtspec_error
property deconv_re_ergspec
property deconv_re_ergspec_error
property deconv_re_flxspec
property deconv_re_flxspec_error
property deconv_re_phtspec
property deconv_re_phtspec_error
property ebin
property egrid
property ewidth
property expr

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

property fit_with

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

Raises:

AttributeError – If no model has been assigned.

get_obj_name()[source]

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

Returns None if no binding is found.

property info

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

property nbin
net_counts_upperlimit(cl=0.9)[source]

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.

property net_ctsrate
property net_ctsrate_error
net_ctsrate_upperlimit(cl=0.9)[source]

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

property net_ctsspec
property net_ctsspec_error
property net_re_ctsrate
property net_re_ctsrate_error
property net_re_ctsspec
property net_re_ctsspec_error
property ngrid
property npoints
property par

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

property par_info

Tabular Info view of parameters, posterior column dropped.

property pvalues

Tuple of current parameter values, preserving par order.

property rsp_chbin
property rsp_chbin_mean
property rsp_chbin_tarr
property rsp_chbin_width
property rsp_drm
property rsp_re_chbin
property rsp_re_chbin_mean
property rsp_re_chbin_tarr
property rsp_re_chbin_width
property rsp_re_drm
save(savepath)[source]

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

Parameters:

savepath – Directory path. Created if missing.

property src_counts
property src_counts_f64
property src_ctsrate
property src_ctsrate_error
property src_ctsspec
property src_ctsspec_error
property src_efficiency
property src_errors
property src_errors_f64
property src_re_counts
property src_re_ctsrate
property src_re_ctsrate_error
property src_re_ctsspec
property src_re_ctsspec_error
property src_re_errors
property tarr
property tgrid
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)[source]

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.

src_ins, bkg_ins, rmf_ins, arf_ins, rsp_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 alpha
property arf
property bkg
property bkg_counts
property bkg_ctsrate
property bkg_ctsrate_error
property bkg_ctsspec
property bkg_ctsspec_error
property bkg_efficiency
property bkg_errors
property bkg_re_counts
property bkg_re_ctsrate
property bkg_re_ctsrate_error
property bkg_re_ctsspec
property bkg_re_ctsspec_error
property bkg_re_errors
property cfg

SuperDict indexed view of this unit’s config parameters.

property completeness

True when both source and response are populated.

property corr_bkg_efficiency
property corr_rsp_drm
property corr_rsp_re_drm
property corr_src_efficiency
property ebin
property egrid
property ewidth
get_obj_name()[source]

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

Returns None if no binding is found.

property grpg
property info

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

property name

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

property nbin
net_counts_upperlimit(cl=0.9)[source]

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.

property net_ctsrate
property net_ctsrate_error
net_ctsrate_upperlimit(cl=0.9)[source]

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

property net_ctsspec
property net_ctsspec_error
property net_re_ctsrate
property net_re_ctsrate_error
property net_re_ctsspec
property net_re_ctsspec_error
property ngrid
property notc
property npoint
property par

SuperDict indexed view of this unit’s fit parameters.

property pvalues

Tuple of current parameter values, preserving par order.

property rebn
property rmf
property rsp
property rsp_chbin
property rsp_chbin_mean
property rsp_chbin_tarr
property rsp_chbin_width
property rsp_drm
property rsp_re_chbin
property rsp_re_chbin_mean
property rsp_re_chbin_tarr
property rsp_re_chbin_width
property rsp_re_drm
save(savepath)[source]

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

Parameters:

savepath – Directory path. Created if missing.

property src
property src_counts
property src_ctsrate
property src_ctsrate_error
property src_ctsspec
property src_ctsspec_error
property src_efficiency
property src_errors
property src_re_counts
property src_re_ctsrate
property src_re_ctsrate_error
property src_re_ctsspec
property src_re_ctsspec_error
property src_re_errors
property stat
property tarr
property tgrid
property time
property weight

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.Auxiliary(phbin, srp)[source]

Bases: Response

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

phbin

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

srp

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

classmethod from_arf(arf_file)[source]

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)[source]

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)[source]

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.

methods_to_disable = ('from_rsp', 'from_rsp2', 'from_rmf_arf')
property srp
class bayspec.data.response.BalrogResponse(balrog_drm, ra=None, dec=None, factor=None)[source]

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.

property balrog_drm
property chbin

Channel bins derived from the balrog ebounds array.

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.

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

Photon bins derived from monte_carlo_energies.

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

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)[source]

Return a function that raises AttributeError for method_name.

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

Bases: Response

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

classmethod from_plain(rmf_file, ii=None)[source]

Dispatch to from_rmf or from_rmf2 based on rmf_file form.

classmethod from_rmf(rmf_file)[source]

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

classmethod from_rmf2(rmf_file, ii=None)[source]

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

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.

property info

Return a tabular Info summary labelled as a redistribution.

methods_to_disable = ('from_rmf_arf',)
class bayspec.data.response.Response(chbin, phbin, drm, ra=None, dec=None, factor=None)[source]

Bases: object

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

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.

property chbin
property chbin_mean

Per-channel midpoint energy, computed from chbin.

property chbin_width

Per-channel bin width, computed from chbin.

property dec
property drm
property factor
classmethod from_plain(rsp_file, ii=None)[source]

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)[source]

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.

classmethod from_rsp(rsp_file)[source]

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)[source]

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.

get_obj_name()[source]

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

Returns None if no binding is found.

property info

Return a tabular Info summary of bin counts.

property name

Best-effort identifier inferred from the caller scope.

property phbin
property ra

bayspec.data.spectrum module

OGIP-style spectrum containers for source and background observations.

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

Bases: Spectrum

Background-region spectrum, constructed from OGIP FITS files.

classmethod from_bkg(bkg_file)[source]

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)[source]

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)[source]

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.

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

Bases: Spectrum

Source-region spectrum, constructed from OGIP FITS files.

classmethod from_plain(src_file, ii=None)[source]

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.

classmethod from_src(src_file)[source]

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)[source]

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.

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

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.

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 backscale
property counts
property errors
property exposure
property factor
get_obj_name()[source]

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.

property grouping
property info

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

property name

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

property quality
set_zero()[source]

Zero out both counts and errors in place.

Module contents

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