pulsar_spectra modules

catalogue

Loads all the data required by vcstools from the data directory.

pulsar_spectra.catalogue.all_flux_from_atnf(query=None)

Queries the ATNF database for flux info for all pulsar at all frequencies.

Parameters

querypsrqpy object, optional

A previous psrqpy.QueryATNF query. Can be supplied to prevent performing a new query.

Returns

jname_cat_dictdict

Catalgoues dictionary with the keys in the format jname_cat_dict[jname][ref][‘Frequency MHz’, ‘Flux Density mJy’, ‘Flux Density error mJy’]

'jname'str

The pulsar’s Jname.

'ref'str

The reference label.

'Frequency MHz'

The observing frequency in MHz.

'Flux Density mJy'

The flux density in mJy.

'Flux Density error mJy'

The error of the flux density in mJy.

pulsar_spectra.catalogue.collect_catalogue_fluxes(only_use=None, exclude=None, query=None, use_atnf=True)

Collect the fluxes from all of the catalogues recorded in this repo.

Parameters

only_uselist, optional

A list of reference labels (in the format ‘Author_year’) of all the papers you want to use.

excludelist, optional

A list of reference labels (in the format ‘Author_year’) of all the papers you want to exclude.

querypsrqpy object, optional

A previous psrqpy.QueryATNF query. Can be supplied to prevent performing a new query.

use_atnf: `bool`, optional

Whether the ATNF values should be included. Default: True.

Returns

jname_cat_list[jname]dict

Catalgoues dictionary with the keys:

'jname'str

The pulsar’s Jname.

Each dictionary contains a list of lists with the following:

Frequency MHzlist

The observing frequency in MHz.

Flux Density mJylist

The flux density in mJy.

Flux Density error mJylist

The error of the flux density in mJy.

reflist

The reference label (in the format ‘Author_year’).

pulsar_spectra.catalogue.convert_antf_ref(ref_code, ref_dict=None)

Converts an ATNF psrcat reference code to a reference in the format “Author Year”

Parameters

ref_codestr

An ATNF psrcat reference code as found from psrqpy.get_references(updaterefcache=True) and https://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_ref.html.

ref_dictdict, optional

A previous psrqpy.get_references query. Can be supplied to prevent performing a new query.

Returns

refstr

Reference in the format “Author Year”.

pulsar_spectra.catalogue.convert_cat_list_to_dict(jname_cat_list)

Returns

jname_cat_dictdict

Catalgoues dictionary with the keys in the format jname_cat_dict[jname][ref][‘Frequency MHz’, ‘Flux Density mJy’, ‘Flux Density error mJy’]

'jname'str

The pulsar’s Jname.

'ref'str

The reference label.

'Frequency MHz'

The observing frequency in MHz.

'Flux Density mJy'

The flux density in mJy.

'Flux Density error mJy'

The error of the flux density in mJy.

pulsar_spectra.catalogue.flux_from_atnf(pulsar, query=None, ref_dict=None, assumed_error=0.5)

Queries the ATNF database for flux info on a particular pulsar at all frequencies.

Parameters

pulsarstr

The Jname of the pulsar.

querypsrqpy object, optional

A previous psrqpy.QueryATNF query. Can be supplied to prevent performing a new query.

ref_dictdict, optional

A previous psrqpy.get_references query. Can be supplied to prevent performing a new query.

assumed_errorfloat, optional

If no error found, apply this factor to flux to make an assumed error.
Default: 0.5.

Returns

freq_alllist

All frequencies in Hz with flux values on ATNF.

flux_alllist

The flux values corresponding to the freq_all list in mJy.

flux_err_alllist

The uncertainty in the flux_all values.

referenceslist

The reference keys from: https://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_ref.html

pulsar_spectra.catalogue.get_antf_references()

Wrapper for psrqpy.get_references() that ensures the cache is only Updated once.

models

Spectral models used for fitting

pulsar_spectra.models.broken_power_law(v, vb, a1, a2, c, v0)

Broken power law:

\[\begin{split}S_v = \begin{cases} c \left( \frac{v}{v0} \right)^{a1} & \mathrm{if}\: v \leq vb \\ c \left( \frac{v}{v0} \right)^{a2} \left( \frac{vb}{v0} \right)^{a1-a2} & \mathrm{otherwise} \\ \end{cases}\end{split}\]

Parameters

vlist

Frequency in Hz.

vbfloat

The frequency of the break in Hz.

a1float

The spectral index before the break.

a2float

The spectral index after the break.

cfloat

Constant.

v0float

Reference frequency.

Returns

S_vlist

The flux density predicted by the model.

pulsar_spectra.models.broken_power_law_intergral(vmin_vmax, vb, a1, a2, c, v0)

The bandwith intergration correction for the broken power law using direct intergration (see derivation for full equation):

Parameters

vmin_vmaxtuple (vmin, vmax)

Where vmin is the minimum and vmax is the maximum frequency in Hz for each flux density measurement’s bandwidth.

vbfloat

The frequency of the break in Hz.

a1float

The spectral index before the break.

a2float

The spectral index after the break.

cfloat

Constant.

v0float

Reference frequency.

Returns

S_vlist

The flux density predicted by the model.

pulsar_spectra.models.double_turn_over_spectrum(v, vc, vpeak, a, beta, c, v0)

Double turn over spectrum (has a low-frequency turnover and a high-frequency cut-off):

\[S_v = c \left( \frac{v}{v0} \right)^{a} \left ( 1 - \frac{v}{vc} \right ) \exp\left [ \frac{a}{\beta} \left( \frac{v}{vc} \right)^{-\beta} \right ],\qquad v < vc\]

Parameters

vlist

Frequency in Hz.

vclist

Cut off frequency in Hz.

vpeaklist

Peak/turn-over frequency in Hz.

afloat

Spectral Index.

betafloat

The smoothness of the turn-over.

cfloat

Constant.

v0float

Reference frequency.

Returns

S_vlist

The flux density predicted by the model.

pulsar_spectra.models.double_turn_over_spectrum_intergral(vmin_vmax, vc, vpeak, a, beta, c, v0)

The bandwith intergration correction for the double turn over spectrum (has a low-frequency turnover and a high-frequency cut-off) using direct intergration (see derivation for full equation):

Parameters

vmin_vmaxtuple (vmin, vmax)

Where vmin is the minimum and vmax is the maximum frequency in Hz for each flux density measurement’s bandwidth.

vclist

Cut off frequency in Hz.

vpeaklist

Peak/turn-over frequency in Hz.

afloat

Spectral Index.

betafloat

The smoothness of the turn-over.

cfloat

Constant.

v0float

Reference frequency.

Returns

S_vlist

The flux density predicted by the model.

pulsar_spectra.models.double_turn_over_spectrum_taylor(vmin_vmax, vc, vpeak, a, beta, c, v0)

The bandwith intergration correction for the double turn over spectrum (has a low-frequency turnover and a high-frequency cut-off) using Taylor series expansion (see derivation for full equation):

Parameters

vmin_vmaxtuple (vmin, vmax)

Where vmin is the minimum and vmax is the maximum frequency in Hz for each flux density measurement’s bandwidth.

vclist

Cut off frequency in Hz.

vpeaklist

Peak/turn-over frequency in Hz.

afloat

Spectral Index.

betafloat

The smoothness of the turn-over.

cfloat

Constant.

v0float

Reference frequency.

Returns

S_vlist

The flux density predicted by the model.

pulsar_spectra.models.gammainc_up(a, z)

Vectorised upper incomplete gamma function. Taken from: https://stackoverflow.com/questions/10542780/incomplete-gamma-function-in-python

pulsar_spectra.models.high_frequency_cut_off_power_law(v, vc, a, c, v0)

High-frequency cut-off power law:

\[S_v = c \left( \frac{v}{v0} \right)^{a} \left ( 1 - \frac{v}{vc} \right ),\qquad v < vc\]

Parameters

vlist

Frequency in Hz.

vclist

Cut off frequency in Hz.

afloat

Spectral Index.

cfloat

Constant.

v0float

Reference frequency.

Returns

S_vlist

The flux density predicted by the model.

pulsar_spectra.models.high_frequency_cut_off_power_law_intergral(vmin_vmax, vc, a, c, v0)

The bandwith intergration correction for the high-frequency cut-off power law using direct intergration (see derivation for full equation):

Parameters

vmin_vmaxtuple (vmin, vmax)

Where vmin is the minimum and vmax is the maximum frequency in Hz for each flux density measurement’s bandwidth.

vclist

Cut off frequency in Hz.

afloat

Spectral Index.

cfloat

Constant.

v0float

Reference frequency.

Returns

S_vlist

The flux density predicted by the model.

pulsar_spectra.models.high_frequency_cut_off_power_law_taylor(vmin_vmax, vc, a, c, v0)

The bandwith intergration correction for the high-frequency cut-off power law using Taylor series expansion (see derivation for full equation):

Parameters

vmin_vmaxtuple (vmin, vmax)

Where vmin is the minimum and vmax is the maximum frequency in Hz for each flux density measurement’s bandwidth.

vclist

Cut off frequency in Hz.

afloat

Spectral Index.

cfloat

Constant.

v0float

Reference frequency.

Returns

S_vlist

The flux density predicted by the model.

pulsar_spectra.models.log_parabolic_spectrum(v, a, b, c, v0)

Log-parabolic spectrum:

\[\log_{10} S_v = a \left [ \log_{10} \left ( \frac{v}{v0} \right ) \right]^2 + b \, \log_{10} \left ( \frac{v}{v0} \right ) + c\]

Parameters

vlist

Frequency in Hz.

afloat

Curvature parameter.

bfloat

The spectral index for \(a = 0\).

cfloat

Constant.

v0float

Reference frequency.

Returns

S_vlist

The flux density predicted by the model.

pulsar_spectra.models.low_frequency_turn_over_power_law(v, vpeak, a, c, beta, v0)

Low-frequency turn-over power law:

\[S_v = c \left( \frac{v}{v0} \right)^{a} \exp\left [ \frac{a}{\beta} \left( \frac{v}{vc} \right)^{-\beta} \right ]\]

Parameters

vlist

Frequency in Hz.

vpeaklist

Peak/Turn-over frequency in Hz.

afloat

The spectral index.

cfloat

Constant.

betafloat

The smoothness of the turn-over.

v0float

Reference frequency.

Returns

S_vlist

The flux density predicted by the model.

pulsar_spectra.models.low_frequency_turn_over_power_law_intergral(vmin_vmax, vpeak, a, c, beta, v0)

The bandwith intergration correction for the low-frequency turn-over power law using direct intergration (see derivation for full equation):

Parameters

vmin_vmaxtuple (vmin, vmax)

Where vmin is the minimum and vmax is the maximum frequency in Hz for each flux density measurement’s bandwidth.

vpeaklist

Peak/Turn-over frequency in Hz.

afloat

The spectral index.

cfloat

Constant.

betafloat

The smoothness of the turn-over.

v0float

Reference frequency.

Returns

S_vlist

The flux density predicted by the model.

pulsar_spectra.models.low_frequency_turn_over_power_law_taylor(vmin_vmax, vpeak, a, c, beta, v0)

The bandwith intergration correction for the low-frequency turn-over power law using Taylor series expansion (see derivation for full equation):

Parameters

vmin_vmaxtuple (vmin, vmax)

Where vmin is the minimum and vmax is the maximum frequency in Hz for each flux density measurement’s bandwidth.

vpeaklist

Peak/Turn-over frequency in Hz.

afloat

The spectral index.

cfloat

Constant.

betafloat

The smoothness of the turn-over.

v0float

Reference frequency.

Returns

S_vlist

The flux density predicted by the model.

pulsar_spectra.models.model_settings(print_models=False)

Holds metadata about spectral models such as common names and default fit parameters.

Parameters

print_modelsboolean, optional

If true, will print the models dictionary which is useful for debuging new models. Default False.

Returns

model_dictdict

Returns a dictionary in the format

{model_name: [model_function, short_name, start_params, mod_limits]}

pulsar_spectra.models.simple_power_law(v, a, c, v0)

Simple power law:

\[S_v = c \left( \frac{v}{v_0} \right)^a\]

Parameters

vlist

Frequency in Hz.

afloat

Spectral Index.

cfloat

Constant.

v0float

Reference frequency.

Returns

S_vlist

The flux density predicted by the model.

pulsar_spectra.models.simple_power_law_integrate(vmin_vmax, a, c, v0)

The bandwith intergration correction for the simple power law using direct intergration (derivation):

\[S_v = \frac{c({\nu_\text{max}}^{a+1} - {\nu_\text{min}}^{a+1})}{\rm{BW}\,\nu_0^a(a+1)}\]

Parameters

vmin_vmaxtuple (vmin, vmax)

Where vmin is the minimum and vmax is the maximum frequency in Hz for each flux density measurement’s bandwidth.

afloat

Spectral Index.

cfloat

Constant.

v0float

Reference frequency.

Returns

S_vlist

The flux density predicted by the model.

spectral_fit

Functions used to fit different spectral models to the fluxs_mJy densities of pulsars

pulsar_spectra.spectral_fit.estimate_flux_density(est_freq, model_name, iminuit_result)

Estimate a pulsar’s flux density using a previous spectra fit.

Parameters

est_freqfloat or list

A single or list of frequencies to estimate flux at (in MHz).

model_namefunction

The pulsar spectra model name from pulsar_spectra.models().

miminuit.Minuit

The Minuit class after being fit in pulsar_spectra.spectral_fit.iminuit_fit_spectral_model().

Returns

fitted_fluxfloat or list

The estimated flux density (in mJy) of the pulsar at the input frequencies.

fitted_flux_errfloat or list

The estimated flux density (in mJy) errors of the pulsar at the input frequencies.

pulsar_spectra.spectral_fit.find_best_spectral_fit(pulsar, freqs_MHz, bands_MHz, fluxs_mJy, flux_errs_mJy, ref_all, plot_all=False, plot_best=False, plot_compare=False, plot_error=True, alternate_style=False, axis=None, secondary_fit=False, fit_range=None, ref_markers=None)

Fit pulsar spectra with iminuit.

Parameters

pulsarstr

The Jname of the pulsar to be fit.

freqs_MHzlist

A list of the frequencies in MHz.

fluxs_mJylist

A list of the flux density in mJy.

flux_errs_mJylist

A list of the uncertainty of the flux density in mJy.

ref_alllist

A list of the reference label (in the format ‘Author_year’).

plot_allboolean, optional

If you want to plot the result of all fits.
Default: False.

plot_bestboolean, optional

If you want to only plot the best fit.
Default: False.

plot_compareboolean, optional

If you want to make a single plot with the result of all fits.
Default: False.

plot_errorboolean, optional

If you want to include the fit error in the plot.
Default: True.

alternate_styleboolean, optional

Plot with the alternate plot style based on Jankowski 2018.
Default: False.

axisAxes, optional

The axes with which the spectrum will be plotted.
Default: None.

secondary_fitboolean, optional

Plot model with an alternate style and without markers. Does not work for comparison plots.
Default: False.

fit_rangetuple, optional

Frequency range to plot the second model over.
Default: None.

ref_markersdict [str, tuple], optional

Used to overwrite the data marker defaults. The key is the reference name and the tuple contains (color, marker, markersize).
Default: None.

Returns

model_namestr

The best fit model name from pulsar_spectra.models().

miminuit.Minuit

The Minuit class after being fit in pulsar_spectra.spectral_fit.iminuit_fit_spectral_model().

fit_infostr

The string to label the fit with from pulsar_spectra.spectral_fit.iminuit_fit_spectral_model().

p_bestfloat

The probability that the best-fit model is actually the best-fit model.

p_categorystr

Category based on the quality of spectral fit, as defined in Jankowski et al. (2018).

pulsar_spectra.spectral_fit.huber_loss_function(sq_resi, k=1.345)

Robust loss function which penalises outliers, as detailed in Jankowski et al (2018).

Parameters

sq_resifloat or list

A single or list of the squared residuals.

kfloat, optional

A constant that defines at which distance the loss function starts to penalize outliers.
Default: 1.345.

Returns

rhofloat or list

The modified squared residuals.

pulsar_spectra.spectral_fit.iminuit_fit_spectral_model(freqs_MHz, bands_MHz, fluxs_mJy, flux_errs_mJy, ref, model_name='simple_power_law', start_params=None, mod_limits=None, plot=False, plot_error=True, save_name='fit.png', alternate_style=False, axis=None, secondary_fit=False, fit_range=None, ref_markers=None)

Fit pulsar spectra with iminuit.

Parameters

freqs_MHzlist

A list of the frequencies in MHz.

fluxs_mJylist

A list of the flux density in mJy.

flux_errs_mJylist

A list of the uncertainty of the flux density in mJy.

reflist

A list of the reference label (in the format ‘Author_year’).

model_namefunction, optional

One of the model names from pulsar_spectra.models.model_settings(). Default: pulsar_spectra.models.simple_power_law().

start_paramstuple, optional

A tuple of the starting paramaters for each input to the model that iminuit will use as an initial estimate. If none provided, will use the defaults from pulsar_spectra.models.model_settings().

mod_limitslist of `tuple`s, optional

A list of tuples where each tuples is the minimum and maximum limits that will be applied to the model by iminuit. If none provided, will use the defaults from pulsar_spectra.models.model_settings().

plotboolean, optional

If you want to plot the result of the fit.
Default: False.

plot_errorboolean, optional

If you want to include the fit error in the plot.
Default: True.

save_namestr, optional

The name of the saved plot.
Default: “fit.png”.

alternate_styleboolean, optional

If you want to use the alternate plot style.
Default: False.

axisAxes, optional

The axes with which the spectrum will be plotted.
None.

secondary_fitboolean, optional

Plot model with an alternate style and without markers.
Default: False.

fit_rangetuple, optional

Frequency range to plot the second model over.
Default: None.

ref_markersdict [str, tuple], optional

Used to overwrite the data marker defaults. The key is the reference name and the tuple contains (color, marker, markersize).
Default: None.

Returns

aicfloat

The Akaike information criterion of the fit.

miminuit.Minuit

The Minuit class after being fit in pulsar_spectra.spectral_fit.iminuit_fit_spectral_model().

fit_infostr

The string to label the fit with from pulsar_spectra.spectral_fit.iminuit_fit_spectral_model().

pulsar_spectra.spectral_fit.migrad_simplex_scan(m, mod_limits, model_name)

Find the minimum of least_squares function using the in-built minimisation algorithms in iminuit. If migrad by itself fails, then run the simplex minimiser before migrad. If simplex fails, run a grid scan over parameter space before migrad. Systematically increase the number of calls until a valid minimum is found.

pulsar_spectra.spectral_fit.plot_fit(freqs_MHz, bands_MHz, fluxs_mJy, flux_errs_mJy, ref, model, iminuit_result, fit_info, plot_error=True, save_name='fit.png', alternate_style=False, axis=None, secondary_fit=False, fit_range=None, ref_markers=None, plot_bands=False)

Create a plot of the pulsar spectral fit.

Parameters

freqs_MHzlist

A list of the frequencies in MHz.

fluxs_mJylist

A list of the flux density in mJy.

flux_errs_mJylist

A list of the uncertainty of the flux density in mJy.

reflist

A list of the reference label (in the format ‘Author_year’).

modelfunction

One of the model functions from pulsar_spectra.models().

iminuit_resultiminuit.Minuit

The Minuit class after being fit in pulsar_spectra.spectral_fit.iminuit_fit_spectral_model().

fit_infostr

The string to label the fit with from pulsar_spectra.spectral_fit.iminuit_fit_spectral_model().

plot_errorboolean, optional

If you want to include the fit error in the plot.
Default: True.

save_namestr, optional

The name of the saved plot.
Default: “fit.png”.

alternate_styleboolean, optional

Plot with the alternate plot style based on Jankowski 2018.
Default: False.

axisAxes, optional

The axes with which the spectrum will be plotted.
None.

secondary_fitboolean, optional

Plot model with an alternate style and without markers.
Default: False.

fit_rangetuple, (float, float) optional

Frequency range to plot the second model over in MHz, eg. (100, 3000).
Default: None, will use input frequency range.

ref_markersdict [str, tuple], optional

Used to overwrite the data marker defaults. The key is the reference name and the tuple contains (color, marker, markersize).
Default: None.

pulsar_spectra.spectral_fit.propagate_flux_n_err(freqs, model, iminuit_result)

Propagate the flux based on an input model and use the iminuit to calculate errors if possible.

Parameters

freqslist

List of frequencies in MHz.

modelfunction

The spectral model function from pulsar_spectra.models().

iminuit_resultiminuit.Minuit

The Minuit class after being fit in pulsar_spectra.spectral_fit.iminuit_fit_spectral_model().

Returns

fitted_fluxlist

A list of the fluxes (in mJy) based on the input model and fit results.

fitted_flux_errlist

A list of flux errors (in mJy) if possible or Nones if not possible.

pulsar_spectra.spectral_fit.robust_cost_function(f_y, y, sigma_y, k=1.345)

Robust cost function. The negative log-likelihood of a Gaussian likelihood with Huber loss.

Parameters

f_ylist

A list of predicted values according to the model.

ylist

A list of measured values at the same frequency as the model values.

sigma_ylist

A list of uncertainties corresponding to the measured values y.

kfloat, optional

A constant that defines at which distance the loss function starts to penalize outliers.
Default: 1.345.

Returns

betafloat

The cost of the model fit.

analysis

pulsar_spectra.analysis.calc_high_frequency_cutoff_emission_height(psrname, v_c, u_v_c, z_surf=12, u_z_surf=2)

Calculate emission height and magetic field strengths using high-frequency cut-off model (pulsar_spectra.models.high_frequency_cut_off_power_law()). Details on the calculation procedure can be found in Jankowski et al. (2018) and Lee et al. (2022). The default neutron star radius is based on a canonical 1.4 solar mass neutron star as per Steiner et al. (2018).

Parameters

psrnamestring

Pulsar name.

v_cfloat

Cut-off frequency in units of Hz.

u_v_cfloat

Uncertainty in cut-off frequency in units of Hz.

z_surffloat, optional

Radius of the neutron star in km.
Default: 12.

u_z_surffloat, optional

Uncertainty on the radius of the neutron star in km.
Default: 2.

Returns

B_pcfloat

Magnetic field strength at the centre of the polar cap in units of Gauss.

u_B_pcfloat

Uncertainty of B_pc in Gauss.

B_surffloat

Magnetic field strength at the neutron star surface.

B_lcfloat

Magnetic field strength at the light cylinder radius in Gauss.

r_lcfloat

Light cylinder radius in km.

z_efloat

Estimated emission height (i.e. the altitude of the centre of the polar cap) in km.

u_z_efloat

Uncertainty of z_e in km.

z_percentfloat

Estimated emission height as a percentage of light-cylinder radius.

u_z_percentfloat

Uncertainty of z_percent as a percentage of light-cylinder radius.

pulsar_spectra.analysis.calc_log_parabolic_spectrum_max_freq(a, b, v0, u_a, u_b, u_ab)

Calculate the frequency where the flux is at its maximum for the log parabolic model (pulsar_spectra.models.log_parabolic_spectrum()).

Parameters

afloat

Curvature parameter.

bfloat

The spectral index for \(a = 0\).

v0float

Reference frequency.

u_afloat

The uncertainty of the curvature parameter, a.

u_bfloat

The uncertainty of b.

u_abfloat

The covariance between a and b.

Returns

v_peakfloat

The frequency in Hz where the flux is at its maximum for the log parabolic model.

u_v_peakfloat

The uncertainty of v_peak in Hz.