Creating publication lists for missions using ADS and IDL

This document describes software I wrote in IDL that allow me to create and maintain webpages containing publication information for science instruments and missions. Examples are the Hinode/EIS and IRIS lists that I maintain.

While the described software automates many of the steps, please note that  each paper needs to be manually checked to make sure that it does count as a paper that uses the mission data.

Two useful features of the method are (i) citation data for the papers, and (ii) country breakdown of citing authors. These can be useful information when preparing reports to funding agencies.

Step 0: initial setup

Follow the instructions at my website for downloading an API key from the ADS, and for accessing the IDL software through Solarsoft.

Identify a directory on your computer where you will store the bibliography data files.

Identify a directory where you will store the html files containing the publication lists.

Step 1: create mission information routine

Create a routine that defines a structure giving information about the mission. For example, for the Hinode/EIS instrument I created the routine eis_pub_info.pro, which is called as:

IDL> data_str=eis_pub_info()

Make sure that your structure contains the same tags. The tags are:

INSTR_NAME: the name of the mission/instrument (e.g., 'EIS').
BCODE_INSTR: the ADS bibcode for the paper that describes the mission/instrument.
BIB_SAVE_DIR: the name of a directory used to store the bibliography data.
ABS_SEARCH_STRING: a string used to search paper abstracts for the name of the mission/instrument. See the EIS example for how this is formatted.
HTML_DIR: the directory where you want to put the output html files.
KEYWORDS: (optional) an IDL list containing keywords. These will be used to generate sub-lists of publications that contain the keywords in their abstracts. See eis_pub_info for an example.

Step 2A: create the bibcode lists for each year

If you haven't run the software before, then for each year from the mission start you need to first do:

IDL> cit_instr_check_year,  year=year, data_str=data_str

The software will print a list of "new" publications (everything is considered new since the software wasn't previously run). For each publication there is a link to ADS allowing you to check manually if the paper actually did use the mission data. For publications that don't use the data you should put the bibcodes into the file "bib_save_dir/remove_[YEAR].txt" (for example, "bib_save_dir/remove_2018.txt").

Once you've identified all the "bad" papers and put them in the remove file, you do:

IDL> cit_instr_check_year,  year=year, data_str=data_str, /update

This creates the file "bibcode_list_[YEAR].txt" in the directory "bib_save_dir" (see Step 1).

Step 2B: update the bibcode lists for the current year

If you have run the software before (so that the bibcode lists already exist), and you need to update the publication lists, then first do:

IDL> cit_instr_check_year,  data_str=data_str

(the software automatically uses the current year). The software checks against the existing bibcode list in "bib_save_dir", and determines if there are new papers. Links to the new papers are printed to the IDL screen and so you should check to make sure they use the mission/instrument data. If any don't, then they need to be added to the list in "bib_save_dir/remove_[YEAR].txt".

After you've done this you can then update the existing publication lists by doing:

IDL> cit_instr_check_year,  data_str=data_str, /update

Note that backups of the previous lists are saved in bib_save_dir/backup.

For an old year you can update the publication list by doing:

IDL> cit_instr_check_year,  year=year, data_str=data_str, /update

This can be useful at the start of a new year when you want to check if there are any updates to the previous year.

Step 3: write the html files containing the publication lists

The html files are written to the directory "html_dir" (see Step 1) by doing:

IDL> cit_instr_master_html, data_str

Multiple html files are created, with the main one being [INSTRUMENT]_publications_summary.html.

Criteria for determining if a paper is counted

My basic criterion is that a paper must make use of the instrument's data in an original way. At the simplest level, it may be a single image or line plot obtained from the data that has not been previously published. I generally do not include the following:

• Review papers (unless they include some original data).
• Conference abstracts.
• Modeling papers that do not include mission data, even if they are trying to model results from the mission.
• Preprints, even if the work has been accepted for a journal.
• Papers that describe technical details of the instrument (e.g., detectors, mirrors, etc.).
  

Frequently-asked questions

I don't want the html output, just the data. How do I get this?
If you call cit_instr_master_html with the all_pubs= optional output, then you'll receive a structure containing all of the papers in the publication list. This structure is also saved as an IDL save file in [bib_save_dir]/ads_data/ads_data.save.

There are a lot of missing affiliations. How do I fix this?
By default, the routine extracts affiliations by downloading the cit_affil_country.txt that I keep on my webpage. This provides a mapping between countries and institutes. When the software extracts the affiliation from ADS it searches for the institute string in order to find the country. If the routine cit_affil_country.pro does not find a match, then it prints to the IDL window the problem affiliation. To create your own affiliation mapping file, copy mine to a local directory, then begin adding the affiliations that cit_affil_country.pro complains about. When you call cit_instr_master_html, use the keyword affil_file= to specify the name of your own affiliation file.

Why does the publication list not include preprints?
You can add preprints by giving the /preprints keyword to cit_instr_check_year. I prefer not to do this because I have to check the preprint to see if it belongs to the mission, and then later I have to check the published version when it appears. I prefer to do the check only once.

Why does the list not include a paper that appeared in a physics journal?
I restrict the search to only the astronomy database at ADS. You can search all the databases by adding the keyword /database_all to cit_instr_check_year.

Page maintained by Dr Peter R Young.