source - Source Class

Source

The Source class loads and manages time-resolved spectral models for astrophysical transients.

Constructor

Source(
    filepath: str | Path,
    min_energy: u.Quantity | None = None,
    max_energy: u.Quantity | None = None,
    ebl: str | None = None,
    times: list[u.Quantity] | None = None,
    distance: Distance | None = None,
    z: float | None = None,
)

Parameters:

Parameter	Type	Description
filepath	str | Path	Path to spectral model file (CSV, FITS, or directory)
min_energy	u.Quantity | None	Minimum energy for analysis
max_energy	u.Quantity | None	Maximum energy for analysis
ebl	str | None	EBL model name ("franceschini", "dominguez", etc.)
times	list[u.Quantity] | None	Specific times to load (optional)
distance	Distance | None	Distance to source (overrides metadata distance)
z	float | None	Redshift (overrides metadata distance/redshift)

Note: Only one of distance or z can be provided, not both.

Example:

from sensipy.source import Source
from sensipy.util import get_data_path
from astropy import units as u
from astropy.coordinates import Distance

# Get path to package mock data
mock_data_path = get_data_path("mock_data/GRB_42_mock.csv")

# Basic usage
source = Source(
    filepath=str(mock_data_path),
    min_energy=20 * u.GeV,
    max_energy=10 * u.TeV,
    ebl="franceschini"
)

# With explicit distance
source_with_distance = Source(
    filepath=str(mock_data_path),
    min_energy=20 * u.GeV,
    max_energy=10 * u.TeV,
    distance=Distance(z=0.5),
    ebl="franceschini"
)

# With explicit redshift
source_with_z = Source(
    filepath=str(mock_data_path),
    min_energy=20 * u.GeV,
    max_energy=10 * u.TeV,
    z=0.5,
    ebl="franceschini"
)

Attributes

Attribute	Type	Description
energy	u.Quantity	Energy grid
times	u.Quantity	Time grid
spectra	np.ndarray	2D array of flux values [energy, time]
filepath	Path	Path to source file
SpectralGrid	RegularGridInterpolator	Interpolation grid

Methods

observe()

Simulate observation to determine required exposure time.

observe(
    sensitivity: Sensitivity,
    start_time: u.Quantity,
    min_energy: u.Quantity,
    max_energy: u.Quantity,
    target_precision: u.Quantity = 1 * u.s,
    max_time: u.Quantity = 12 * u.h,
    sensitivity_mode: Literal["sensitivity", "photon_flux"] = "sensitivity",
    n_time_steps: int = 10,
) -> dict

Returns: Dictionary with detection results including obs_time, seen, start_time, end_time, metadata.

Example:

result = source.observe(
    sensitivity=sens,
    start_time=30 * u.min,
    min_energy=20 * u.GeV,
    max_energy=10 * u.TeV,
)
print(result['obs_time'] if result['seen'] else "Not detectable")

get_spectrum()

Get differential flux spectrum at a given time.

get_spectrum(time: u.Quantity, energy: u.Quantity | None = None) -> u.Quantity

Returns: Flux values at the specified time (and energy if provided).

spectrum = source.get_spectrum(time=100 * u.s)
flux_at_1TeV = source.get_spectrum(time=100 * u.s, energy=1 * u.TeV)

get_flux()

Get differential flux at a given energy.

get_flux(energy: u.Quantity, time: u.Quantity | None = None) -> u.Quantity

Returns: Flux values at the specified energy (and time if provided).

lightcurve = source.get_flux(energy=1 * u.TeV)
flux_value = source.get_flux(energy=1 * u.TeV, time=100 * u.s)

set_ebl_model()

Set or update EBL absorption model.

set_ebl_model(ebl: str | None, z: float | None = None, distance: Distance | None = None) -> bool

Parameters:

• ebl: EBL model name or None to remove
• z: Redshift (optional, auto-detected from metadata if available)
• distance: Distance to source as astropy Distance object (optional)

Note: Only one of distance or z can be provided, not both.

Returns: True if the distance was changed, False otherwise.

from astropy.coordinates import Distance

# Using redshift
source.set_ebl_model("franceschini", z=0.5)

# Using distance
distance = Distance(z=0.5)
source.set_ebl_model("franceschini", distance=distance)

# Remove EBL
source.set_ebl_model(None)

get_powerlaw_spectrum()

Create a Gammapy PowerLawSpectralModel representing the spectrum at a given time.

get_powerlaw_spectrum(
    time: u.Quantity,
    amplitude: u.Quantity | None = None,
    reference: u.Quantity = 1 * u.TeV,
    use_ebl: bool | None = None,
) -> PowerLawSpectralModel

Parameters:

Parameter	Type	Description
time	u.Quantity	Time at which to evaluate the spectrum
amplitude	u.Quantity | None	Optional amplitude at reference energy (auto-calculated if None)
reference	u.Quantity	Reference energy for power law (default: 1 TeV)
use_ebl	bool | None	Apply EBL absorption. If None, defaults to True if EBL model is set, otherwise False

