A Python toolkit to fetch and visualize the global distribution of your academic citations.

This repository contains two primary modules:

1. citation_fetcher.py: A unified tool to fetch all citations for an author. It supports multiple input methods (OpenAlex ID , ORCID , Google Scholar ID , or local CSV) and always generates an intermediate publication list for your review.
2. create_citation_map.py: A module to generate highly customizable world maps from the fetched citation data.

citation map

1. Clone this repository:

   git clone https://github.com/linjunhe/citation-map.git
   cd citation-map

2. Install the required Python packages:

   pip install -r requirements.txt

The workflow is two steps: fetching data, then creating the map.

You can run citation_fetcher.py from the command line. It is highly recommended to provide your email address for polite API access.

• Logic: Fetches your publication list from the ORCID API.
• DOI Handling: Uses the DOI provided by ORCID if available. If a DOI is missing, it attempts to find it via Crossref based on the publication title.
• Intermediate Output: Saves publications_with_doi_orcid.csv.

python citation_fetcher.py --orcid 0000-0002-XXXX-XXXX --email your_email@example.com

• Logic: Scrapes your publication list from Google Scholar using the scholarly library.
• DOI Handling: Since Google Scholar does not provide DOIs, all DOIs are retrieved via Crossref based on the publication titles.
• Intermediate Output: Saves publications_with_doi_scholar.csv.

python citation_fetcher.py --scholar_id SCHOLAR_ID --email your_email@example.com

• Logic: Directly fetches your work list from OpenAlex. This is the fastest method if you already have your OpenAlex author ID.
• Intermediate Output: Saves publications_with_doi_openalex.csv for your reference.

python citation_fetcher.py --openalex_id A5XXXXXXXX --email your_email@example.com

If you have a CSV file (e.g., my_publications_with_doi.csv) with a column named DOI or doi, you can use it directly.

python citation_fetcher.py --csv my_publications_with_doi.csv --email your_email@example.com

All options generate a citation_info.csv file (output filename can be changed via --output).

(Note: Rows are duplicated for each author and institution associated with a single citing paper.)

Important: The create_citation_map.py script only uses the cited_by_country column to generate the map. The other columns (my_publication, cited_by_institution, etc.) are provided for your own analysis.

Import and call the create_citation_map function in a Python script (e.g., run_demo.py). Point it to the citation_info.csv file generated in Step 1.

This example creates a simple green map with 70% alpha and adds pins that scale in color and size based on the log_rank scale.

from create_citation_map import create_citation_map
# -- Run the map generator --
create_citation_map(
 "citation_info.csv",
 output_filename='map_ex_simple_green_with_pin.png',
 scale='log_rank', # Use rank scale for pins
 fill_mode='simple',
 fill_alpha=0.7,
 fill_color='#B5E48C', # Light green fill
 show_pins=True,
 pin_cmap='YlGn', # Use a green heatmap for pins
 pin_scale_color=True, # Scale pin color
 pin_scale_size=True, # Scale pin size
 pin_scale_alpha=False, # Use static alpha for pins
 pin_size_range=(30, 250),
 show_legend=True,
)

Here are a few other examples to get you started. Please experiment with the settings and share your creations!

Example 1: Simple Mode (Blue)

A simple map showing cited vs. non-cited countries with a solid blue fill and a legend.

create_citation_map(
 "citation_info.csv",
 output_filename='map_ex1_simple_blue.png',
 fill_mode='simple',
 fill_color='#0077B6', # Use a blue fill
 show_legend=True,
)

citation map 1

Example 2: Heatmap Mode (Red) with Pins

A log_rank scaled heatmap using a red colormap, adding dark grey pins with a static size but scaled alpha.

create_citation_map(
 "citation_info.csv",
 output_filename='map_ex2_heatmap_with_Reds_cmap_with_pin.png',
 scale='log_rank',
 fill_mode='heatmap',
 fill_cmap='Reds',
 show_pins=True,
 pin_color='#333333', # Dark grey pins
 pin_scale_alpha=False, # Use static alpha
 show_legend=True,
)

citation map 2

Example 3: Heatmap Mode (Blue) with Labels

A log_rank scaled heatmap using a blue colormap, with country labels.

create_citation_map(
 "citation_info.csv",
 output_filename='map_ex3_heatmap_with_label.png',
 scale='log_rank',
 fill_mode='heatmap',
 fill_cmap='Blues',
 show_labels=True,
 show_legend=True,
)

citation map 3

Example 4: Heatmap Mode (Blue) with Labels & Counts

A log_rank scaled heatmap using a blue colormap, with country labels and counts.

create_citation_map(
 "citation_info.csv",
 output_filename='map_ex4_heatmap_with_label_count.png',
 scale='log_rank',
 fill_mode='heatmap',
 fill_cmap='Blues',
 show_labels=True,
 show_legend=True,
 show_counts=True,
)

citation map 4

Here are all the available parameters for create_citation_map: