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 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 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 J1453-6413.

print(cat_dict['J1453-6413'])
[[950.0, 800.0, 1400, 8400, 728, 1382, 3100, 185.0, 200.0, 154.0, 200, 400, 150, 800],
 [42.0, 89.0, 14.0, 1.5, 80.0, 18.0, 2.4, 1244.0, 684.0, 630.0, 684.0, 230.0, 630.0, 53.0],
 [4.2, 26.7, 1.4, 0.75, 10.0, 1.0, 0.5, 20.0, 23.0, 200.0, 23.0, 115.0, 20.0, 3.0],
 ['van_Ommen_1997', 'van_Ommen_1997', 'Hobbs_2004', 'Johnston_2006', 'Jankowski_2018', 'Jankowski_2018', 'Jankowski_2018', 'Xue_2017', 'Xue_2017', 'Bell_2016', 'Murphy_2017', 'Taylor_1993', 'Bell_2016', 'Jankowski_2019']]

You can add your data like so before fitting the spectra

freqs, fluxs, flux_errs, refs = cat_dict[pulsar]
freqs += [150.]
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, I can create a cat_dict without Sieber et al. 1973 like so

cat_dict = collect_catalogue_fluxes(exclude=["Sieber_1973"])

Inversely 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

Papers included in our catalogue

Paper	# Pulsars	Frequency range (MHz)	Link
ATNF pulsar catalogue	2863	40-150000	Catalogue website
McLean et al. (1973)	18	408-408	ADS
Bartel et al. (1978)	18	14800-22700	ADS
Manchester et al. (1978a)	224	40-408	ADS
Izvekova et al. (1981)	86	39-102	ADS
Dewey et al. (1985)	34	390-390	ADS
Stokes et al. (1985)	20	390-390	ADS
Stokes et al. (1986)	5	430-430	ADS
McConnell et al. (1991)	4	610-610	ADS
Johnston et al. (1992)	100	640-1520	ADS
Wolszczan et al. (1992)	1	430-1400	ADS
Johnston et al. (1993)	1	430-2360	ADS
Malofeev et al. (1993)	33	61-102	ADS
Manchester et al. (1993)	1	640-640	ADS
Camilo et al. (1995)	29	430-430	ADS
Lorimer et al. (1995)	4	436-1520	ADS
Lundgren et al. (1995)	1	430-1400	ADS
Manchester et al. (1995)	2	1400-8300	ADS
Nicastro et al. (1995)	1	411-1400	ADS
Qiao et al. (1995)	61	660-1440	ADS
Robinson et al. (1995)	2	436-640	ADS
Seiradakis et al. (1995)	188	1315-10550	ADS
Lorimer et al. (1995b)	280	408-1606	ADS
Biggs et al. (1996)	4	408-408	ADS
Lorimer et al. (1996)	4	436-1400	ADS
Manchester et al. (1996)	55	436-436	ADS
Zepka et al. (1996)	1	430-1400	ADS
Bailes et al. (1997)	4	400-1400	ADS
Hoensbroech et al. (1997)	27	1410-10450	ADS
Kaspi et al. (1997)	1	660-1650	ADS
Kramer et al. (1997)	4	14600-43000	ADS
Sayer et al. (1997)	8	370-800	ADS
van Ommen et al. (1997)	82	800-960	ADS
Kijak et al. (1998)	87	4850-4850	ADS
Kramer et al. (1998)	34	1400-1400	ADS
Shrauner et al. (1998)	20	81-81	ADS
Toscano et al. (1998)	19	436-1660	ADS
Han et al. (1999)	106	1435-1435	ADS
Kramer et al. (1999)	16	2695-4850	ADS
Stairs et al. (1999)	19	410-1414	ADS
Weisberg et al. (1999)	98	1418-1418	ADS
Kouwenhoven et al. (2000)	39	325-325	ADS
Lommen et al. (2000)	3	430-1400	ADS
Malofeev et al. (2000)	212	102-102	ADS
Crawford et al. (2001)	9	660-2264	ADS
Giacani et al. (2001)	2	1420-8460	ADS
Kuzmin et al. (2001)	30	102-111	ADS
Manchester et al. (2001)	100	1374-1374	ADS
McGary et al. (2001)	3	1452-1452	ADS
Morris et al. (2002)	120	1374-1374	ADS
Kramer et al. (2003a)	200	1374-1374	ADS
Esamdin et al. (2004)	2	327-327	ADS
Lewandowski et al. (2004)	18	430-1400	ADS
Hobbs et al. (2004a)	453	1400-1400	ADS
Karastergiou et al. (2005)	48	3100-3100	ADS
Lorimer et al. (2005)	38	400-430	ADS
Champion et al. (2005a)	17	430-430	ADS
Champion et al. (2005b)	1	327-430	ADS
Johnston et al. (2006)	31	8356-8356	ADS
Lorimer et al. (2006)	142	1400-1400	ADS
Crawford et al. (2007)	2	1384-3100	ADS
Freire et al. (2007)	1	350-1950	ADS
Kijak et al. (2007)	11	325-1060	ADS
Lorimer et al. (2007)	1	430-430	ADS
Stappers et al. (2008)	13	147-147	ADS
Deller et al. (2009)	9	1650-1650	ADS
Janssen et al. (2009)	3	328-2300	ADS
Joshi et al. (2009)	3	626-1400	ADS
Bates et al. (2011)	18	6591-6591	ADS
Keith et al. (2011)	9	17000-24000	ADS
Kijak et al. (2011)	15	610-4850	ADS
Lynch et al. (2012)	12	2000-2000	ADS
Mickaliger et al. (2012)	1	820-820	ADS
Boyles et al. (2013)	13	820-820	ADS
Demorest et al. (2013)	17	327-2300	ADS
Dowell et al. (2013)	1	41-81	ADS
Lynch et al. (2013)	10	820-820	ADS
Manchester et al. (2013)	20	700-3100	ADS
Zakharenko et al. (2013)	40	20-25	ADS
Dembska et al. (2014)	19	610-8350	ADS
Stovall et al. (2014)	67	350-820	ADS
Dai et al. (2015)	24	730-3100	ADS
Dembska et al. (2015)	6	610-610	ADS
Kuniyoshi et al. (2015)	10	74-1400	ADS
Lazarus et al. (2015)	127	1375-1375	ADS
Ng et al. (2015)	57	325-1352	ADS
Stovall et al. (2015)	36	35-79	ADS
Basu et al. (2016)	1	325-1280	ADS
Bell et al. (2016)	17	154-154	ADS
Bhattacharyya et al. (2016)	12	322-322	ADS
Bilous et al. (2016)	158	149-149	ADS
Frail et al. (2016)	200	147-147	ADS
Han et al. (2016)	228	1274-1523	ADS
Kondratiev et al. (2016)	48	149-149	ADS
Mikhailov et al. (2016)	2	146-146	ADS
Kijak et al. (2017)	12	325-610	ADS
Mignani et al. (2017)	1	97500-343500	ADS
Murphy et al. (2017)	60	76-227	ADS
Xue et al. (2017)	48	185-185	ADS
Zhao et al. (2017)	26	8600-8600	ADS
Basu et al. (2018)	6	325-1280	ADS
Brinkman et al. (2018)	12	327-1400	ADS
Gentile et al. (2018)	28	430-2100	ADS
Jankowski et al. (2018)	441	728-3100	ADS
Johnston et al. (2018)	586	1360-1360	ADS
RoZko et al. (2018)	2	325-5900	ADS
Aloisi et al. (2019)	4	350-350	ADS
Jankowski et al. (2019)	205	843-843	ADS
Kaur et al. (2019)	1	81-219	ADS
Sanidas et al. (2019)	288	135-135	ADS
Surnis et al. (2019)	3	325-1170	ADS
Titus et al. (2019)	3	1382-1382	ADS
Xie et al. (2019)	32	1369-1369	ADS
Zhang et al. (2019)	3	768-3968	ADS
Zhao et al. (2019)	71	4820-5124	ADS
Bilous et al. (2020)	43	53-63	ADS
Bondonneau et al. (2020)	64	53-65	ADS
Crowter et al. (2020)	1	350-1500	ADS
Curylo et al. (2020)	1	150-150	ADS
McEwen et al. (2020)	670	350-350	ADS
Michilli et al. (2020)	19	129-1532	ADS
Tan et al. (2020)	20	118-1532	ADS
Alam et al. (2021)	47	430-2100	ADS
Bondonneau et al. (2021)	12	50-50	ADS
Han et al. (2021)	201	1250-1250	ADS
Johnston et al. (2021)	44	1369-1369	ADS
Shapiro Albert et al. (2021)	3	430-1500	ADS
Kravtsov et al. (2022)	20	24-24	ADS
Lee et al. (2022)	22	70-352	ADS
Spiewak et al. (2022)	189	1284-1284	ADS
Bhat et al. (2023)	120	154-154	ADS
Gitika et al. (2023)	89	944-1625	ADS

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.