Returns: Wrapped PowerLawSpectralModel with automatic energy range in plot() method.

Examples:

Without EBL

from sensipy.source import Source
from sensipy.util import get_data_path
import astropy.units as u

mock_data_path = get_data_path("mock_data/GRB_42_mock.csv")
source = Source(
    filepath=str(mock_data_path),
    min_energy=20 * u.GeV,
    max_energy=10 * u.TeV,
)

time = 100 * u.s
# Explicitly disable EBL (or use_ebl=None defaults to False when no EBL model is set)
spectrum = source.get_powerlaw_spectrum(time, use_ebl=False)

# Plot automatically uses source.min_energy and source.max_energy
spectrum.plot()

With EBL (default)

from sensipy.source import Source
from sensipy.util import get_data_path
import astropy.units as u

mock_data_path = get_data_path("mock_data/GRB_42_mock.csv")
source = Source(
    filepath=str(mock_data_path),
    min_energy=20 * u.GeV,
    max_energy=10 * u.TeV,
    ebl="franceschini",  # Set EBL model
)

time = 100 * u.s
# use_ebl=None defaults to True when EBL model is set
spectrum_with_ebl = source.get_powerlaw_spectrum(time)

# Plot shows absorbed spectrum
spectrum_with_ebl.plot()

get_template_spectrum()

Create a template spectral model from the spectrum at a given time.

get_template_spectrum(
    time: u.Quantity,
    scaling_factor: int | float = 1,
    use_ebl: bool | None = None,
) -> ScaledTemplateModel

Parameters:

Parameter	Type	Description
time	u.Quantity	Time at which to extract the spectrum
scaling_factor	int | float	Initial scaling factor (default: 1)
use_ebl	bool | None	Apply EBL absorption. If None, defaults to True if EBL model is set, otherwise False

Returns: Wrapped ScaledTemplateModel with automatic energy range in plot() method.

Examples:

Without EBL

from sensipy.source import Source
from sensipy.util import get_data_path
import astropy.units as u

mock_data_path = get_data_path("mock_data/GRB_42_mock.csv")
source = Source(
    filepath=str(mock_data_path),
    min_energy=20 * u.GeV,
    max_energy=10 * u.TeV,
)

time = 100 * u.s
# Explicitly disable EBL (or use_ebl=None defaults to False when no EBL model is set)
template = source.get_template_spectrum(time, use_ebl=False)

# Plot automatically uses source.min_energy and source.max_energy
template.plot()

With EBL (default)

from sensipy.source import Source
from sensipy.util import get_data_path
import astropy.units as u

mock_data_path = get_data_path("mock_data/GRB_42_mock.csv")
source = Source(
    filepath=str(mock_data_path),
    min_energy=20 * u.GeV,
    max_energy=10 * u.TeV,
    ebl="franceschini",  # Set EBL model
)

time = 100 * u.s
# use_ebl=None defaults to True when EBL model is set
template_with_ebl = source.get_template_spectrum(time)

# Plot shows absorbed spectrum
template_with_ebl.plot()

Note

Both get_powerlaw_spectrum() and get_template_spectrum() return wrapped models that automatically use the source’s min_energy and max_energy when calling .plot(). You can still override the energy range by passing energy_range explicitly to plot().

When use_ebl=None (the default), EBL absorption is automatically applied if an EBL model has been set (via the constructor or set_ebl_model()). Set use_ebl=False to explicitly disable EBL absorption, or use_ebl=True to force it even if no EBL model is set.

show_spectral_pattern()

Visualize the time-energy spectral evolution.

show_spectral_pattern(
    resolution: int = 100,
    return_plot: bool = False,
    cutoff_flux: u.Quantity = 1e-20 * u.Unit("1 / (cm2 s GeV)"),
) -> plt | None

source.show_spectral_pattern(resolution=100)

metadata

Property that returns a copy of the user-defined metadata dictionary. Metadata can be accessed via attribute notation (like pandas DataFrame columns) or through the dictionary.

# Access via attribute notation (recommended)
print(source.event_id)
print(source.distance)
print(source.eiso)

# Or access via the metadata dictionary
meta = source.metadata
print(meta.get('event_id'))
print(meta.get('distance'))
print(meta.get('eiso'))

# Set custom metadata
source.my_custom_field = "value"
print(source.my_custom_field)

Note

Metadata is completely user-defined—there are no built-in metadata fields. Keys come from your metadata CSV file or FITS header, and you can add custom fields at any time via attribute assignment.

File Format Support

• CSV: Recommended format with time, energy, flux columns
• FITS: HDU structure with energy, time, and flux arrays
• Text directory: Legacy format with multiple .txt files

See Spectral Models for format details.