Catalogue
The catalogue comprises YAML files containing pulsar flux density measurements for each paper the repository has included. You should not assume that this repository has all flux density measurements for a pulsar you are interested in. Instead, you should search through the literature to find all papers that contain flux density measurements of the pulsar and confirm all of those papers are in the catalogue. If you would like to add a new paper to the catalogue see the Adding to the catalogue section.
Using the catalogue
This section will explain how to use the catalogue. If you would like more information, you can see the module documentation in the catalogue module description.
You can use the following command to get all fluxes from the catalogue.
from pulsar_spectra.catalogue import collect_catalogue_fluxes
cat_dict = collect_catalogue_fluxes()
cat_dict will have the format
cat_dict = {"Pulsar Jname":[["List of frequencies in MHz"],
["List of bandwidths in MHz"],
["List of flux densities in mJy"],
["List of flux density uncertainties in mJy"],
["The reference label (in the format 'Author_year')"]],
"Other pulsar":[["List of frequencies in MHz"],
["List of bandwidths in MHz"],
["List of flux densities in mJy"],
["List of flux density uncertainties in mJy"],
["The reference label (in the format 'Author_year')"]],
}
For example, this is the data for PSR J2256-1024.
print(cat_dict['J2256-1024'])
[[350.0, 350, 820, 822, 1392, 1500, 350.0, 350.0],
[100.0, 200, 200, 64, 64, 200, 100.0, 100.0],
[8.3, 13.0, 1.9, 1.7, 0.73, 1.2, 7.0, 17.8],
[4.15, 6.5, 0.9, 0.85, 0.365, 0.6, 3.5, 3.5],
['Bangale_2024', 'Crowter_2020', 'Crowter_2020', 'Crowter_2020', 'Crowter_2020', 'Crowter_2020', 'Hessels_2011', 'McEwen_2020']]
You can add your data like so before fitting the spectra
freqs, bands, fluxs, flux_errs, refs = cat_dict[pulsar]
freqs += [150.]
bands += [30.]
fluxs += [1000.]
flux_errs += [100.]
refs += ["Your Work"]
You can exclude papers that you don’t trust the results or if you think they’re negatively affecting your fit. For example, you can create a cat_dict without Sieber et al. (1973) like so
cat_dict = collect_catalogue_fluxes(exclude=["Sieber_1973"])
Conversely, if you only what the flux density measurements from a few papers, you can use the include argument. For example, you can create a cat_dict that only includes data from Murphy et al. (2017) and Xue et al. (2017) like so
cat_dict = collect_catalogue_fluxes(include=["Murphy_2017", "Xue_2017"])
Papers included in our catalogue
Paper |
# Pulsars |
Frequency range (MHz) |
Link |
|---|---|---|---|
ATNF pulsar catalogue |
3050 |
35-150000 |
|
McLean et al. (1973) |
18 |
406-410 |
|
Bartel et al. (1978) |
18 |
14550-22850 |
|
Manchester et al. (1978a) |
224 |
16-410 |
|
Izvekova et al. (1981) |
86 |
38-103 |
|
Dewey et al. (1985) |
34 |
382-398 |
|
Stokes et al. (1985) |
20 |
386-394 |
|
Slee et al. (1986) |
44 |
79-160 |
|
Stokes et al. (1986) |
5 |
429-430 |
|
Fruchter et al. (1988) |
1 |
425-435 |
|
Fruchter et al. (1990) |
1 |
1440-1540 |
|
McConnell et al. (1991) |
4 |
550-670 |
|
Johnston et al. (1992) |
100 |
624-1680 |
|
Wolszczan et al. (1992) |
1 |
420-1566 |
|
Johnston et al. (1993) |
1 |
414-2520 |
|
Malofeev et al. (1993) |
33 |
60-103 |
|
Manchester et al. (1993) |
1 |
624-656 |
|
Wielebinski et al. (1993) |
4 |
32900-34900 |
|
Bailes et al. (1994) |
3 |
420-452 |
|
Camilo et al. (1995) |
29 |
420-440 |
|
Lorimer et al. (1995) |
4 |
420-1536 |
|
Lundgren et al. (1995) |
1 |
426-1420 |
|
Manchester et al. (1995) |
2 |
1320-8380 |
|
Navarro et al. (1995) |
1 |
407-1420 |
|
Nicastro et al. (1995) |
1 |
407-1404 |
|
Qiao et al. (1995) |
61 |
644-1520 |
|
Robinson et al. (1995) |
2 |
420-656 |
|
Seiradakis et al. (1995) |
188 |
1295-10800 |
|
Lorimer et al. (1995b) |
280 |
407-1606 |
|
Biggs et al. (1996) |
4 |
406-410 |
|
Camilo et al. (1996) |
19 |
426-820 |
|
Lorimer et al. (1996) |
4 |
420-1416 |
|
Manchester et al. (1996) |
55 |
420-452 |
|
Zepka et al. (1996) |
1 |
426-1404 |
|
Bailes et al. (1997) |
4 |
406-1416 |
|
Hoensbroech et al. (1997) |
27 |
1370-10600 |
|
Kaspi et al. (1997) |
1 |
644-1810 |
|
Kijak et al. (1997) |
4 |
4600-5100 |
|
Kramer et al. (1997) |
4 |
13600-44000 |
|
Sayer et al. (1997) |
8 |
350-820 |
|
van Ommen et al. (1997) |
82 |
795-965 |
|
Kijak et al. (1998) |
83 |
4600-5100 |
|
Kramer et al. (1998) |
23 |
1390-1599 |
|
Shrauner et al. (1998) |
20 |
81-82 |
|
Toscano et al. (1998) |
19 |
420-1724 |
|
Han et al. (1999) |
106 |
1414-1456 |
|
Kramer et al. (1999) |
15 |
2655-4890 |
|
Stairs et al. (1999) |
19 |
407-1419 |
|
Weisberg et al. (1999) |
98 |
1398-1438 |
|
Kouwenhoven et al. (2000) |
39 |
322-327 |
|
Lommen et al. (2000) |
3 |
426-1404 |
|
Malofeev et al. (2000) |
211 |
102-102 |
|
Crawford et al. (2001) |
9 |
644-2328 |
|
Giacani et al. (2001) |
2 |
1407-8472 |
|
Kuzmin et al. (2001) |
30 |
101-111 |
|
Manchester et al. (2001) |
100 |
1230-1518 |
|
McGary et al. (2001) |
3 |
1439-1464 |
|
Morris et al. (2002) |
120 |
1230-1518 |
|
Kramer et al. (2003a) |
200 |
1230-1518 |
|
Esamdin et al. (2004) |
2 |
326-328 |
|
Lewandowski et al. (2004) |
18 |
426-1403 |
|
Maron et al. (2004) |
3 |
8250-8450 |
|
Hobbs et al. (2004a) |
453 |
1350-1450 |
|
Karastergiou et al. (2005) |
48 |
2588-3612 |
|
Lorimer et al. (2005) |
38 |
395-435 |
|
Champion et al. (2005a) |
17 |
426-433 |
|
Champion et al. (2005b) |
1 |
314-442 |
|
Johnston et al. (2006) |
31 |
8100-8612 |
|
Lorimer et al. (2006) |
142 |
1256-1544 |
|
Crawford et al. (2007) |
2 |
1320-3164 |
|
Freire et al. (2007) |
1 |
325-2250 |
|
Kijak et al. (2007) |
11 |
317-1068 |
|
Lorimer et al. (2007) |
1 |
426-433 |
|
Champion et al. (2008) |
1 |
1350-5300 |
|
Stappers et al. (2008) |
13 |
117-177 |
|
Deller et al. (2009) |
9 |
1642-1658 |
|
Janssen et al. (2009) |
3 |
318-2340 |
|
Joshi et al. (2009) |
3 |
618-1416 |
|
Bates et al. (2011) |
18 |
6303-6879 |
|
Hessels et al. (2011) |
12 |
300-400 |
|
Keith et al. (2011) |
9 |
16488-24512 |
|
Kijak et al. (2011) |
15 |
602-5100 |
|
Kowalinska et al. (2012) |
5 |
8250-8450 |
|
Lynch et al. (2012) |
12 |
1600-2400 |
|
Mickaliger et al. (2012) |
1 |
720-920 |
|
Boyles et al. (2013) |
13 |
795-845 |
|
Demorest et al. (2013) |
17 |
263-2364 |
|
Dowell et al. (2013) |
1 |
37-85 |
|
Lynch et al. (2013) |
10 |
795-845 |
|
Manchester et al. (2013) |
20 |
665-3600 |
|
Zakharenko et al. (2013) |
40 |
18-27 |
|
Dembska et al. (2014) |
19 |
602-8900 |
|
Stovall et al. (2014) |
67 |
300-920 |
|
Dai et al. (2015) |
24 |
698-3612 |
|
Dembska et al. (2015) |
6 |
593-626 |
|
Kuniyoshi et al. (2015) |
10 |
73-1412 |
|
Lazarus et al. (2015) |
127 |
1214-1536 |
|
Ng et al. (2015) |
54 |
1182-1522 |
|
Stovall et al. (2015) |
36 |
25-89 |
|
Basu et al. (2016) |
1 |
308-1296 |
|
Bell et al. (2016) |
17 |
138-169 |
|
Bhattacharyya et al. (2016) |
12 |
306-338 |
|
Bilous et al. (2016) |
158 |
110-188 |
|
Frail et al. (2016) |
200 |
139-155 |
|
Han et al. (2016) |
228 |
1242-1555 |
|
Kondratiev et al. (2016) |
48 |
110-188 |
|
Levin et al. (2016) |
37 |
1100-1900 |
|
Mikhailov et al. (2016) |
2 |
111-180 |
|
Kijak et al. (2017) |
12 |
308-626 |
|
Mignani et al. (2017) |
1 |
93750-347250 |
|
Murphy et al. (2017) |
60 |
72-231 |
|
Xue et al. (2017) |
48 |
169-200 |
|
Zhao et al. (2017) |
26 |
8200-9000 |
|
Basu et al. (2018) |
6 |
308-1296 |
|
Brinkman et al. (2018) |
12 |
302-1425 |
|
Gentile et al. (2018) |
28 |
380-2500 |
|
Jankowski et al. (2018) |
441 |
696-3612 |
|
Johnston et al. (2018) |
585 |
1232-1488 |
|
Rozko et al. (2018) |
2 |
308-6300 |
|
Aloisi et al. (2019) |
4 |
300-400 |
|
Jankowski et al. (2019) |
205 |
827-858 |
|
Kaur et al. (2019) |
1 |
80-220 |
|
Sanidas et al. (2019) |
288 |
119-151 |
|
Surnis et al. (2019) |
3 |
308-1186 |
|
Titus et al. (2019) |
3 |
1182-1582 |
|
Xie et al. (2019) |
32 |
1241-1497 |
|
Zhang et al. (2019) |
3 |
704-4032 |
|
Zhao et al. (2019) |
71 |
4320-5624 |
|
Bilous et al. (2020) |
43 |
30-77 |
|
Bondonneau et al. (2020) |
64 |
25-89 |
|
Crowter et al. (2020) |
1 |
250-1600 |
|
Curylo et al. (2020) |
1 |
110-189 |
|
McEwen et al. (2020) |
670 |
300-400 |
|
Michilli et al. (2020) |
19 |
90-1740 |
|
Tan et al. (2020) |
20 |
102-1724 |
|
Alam et al. (2021) |
47 |
398-2132 |
|
Bondonneau et al. (2021) |
12 |
12-87 |
|
Han et al. (2021) |
201 |
1025-1475 |
|
Johnston et al. (2021) |
44 |
1241-1497 |
|
Kijak et al. (2021) |
13 |
308-626 |
|
Rozko et al. (2021) |
3 |
308-1296 |
|
Shapiro Albert et al. (2021) |
3 |
380-1900 |
|
Kravtsov et al. (2022) |
20 |
16-33 |
|
Lee et al. (2022) |
22 |
69-352 |
|
Martsen et al. (2022) |
32 |
1175-2325 |
|
Parent et al. (2022) |
72 |
1214-1537 |
|
Spiewak et al. (2022) |
101 |
896-1671 |
|
Bhat et al. (2023) |
120 |
138-169 |
|
Fiore et al. (2023) |
21 |
27-2050 |
|
Gitika et al. (2023) |
89 |
895-1673 |
|
Bangale et al. (2024) |
18 |
300-2050 |
|
Deneva et al. (2024) |
184 |
292-361 |
|
Keith et al. (2024) |
597 |
896-1671 |
|
Wang et al. (2024) |
10 |
2200-9000 |
|
Kumar et al. (2025) |
96 |
25-89 |
|
Lee et al. (2025) |
40 |
138-169 |
|
Mantovanini et al. (2025) |
190 |
72-230 |
Adjusting the uncertainty of catalogue data
In this repository, we follow the method used by Bilous et al. (2016) and Sieber (1973) to increase the flux density uncertainties for observations that do not have a sufficient number of epochs to account for the scintillation variability. This is done by classifying the papers as either “Single-epoch”, “Several-epoch” or “Multi-epoch”.
Single-epoch: If the paper only reports flux density measurements from a single observation or is unclear about the number of observations, then we assign a minimum relative uncertainty of 50% to account for diffractive and refractive interstellar scintillation. We assume that all ATNF observations fall into this category. It should be noted that some pulsars may exhibit greater changes in flux density than this, in which case the uncertainties may still be underestimated.
Several-epoch: If the paper reports flux density measurements from several observations (<5) over less than a year, then we assume that the refractive scintillation is partially accounted on this timescale, and we assign a minimum relative uncertainty of 30%.
Multi-epoch: If the paper reports flux density measurements from multiple observations (>=5) over a year or more, and the uncertainty has been calculated as the standard deviation of the flux density measurements, then we assume that the refractive scintillation has been fully accounted for, and we do not make any adjustments.
For example, you can see in the Bates_2011.yaml that the paper is classified as “Single-epoch” and the flux density uncertainties are less than 50% of the flux density value:
Paper Metadata:
Data Type: Beamforming
Observation Span: Single-epoch
J1316-6232:
Frequency MHz:
- 6591
Bandwidth MHz:
- 576
Flux Density mJy:
- 0.7
Flux Density error mJy:
- 0.1
J1327-6222:
Frequency MHz:
- 6591
Bandwidth MHz:
- 576
Flux Density mJy:
- 0.9
Flux Density error mJy:
- 0.2
When you use the collect_catalogue_fluxes function, it will automatically adjust the uncertainties of the flux density measurements based on the observation span of the paper.
For example, if we run the following code:
from pulsar_spectra.catalogue import collect_catalogue_fluxes
cat_dict = collect_catalogue_fluxes(only_use=["Bates_2011"])
freq, band, flux, flux_err, ref = cat_dict["J1316-6232"]
print(f"J1316-6232 flux: {flux[0]} ± {flux_err[0]} mJy")
freq, band, flux, flux_err, ref = cat_dict["J1327-6222"]
print(f"J1327-6222 flux: {flux[0]} ± {flux_err[0]} mJy")
It will output:
J1316-6232 flux: 0.7 ± 0.35 mJy
J1327-6222 flux: 0.9 ± 0.45 mJy
Which, as you can see, is different from what is recorded in the YAML file (0.1 and 0.2 mJy, respectively).
This is the default behaviour, but you can turn it off by using the adjust_errors=False argument in collect_catalogue_fluxes:
from pulsar_spectra.catalogue import collect_catalogue_fluxes
cat_dict = collect_catalogue_fluxes(adjust_errors=False)
If data was more widely available in the literature for individual observing epochs, then this feature could be expanded in future to make more accurate adjustments to the uncertainties. Based on the DM and local turbulence, we could calculate the expected scintillation variability and then use the time and duration of each observation to adjust the uncertainties accordingly if the variability hasn’t been averaged out. The data required for this is not available in most papers, but as more automated pulsar monitoring is uploaded to online databases, this may become possible in the future.
Finding more papers to add to the catalogue
The pulsar_spectra catalogue is not a complete catalogue of flux density measurements, so researchers should do their own literature review to find any publications that have not yet been included in the catalogue. The following sections are suggestions of some ways to find new publications.
Look up ANTF references
If you see a reference label ending in _ATNF (see below for an example), those flux density measurements were imported from the ATNF catalogue.
Important
Since the ATNF catalogue does not include bandwidth information, we use a default bandwidth of 1 MHz for all imported data. If the data spans a significant fractional bandwidth and/or the centre frequency reported in the ATNF catalogue is inaccurate, then this may be a poor assumption. This can be the case, for example, since many of the ATNF catalogue flux densities are recorded at the nearest standard frequency (e.g. 400 MHz). We also assume all ATNF observations are single-epoch (see Adjusting the uncertainty of catalogue data for more details). Therefore, if you are planning on using the spectral fits for scientific analysis, then we recommend adding the paper to the catalogue. The first author and the year in the reference label will help you find the full reference on the ATNF references page.
Adding to the catalogue
If you would like to add a new paper to the catalogue, you should first format the data into CSV with the following format:
Pulsar Jname,Frequency (MHz),Bandwidth (MHz),Flux Density (mJy),Flux Density Uncertainty (mJy)
J0030+0451,150,20,37.6,4.4
J0030+0451,180,20,32.4,3.2
J0034-0534,150,20,202.8,7.9
J0034-0721,150,20,367.9,10.5
If the paper does not provide a flux density, then the script will assume a 50% uncertainty if you do not have to include it in your CSV like so:
Pulsar Jname,Frequency (MHz),Bandwidth (MHz),Flux Density (mJy)
J0030+0451,150,20,37.6
J0030+0451,180,20,32.4
J0034-0534,150,20,202.8
J0034-0721,150,20,367.9
If the paper only provides the B name then the script will convert to a J name using psrqpy as long as the PSR name starts with a B:
Pulsar Jname,Frequency (MHz),Bandwidth (MHz),Flux Density (mJy)
B0037+56,390,20,3.5
B0045+33,390,20,4.5
B0052+51,390,20,3.6
B0053+47,390,20,5.8
Then move to the catalogue subdirectory (src/pulsar_spectra/catalogue_papers) of the repository and run the command:
csv-to-yaml --csv your_paper.csv --ref <author_year> --obs_span <observation_span> --data_type <beamforming_or_imaging>
Where <author_year> is the first author’s last name and the year of publication (e.g. Smith_2020),
<observation_span> is either Single-epoch, Several-epoch or Multi-epoch (see Adjusting the uncertainty of catalogue data for more details), and
<beamforming_or_imaging> is either Beamforming or Imaging depending on the detection type.
This will put a YAML file of the paper in src/pulsar_spectra/catalogue_papers/.
You should then reinstall the software and run a spectral fit to confirm it worked.
Catalogue standards for new paper
For flux density measurements to be uploaded to the catalogue, they must meet the following criteria and standards:
- Published
The paper must be peer-reviewed and published. We are considering altering this to accept regular measurement programs with an established and reliable method.
- New results
If the paper includes flux density measurements from previous publications, do not include them.
- Include bandwidth
A bandwidth value is required for each flux density measurement. If there is no mention of the bandwidth in the paper, investigate previous publications that use the telescope to determine what bandwidth was likely used. If there is no way to determine the bandwidth used, do not use the paper.
- Flux density uncertainties
If the paper does not supply a flux density uncertainty, assume a relative uncertainty of 50 %.
- Do not include upper limits
The catalogue does not currently have a way of handling upper limits, so do not include them. If you have a suggestion for handling upper limits, please make an issue or start a discussion on the GitHub page.
Uploading the new catalogue to GitHub
So others can use this paper’s data, you should create a fork of the pulsar_spectra, and the new catalogue files and make a pull request. The following are the steps this will require and what you should include in your pull request.
- Make a fork of pulsar spectra
Go to the pulsar_spectra repository and fork it by clicking the fork button in the top right. Follow the steps until you are on the webpage with your fork (the URL should look like https://github.com/yourusername/pulsar_spectra).
- Clone your fork
From your fork webpage, click the code button and copy the clone URL. In your terminal, go to a directory where you would like to put the code and run the command
git clone <copied url here>The
pulsar_spectradirectory it creates is where you should be working on your changes.
- Add each paper
For each paper, perform the following sub-steps
- Create the YAML paper file
Follow the steps in the added to the catalogue section, will make a YAML file in the directory
pulsar_spectra/catalogue_papers/.
- Update ADS links
In the
pulsar_spectra/catalogue.py, there is a dictionary calledADS_REF(currently on line 25). Add a new line to this dictionary by making the key “Author_year” and the link to the ADS abstract page for the paper. So the format is:"Author_year": "adslink",
- Commit the changed files
First, you must add the new YAML file and the updated ADS ref like so (changing the command for your file):
git add pulsar_spectra/catalogue_papers/<AUTHOR_YEAR>.yaml pulsar_spectra/catalogue.pyThen make a commit describing your changes:
git commit -m "Added <AUTHOR_YEAR> to the catalogue.Feel free to add a brief description of the paper if you’d like.
- Create a pull request
Once you have finished adding to the repo, you can push your changes to your GitHub fork using:
git pushThen go to your GitHub pulsar_spectra fork webpage and click on “Pull requests”, and then “Create pull request” (It may have prompted you to make a pull request already).
What we want (and what should happen by default) is the pull request will say something like this:
base respository:NickSwainston/pulsar_spectra base:main <- head respository:YOURUSERNAME/pulsar_spectra base:mainWrite a description of the changes you have made and click submit.
- Wait for approval
The maintainers will review your changes, run some of the tests and either help you fix any errors or fix them on your behalf. Once the pull request is fixed and tested, it will be merged into the main branch so everyone can use it.
- Celebrate!
Pat yourself on the back for contributing to open-source software! You should now see yourself listed under the contributors to the repository.
Catalogue format
The catalogue is made up of YAML files of each paper. The format of the YAML files is:
Paper Metadata:
Data Type: Beamforming or Imaging
Observation Span: Single-epoch, Several-epoch or Multi-epoch
Pulsar Jname:
Frequency MHz:
- First frequency value in MHz
- Second frequency value in MHz
Bandwidth MHz:
- First bandwidth value in MHz
- Second bandwidth value in MHz
Flux Density mJy:
- First flux density value in mJy
- Second flux density value in mJy
Flux Density error mJy:
- First flux density uncertainty value in mJy
- Second flux density uncertainty value in mJy
For example:
Paper Metadata:
Data Type: Beamforming
Observation Span: Single-epoch
J0030+0451:
Frequency MHz:
- 150.0
- 180.0
Bandwidth MHz:
- 37.6
- 32.4
Flux Density mJy:
- 4.4
- 3.2
Flux Density error mJy:
- 2.2
- 1.6
J0034-0534:
Frequency MHz:
- 150.0
Bandwidth MHz:
- 202.8
Flux Density mJy:
- 7.9
Flux Density error mJy:
- 3.95
Where the Paper Metadata section contains information about the paper as a whole, and each pulsar has its own section with lists of frequencies, bandwidths, flux densities and flux density uncertainties.
The Data Type can be either Beamforming or Imaging, and the Observation Span can be either Single-epoch, Several-epoch or Multi-epoch (for details on the observation span, see the Adjusting the uncertainty of catalogue data section).