The ATNF catalogue values often record flux density measurements at the nearest standard frequency, which can be inaccurate and should be replaced with the actual value.

The first author and the year in the reference label will help you find the full reference on the ATNF references page. The publication can be added to the catalogue.

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),Flux Density (mJy),Flux Density Uncertainty (mJy)
J0030+0451,150,37.6,4.4
J0030+0451,180,32.4,3.2
J0034-0534,150,202.8,7.9
J0034-0721,150,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),Flux Density (mJy)
J0030+0451,150,37.6
J0030+0451,180,32.4
J0034-0534,150,202.8
J0034-0721,150,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),Flux Density (mJy)
B0037+56,390,3.5
B0045+33,390,4.5
B0052+51,390,3.6
B0053+47,390,5.8

Then move to the scripts subdirectory of the repository and run the command:

python csv_to_yaml.py --csv your_paper.csv --ref author_year

This will put a YAML file of the paper in pulsar_spectra/catalogue_papers/. You should then reinstall the software (python setup.py install) then 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:

1. 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.

2. New results

   If the paper includes flux density measurements from previous publications, do not include them.

3. 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.

4. Flux density uncertainties

   If the paper does not supply a flux density uncertainty, assume a relative uncertainty of 50 %.

5. 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.

1. 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).

2. 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_spectra directory it creates is where you should be working on your changes.

3. Add each paper

   For each paper, perform the following sub-steps

   1. 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/.

   2. Update ADS links

      In the pulsar_spectra/catalogue.py, there is a dictionary called ADS_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",

   3. 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.py

      Then 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.

4. Create a pull request

   Once you have finished adding to the repo, you can push your changes to your GitHub fork using:

   git push

   Then 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:main

   Write a description of the changes you have made and click submit.

5. 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.

6. 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:

{
    "Pulsar Jname": {
        "Frequency MHz":    ["List of frequencies in MHz"],
        "Flux Density mJy": ["List of flux densities in mJy"],
        "Flux Density error mJy": ["List of flux density uncertainties in mJy"]
    }
}

For example:

{
    "J0030+0451": {
        "Frequency MHz": [150.0, 180.0],
        "Flux Density mJy": [ 37.6, 32.4],
        "Flux Density error mJy": [ 4.4, 3.2]
    },
    "J0034-0534": {
        "Frequency MHz": [150.0],
        "Flux Density mJy": [202.8],
        "Flux Density error mJy": [7.9]
    },
}