PyPI - citation-map - Versions diffs - 4.0__tar.gz → 4.2__tar.gz - Mend

citation-map 4.0tar.gz → 4.2tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

{citation-map-4.0 → citation-map-4.2}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: citation-map
-Version: 4.0
+Version: 4.2
 Summary: A simple tool to generate your Google Scholar citation world map.
 Home-page: https://github.com/ChenLiu-1996/CitationMap
 Author: Chen Liu
@@ -35,7 +35,7 @@ Research areas: Machine Learning, Spatial-Temporal Modeling, Medical Vision, AI4
 **[Asking for advice]**
 1. This is my first time dealing with webscraping/crawling. Users have reported stability issues, and I suspect the major problems are (1) being caught by CAPTCHA or robot check, and (2) being flagged for blacklist by Google Scholar. If you are experienced in these areas and have good advice, I would highly appreciate a GitHub issue or a pull request.
-[Aug 2, 2024] Version 4.0 released >>> Logic update. A new input argument `affiliation_conservative`. If true, we will use **a very conservative approach for identifying affiliations** which lead to **very high precision and lower recall**. Many thanks to [Zhijian Liu](https://github.com/zhijian-liu) for the [helpful discussion](https://github.com/ChenLiu-1996/CitationMap/issues/8).
+[Aug 2, 2024] Version 4.0 released >>> Logic update. A new input argument `affiliation_conservative`. If set to True, we will use **a very conservative approach to identify affiliations** which leads to **much higher precision and lower recall**. Many thanks to [Zhijian Liu](https://github.com/zhijian-liu) for the [helpful discussion](https://github.com/ChenLiu-1996/CitationMap/issues/8).
 [Jul 28, 2024] Version 3.10 released >>> Logic update. Tested on a professor's profile **with 10,000 citations**!
@@ -55,13 +55,13 @@ You will be given an **HTML file** as the output of the script.
 If you open it on a browser, you will see your own version of the following citation world map.
+<img src = "assets/citation_world_map.png" width=800>
 Besides, there will be a **CSV file** recording citation information (citing author, citing paper, cited paper, affiliation, detailed location).
 **Disclaimer:** It is reasonable for this tool to make some minor mistakes: missing a few citing authors, dropping a couple of pins in wrong locations, etc. If you care a lot about ensuring all citing authors' affiliations are included and accurately marked, you could try manually annotating on [Google My Maps](https://www.google.com/maps/d/) instead. This tool is meant to help people who cannot tolerate this painful process, especailly when they have a decent number of citations.
-**NOTE:** **Now you can trade off between affiliation precision and recall** by leveraging the `affiliation_conservative` option. If set to True, we will use the Google Scholar verified official organization name from the citing authors. This is a very conservative approach, since (1) the author needs to self-report it in the affiliation panel, (2) the author needs to verify with the matching email address, and (3) the organization needs to be recorded by Google Scholar. For example, Meta (the company) is not in the list.
-<img src = "assets/citation_world_map.png" width=800>
+**NOTE:** **Now you can trade off between affiliation precision and recall** with the `affiliation_conservative` option. If set to True, we will use the Google Scholar verified official organization name from the citing authors. This is a very conservative approach, since (1) the author needs to self-report it in the affiliation panel, (2) the author needs to verify with the matching email address, and (3) the organization needs to be recorded by Google Scholar. For example, Meta (the company) is not in the list. Many thanks to [Zhijian Liu](https://github.com/zhijian-liu) for the [helpful discussion](https://github.com/ChenLiu-1996/CitationMap/issues/8).
 ## User Guide
@@ -90,6 +90,8 @@ Besides, there will be a **CSV file** recording citation information (citing aut
         generate_citation_map(scholar_id)
     ```
+    Note that in Version 4.0, we will cache the results before identifying affiliations. So if you want to rerun the same author from scratch, you need to delete the cache (default location is 'cache').
     More input arguments are shown in [the demo script](https://github.com/ChenLiu-1996/CitationMap/blob/main/demo/demo.py).
     You can take a look at the input arguments (listed below) of the function `generate_citation_map` in case you need those functionalities.
@@ -107,13 +109,13 @@ Besides, there will be a **CSV file** recording citation information (citing aut
         The path to the output csv file.
     cache_folder: str
         (default is 'cache')
-        The folder to save intermediate results,
-        after finding (author, paper) but before finding the affiliations.
+        The folder to save intermediate results, after finding (author, paper) but before finding the affiliations.
         This is because the user might want to try the aggressive vs. conservative approach.
+        Set to None if you do not want caching.
     affiliation_conservative: bool
         (default is False)
-        If true, we will use a more conservative approach for identifying affiliations.
-        If false, we will use a more aggressive approach for identifying affiliations.
+        If true, we will use a more conservative approach to identify affiliations.
+        If false, we will use a more aggressive approach to identify affiliations.
     num_processes: int
         (default is 16)
         Number of processes for parallel processing.
@@ -148,9 +150,9 @@ Besides, there will be a **CSV file** recording citation information (citing aut
 ## Debug
-1. `MaxTriesExceededException` or (`[WARNING!] Blocked by CAPTCHA or robot check` for all entries).
+1. `MaxTriesExceededException` or `Exception: Failed to fetch the Google Scholar page` or (`[WARNING!] Blocked by CAPTCHA or robot check` for all entries).
-    - From my experience, both are good indicators that your IP address is blocked by Google Scholar due to excessive crawling (using the `scholarly` package).
+    - From my experience, these are good indicators that your IP address is blocked by Google Scholar due to excessive crawling (using the `scholarly` package).
     - One hot fix I found was to hop on a University VPN and run again. I typically experience this error after running the tool twice, and I need to disconnect and reconnect my VPN to "unblock" myself.
     - In case this does not help, you can try to change IP adress and reduce the number of processes (e.g., setting `num_processes=1`).
     - If you get `[WARNING!] Blocked by CAPTCHA or robot check` no more than several times, it's not a big deal especially if you have many citing authors.
@@ -174,7 +176,16 @@ Besides, there will be a **CSV file** recording citation information (citing aut
       ```
 ## Changelog
-[![Star History Chart](https://api.star-history.com/svg?repos=ChenLiu-1996/CitationMap&type=Date)](https://star-history.com/#ChenLiu-1996/CitationMap&Date)
+<details>
+<summary>Version 4.0 (Aug 2, 2024)</summary>
+<br>
+1. **Now you can trade off between precision and recall as we identify the affiliations.**
+2. Added caching before identifying the affiliations, since users might want to try both the conservative and aggressive approaches.
+3. Slight optimization in the affiliation to geocode stage by adding early breaking if successful.
+</details>
 <details>
 <summary>Version 3.11 (Jul 28, 2024)</summary>

{citation-map-4.0 → citation-map-4.2}/README.md RENAMED Viewed

@@ -19,7 +19,7 @@ Research areas: Machine Learning, Spatial-Temporal Modeling, Medical Vision, AI4
 **[Asking for advice]**
 1. This is my first time dealing with webscraping/crawling. Users have reported stability issues, and I suspect the major problems are (1) being caught by CAPTCHA or robot check, and (2) being flagged for blacklist by Google Scholar. If you are experienced in these areas and have good advice, I would highly appreciate a GitHub issue or a pull request.
-[Aug 2, 2024] Version 4.0 released >>> Logic update. A new input argument `affiliation_conservative`. If true, we will use **a very conservative approach for identifying affiliations** which lead to **very high precision and lower recall**. Many thanks to [Zhijian Liu](https://github.com/zhijian-liu) for the [helpful discussion](https://github.com/ChenLiu-1996/CitationMap/issues/8).
+[Aug 2, 2024] Version 4.0 released >>> Logic update. A new input argument `affiliation_conservative`. If set to True, we will use **a very conservative approach to identify affiliations** which leads to **much higher precision and lower recall**. Many thanks to [Zhijian Liu](https://github.com/zhijian-liu) for the [helpful discussion](https://github.com/ChenLiu-1996/CitationMap/issues/8).
 [Jul 28, 2024] Version 3.10 released >>> Logic update. Tested on a professor's profile **with 10,000 citations**!
@@ -39,13 +39,13 @@ You will be given an **HTML file** as the output of the script.
 If you open it on a browser, you will see your own version of the following citation world map.
+<img src = "assets/citation_world_map.png" width=800>
 Besides, there will be a **CSV file** recording citation information (citing author, citing paper, cited paper, affiliation, detailed location).
 **Disclaimer:** It is reasonable for this tool to make some minor mistakes: missing a few citing authors, dropping a couple of pins in wrong locations, etc. If you care a lot about ensuring all citing authors' affiliations are included and accurately marked, you could try manually annotating on [Google My Maps](https://www.google.com/maps/d/) instead. This tool is meant to help people who cannot tolerate this painful process, especailly when they have a decent number of citations.
-**NOTE:** **Now you can trade off between affiliation precision and recall** by leveraging the `affiliation_conservative` option. If set to True, we will use the Google Scholar verified official organization name from the citing authors. This is a very conservative approach, since (1) the author needs to self-report it in the affiliation panel, (2) the author needs to verify with the matching email address, and (3) the organization needs to be recorded by Google Scholar. For example, Meta (the company) is not in the list.
-<img src = "assets/citation_world_map.png" width=800>
+**NOTE:** **Now you can trade off between affiliation precision and recall** with the `affiliation_conservative` option. If set to True, we will use the Google Scholar verified official organization name from the citing authors. This is a very conservative approach, since (1) the author needs to self-report it in the affiliation panel, (2) the author needs to verify with the matching email address, and (3) the organization needs to be recorded by Google Scholar. For example, Meta (the company) is not in the list. Many thanks to [Zhijian Liu](https://github.com/zhijian-liu) for the [helpful discussion](https://github.com/ChenLiu-1996/CitationMap/issues/8).
 ## User Guide
@@ -74,6 +74,8 @@ Besides, there will be a **CSV file** recording citation information (citing aut
         generate_citation_map(scholar_id)
     ```
+    Note that in Version 4.0, we will cache the results before identifying affiliations. So if you want to rerun the same author from scratch, you need to delete the cache (default location is 'cache').
     More input arguments are shown in [the demo script](https://github.com/ChenLiu-1996/CitationMap/blob/main/demo/demo.py).
     You can take a look at the input arguments (listed below) of the function `generate_citation_map` in case you need those functionalities.
@@ -91,13 +93,13 @@ Besides, there will be a **CSV file** recording citation information (citing aut
         The path to the output csv file.
     cache_folder: str
         (default is 'cache')
-        The folder to save intermediate results,
-        after finding (author, paper) but before finding the affiliations.
+        The folder to save intermediate results, after finding (author, paper) but before finding the affiliations.
         This is because the user might want to try the aggressive vs. conservative approach.
+        Set to None if you do not want caching.
     affiliation_conservative: bool
         (default is False)
-        If true, we will use a more conservative approach for identifying affiliations.
-        If false, we will use a more aggressive approach for identifying affiliations.
+        If true, we will use a more conservative approach to identify affiliations.
+        If false, we will use a more aggressive approach to identify affiliations.
     num_processes: int
         (default is 16)
         Number of processes for parallel processing.
@@ -132,9 +134,9 @@ Besides, there will be a **CSV file** recording citation information (citing aut
 ## Debug
-1. `MaxTriesExceededException` or (`[WARNING!] Blocked by CAPTCHA or robot check` for all entries).
+1. `MaxTriesExceededException` or `Exception: Failed to fetch the Google Scholar page` or (`[WARNING!] Blocked by CAPTCHA or robot check` for all entries).
-    - From my experience, both are good indicators that your IP address is blocked by Google Scholar due to excessive crawling (using the `scholarly` package).
+    - From my experience, these are good indicators that your IP address is blocked by Google Scholar due to excessive crawling (using the `scholarly` package).
     - One hot fix I found was to hop on a University VPN and run again. I typically experience this error after running the tool twice, and I need to disconnect and reconnect my VPN to "unblock" myself.
     - In case this does not help, you can try to change IP adress and reduce the number of processes (e.g., setting `num_processes=1`).
     - If you get `[WARNING!] Blocked by CAPTCHA or robot check` no more than several times, it's not a big deal especially if you have many citing authors.
@@ -158,7 +160,16 @@ Besides, there will be a **CSV file** recording citation information (citing aut
       ```
 ## Changelog
-[![Star History Chart](https://api.star-history.com/svg?repos=ChenLiu-1996/CitationMap&type=Date)](https://star-history.com/#ChenLiu-1996/CitationMap&Date)
+<details>
+<summary>Version 4.0 (Aug 2, 2024)</summary>
+<br>
+1. **Now you can trade off between precision and recall as we identify the affiliations.**
+2. Added caching before identifying the affiliations, since users might want to try both the conservative and aggressive approaches.
+3. Slight optimization in the affiliation to geocode stage by adding early breaking if successful.
+</details>
 <details>
 <summary>Version 3.11 (Jul 28, 2024)</summary>

{citation-map-4.0 → citation-map-4.2}/citation_map/citation_map.py RENAMED Viewed

@@ -19,18 +19,16 @@ from typing import Any, Iterable, List, Tuple
 from .scholarly_support import get_citing_author_ids_and_citing_papers, get_organization_name
-def fetch_google_scholar_profile(scholar_id: str):
+def find_all_citing_authors(scholar_id: str, num_processes: int = 16) -> List[Tuple[str]]:
     '''
-    Step 1: Fetch Google Scholar Profile using Scholar ID.
+    Step 1. Find all citing authors.
     '''
+    # Find Google Scholar Profile using Scholar ID.
     author = scholarly.search_author_id(scholar_id)
     author = scholarly.fill(author, sections=['publications'])
-    return author
+    publications = author['publications']
+    print('Author profile found, with %d publications.\n' % len(publications))
-def find_all_citing_authors(publications: Iterable, num_processes: int = 16) -> List[Tuple[str]]:
-    '''
-    Step 2. Find all citing authors.
-    '''
     # Fetch metadata for all publications.
     if num_processes > 1 and isinstance(num_processes, int):
         with Pool(processes=num_processes) as pool:
@@ -72,7 +70,7 @@ def find_all_citing_affiliations(all_citing_author_paper_tuple_list: List[Tuple[
                                  num_processes: int = 16,
                                  affiliation_conservative: bool = False):
     '''
-    Step 3. Find all citing affiliations.
+    Step 2. Find all citing affiliations.
     '''
     if affiliation_conservative:
         __affiliations_from_authors = __affiliations_from_authors_conservative
@@ -98,7 +96,7 @@ def find_all_citing_affiliations(all_citing_author_paper_tuple_list: List[Tuple[
 def clean_affiliation_names(author_paper_affiliation_tuple_list: List[Tuple[str]]) -> List[Tuple[str]]:
     '''
-    Step 4 (Optional). Clean up the names of affiliations from the authors' affiliation tab on their Google Scholar profiles.
+    Step 3 (Optional). Clean up the names of affiliations from the authors' affiliation tab on their Google Scholar profiles.
     NOTE: This logic is very naive. Please send an issue or pull request if you have any idea how to improve it.
     Currently we will not consider any paid service or tools that pose extra burden on the users, such as GPT API.
     '''
@@ -125,7 +123,7 @@ def clean_affiliation_names(author_paper_affiliation_tuple_list: List[Tuple[str]
 def affiliation_text_to_geocode(author_paper_affiliation_tuple_list: List[Tuple[str]], max_attempts: int = 3) -> List[Tuple[str]]:
     '''
-    Step 5: Convert affiliations in plain text to Geocode.
+    Step 4: Convert affiliations in plain text to Geocode.
     '''
     coordinates_and_info = []
     # NOTE: According to the Nomatim Usage Policy (https://operations.osmfoundation.org/policies/nominatim/),
@@ -181,7 +179,7 @@ def affiliation_text_to_geocode(author_paper_affiliation_tuple_list: List[Tuple[
 def create_map(coordinates_and_info: List[Tuple[str]], pin_colorful: bool = True):
     '''
-    Step 6.1: Create the Citation World Map.
+    Step 5.1: Create the Citation World Map.
     For authors under the same affiliations, they will be displayed in the same pin.
     '''
@@ -221,7 +219,7 @@ def create_map(coordinates_and_info: List[Tuple[str]], pin_colorful: bool = True
 def export_csv(coordinates_and_info: List[Tuple[str]], csv_output_path: str) -> None:
     '''
-    Step 6.2: Export csv file recording citation information.
+    Step 5.2: Export csv file recording citation information.
     '''
     citation_df = pd.DataFrame(coordinates_and_info,
@@ -351,13 +349,13 @@ def generate_citation_map(scholar_id: str,
         The path to the output csv file.
     cache_folder: str
         (default is 'cache')
-        The folder to save intermediate results,
-        after finding (author, paper) but before finding the affiliations.
+        The folder to save intermediate results, after finding (author, paper) but before finding the affiliations.
         This is because the user might want to try the aggressive vs. conservative approach.
+        Set to None if you do not want caching.
     affiliation_conservative: bool
         (default is False)
-        If true, we will use a more conservative approach for identifying affiliations.
-        If false, we will use a more aggressive approach for identifying affiliations.
+        If true, we will use a more conservative approach to identify affiliations.
+        If false, we will use a more aggressive approach to identify affiliations.
     num_processes: int
         (default is 16)
         Number of processes for parallel processing.
@@ -380,30 +378,31 @@ def generate_citation_map(scholar_id: str,
         scholarly.use_proxy(pg)
         print('Using proxy.')
-    cache_path = os.path.join(cache_folder, scholar_id, 'all_citing_author_paper_tuple_list.pkl')
-    if not os.path.exists(cache_path):
-        print('No cache found for this author. Running from scratch.')
+    if cache_folder is not None:
+        cache_path = os.path.join(cache_folder, scholar_id, 'all_citing_author_paper_tuple_list.pkl')
+    else:
+        cache_path = None
-        # NOTE: Step 1. Fetch Google Scholar profile.
-        author_profile = fetch_google_scholar_profile(scholar_id)
+    if cache_path is None or not os.path.exists(cache_path):
+        print('No cache found for this author. Running from scratch.\n')
-        # NOTE: Step 2. Find all citing authors.
-        print('\nAuthor profile found, with %d publications.\n' % len(author_profile['publications']))
-        all_citing_author_paper_tuple_list = find_all_citing_authors(author_profile['publications'],
+        # NOTE: Step 1. Find all citing authors.
+        all_citing_author_paper_tuple_list = find_all_citing_authors(scholar_id=scholar_id,
                                                                      num_processes=num_processes)
-        print('\nA total of %d citing authors recorded.\n' % len(all_citing_author_paper_tuple_list))
-        save_cache(all_citing_author_paper_tuple_list, cache_path)
-        print('Saved to cache: %s.' % cache_path)
+        print('A total of %d citing authors recorded.\n' % len(all_citing_author_paper_tuple_list))
+        if cache_path is not None and len(all_citing_author_paper_tuple_list) > 0:
+            save_cache(all_citing_author_paper_tuple_list, cache_path)
+        print('Saved to cache: %s.\n' % cache_path)
     else:
         print('Cache found. Loading author paper affiliation information from cache.\n')
-        # NOTE: Step 1 & 2. Load all citing authors.
+        # NOTE: Step 1. Load all citing authors.
         all_citing_author_paper_tuple_list = load_cache(cache_path)
-        print('Loaded from cache: %s.' % cache_path)
-        print('\nA total of %d citing authors loaded.\n' % len(all_citing_author_paper_tuple_list))
+        print('Loaded from cache: %s.\n' % cache_path)
+        print('A total of %d citing authors loaded.\n' % len(all_citing_author_paper_tuple_list))
-    # NOTE: Step 3. Find all citing affiliations.
+    # NOTE: Step 2. Find all citing affiliations.
     print('Identifying affiliations using the %s approach.' % ('conservative' if affiliation_conservative else 'aggressive'))
     author_paper_affiliation_tuple_list = find_all_citing_affiliations(all_citing_author_paper_tuple_list,
                                                                        num_processes=num_processes,
@@ -412,36 +411,36 @@ def generate_citation_map(scholar_id: str,
     # Take unique tuples.
     author_paper_affiliation_tuple_list = list(set(author_paper_affiliation_tuple_list))
-    # NOTE: Step 4. Clean the affiliation strings (optional, only used if taking the aggressive approach).
+    # NOTE: Step 3. Clean the affiliation strings (optional, only used if taking the aggressive approach).
     if print_citing_affiliations:
         if affiliation_conservative:
             print('Taking the conservative approach. Will not need to clean the affiliation names.')
             print('List of all citing authors and affiliations:\n')
         else:
-            print('\nTaking the aggressive approach. Cleaning the affiliation names.')
+            print('Taking the aggressive approach. Cleaning the affiliation names.')
             print('List of all citing authors and affiliations before cleaning:\n')
         __print_author_and_affiliation(author_paper_affiliation_tuple_list)
     if not affiliation_conservative:
         cleaned_author_paper_affiliation_tuple_list = clean_affiliation_names(author_paper_affiliation_tuple_list)
         if print_citing_affiliations:
-            print('\nList of all citing authors and affiliations after cleaning:\n')
+            print('List of all citing authors and affiliations after cleaning:\n')
             __print_author_and_affiliation(cleaned_author_paper_affiliation_tuple_list)
         # Use the merged set to maximize coverage.
         author_paper_affiliation_tuple_list += cleaned_author_paper_affiliation_tuple_list
         # Take unique tuples.
         author_paper_affiliation_tuple_list = list(set(author_paper_affiliation_tuple_list))
-    # NOTE: Step 5. Convert affiliations in plain text to Geocode.
+    # NOTE: Step 4. Convert affiliations in plain text to Geocode.
     coordinates_and_info = affiliation_text_to_geocode(author_paper_affiliation_tuple_list)
     # Take unique tuples.
     coordinates_and_info = list(set(coordinates_and_info))
-    # NOTE: Step 6.1. Create the citation world map.
+    # NOTE: Step 5.1. Create the citation world map.
     citation_map = create_map(coordinates_and_info, pin_colorful=pin_colorful)
     citation_map.save(output_path)
     print('\nMap created and saved at %s.\n' % output_path)
-    # NOTE: Step 6.2. Export csv file recording citation information.
+    # NOTE: Step 5.2. Export csv file recording citation information.
     export_csv(coordinates_and_info, csv_output_path)
     print('\nCitation information exported to %s.' % csv_output_path)
     return

{citation-map-4.0 → citation-map-4.2}/citation_map.egg-info/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: citation-map
-Version: 4.0
+Version: 4.2
 Summary: A simple tool to generate your Google Scholar citation world map.
 Home-page: https://github.com/ChenLiu-1996/CitationMap
 Author: Chen Liu
@@ -35,7 +35,7 @@ Research areas: Machine Learning, Spatial-Temporal Modeling, Medical Vision, AI4
 **[Asking for advice]**
 1. This is my first time dealing with webscraping/crawling. Users have reported stability issues, and I suspect the major problems are (1) being caught by CAPTCHA or robot check, and (2) being flagged for blacklist by Google Scholar. If you are experienced in these areas and have good advice, I would highly appreciate a GitHub issue or a pull request.
-[Aug 2, 2024] Version 4.0 released >>> Logic update. A new input argument `affiliation_conservative`. If true, we will use **a very conservative approach for identifying affiliations** which lead to **very high precision and lower recall**. Many thanks to [Zhijian Liu](https://github.com/zhijian-liu) for the [helpful discussion](https://github.com/ChenLiu-1996/CitationMap/issues/8).
+[Aug 2, 2024] Version 4.0 released >>> Logic update. A new input argument `affiliation_conservative`. If set to True, we will use **a very conservative approach to identify affiliations** which leads to **much higher precision and lower recall**. Many thanks to [Zhijian Liu](https://github.com/zhijian-liu) for the [helpful discussion](https://github.com/ChenLiu-1996/CitationMap/issues/8).
 [Jul 28, 2024] Version 3.10 released >>> Logic update. Tested on a professor's profile **with 10,000 citations**!
@@ -55,13 +55,13 @@ You will be given an **HTML file** as the output of the script.
 If you open it on a browser, you will see your own version of the following citation world map.
+<img src = "assets/citation_world_map.png" width=800>
 Besides, there will be a **CSV file** recording citation information (citing author, citing paper, cited paper, affiliation, detailed location).
 **Disclaimer:** It is reasonable for this tool to make some minor mistakes: missing a few citing authors, dropping a couple of pins in wrong locations, etc. If you care a lot about ensuring all citing authors' affiliations are included and accurately marked, you could try manually annotating on [Google My Maps](https://www.google.com/maps/d/) instead. This tool is meant to help people who cannot tolerate this painful process, especailly when they have a decent number of citations.
-**NOTE:** **Now you can trade off between affiliation precision and recall** by leveraging the `affiliation_conservative` option. If set to True, we will use the Google Scholar verified official organization name from the citing authors. This is a very conservative approach, since (1) the author needs to self-report it in the affiliation panel, (2) the author needs to verify with the matching email address, and (3) the organization needs to be recorded by Google Scholar. For example, Meta (the company) is not in the list.
-<img src = "assets/citation_world_map.png" width=800>
+**NOTE:** **Now you can trade off between affiliation precision and recall** with the `affiliation_conservative` option. If set to True, we will use the Google Scholar verified official organization name from the citing authors. This is a very conservative approach, since (1) the author needs to self-report it in the affiliation panel, (2) the author needs to verify with the matching email address, and (3) the organization needs to be recorded by Google Scholar. For example, Meta (the company) is not in the list. Many thanks to [Zhijian Liu](https://github.com/zhijian-liu) for the [helpful discussion](https://github.com/ChenLiu-1996/CitationMap/issues/8).
 ## User Guide
@@ -90,6 +90,8 @@ Besides, there will be a **CSV file** recording citation information (citing aut
         generate_citation_map(scholar_id)
     ```
+    Note that in Version 4.0, we will cache the results before identifying affiliations. So if you want to rerun the same author from scratch, you need to delete the cache (default location is 'cache').
     More input arguments are shown in [the demo script](https://github.com/ChenLiu-1996/CitationMap/blob/main/demo/demo.py).
     You can take a look at the input arguments (listed below) of the function `generate_citation_map` in case you need those functionalities.
@@ -107,13 +109,13 @@ Besides, there will be a **CSV file** recording citation information (citing aut
         The path to the output csv file.
     cache_folder: str
         (default is 'cache')
-        The folder to save intermediate results,
-        after finding (author, paper) but before finding the affiliations.
+        The folder to save intermediate results, after finding (author, paper) but before finding the affiliations.
         This is because the user might want to try the aggressive vs. conservative approach.
+        Set to None if you do not want caching.
     affiliation_conservative: bool
         (default is False)
-        If true, we will use a more conservative approach for identifying affiliations.
-        If false, we will use a more aggressive approach for identifying affiliations.
+        If true, we will use a more conservative approach to identify affiliations.
+        If false, we will use a more aggressive approach to identify affiliations.
     num_processes: int
         (default is 16)
         Number of processes for parallel processing.
@@ -148,9 +150,9 @@ Besides, there will be a **CSV file** recording citation information (citing aut
 ## Debug
-1. `MaxTriesExceededException` or (`[WARNING!] Blocked by CAPTCHA or robot check` for all entries).
+1. `MaxTriesExceededException` or `Exception: Failed to fetch the Google Scholar page` or (`[WARNING!] Blocked by CAPTCHA or robot check` for all entries).
-    - From my experience, both are good indicators that your IP address is blocked by Google Scholar due to excessive crawling (using the `scholarly` package).
+    - From my experience, these are good indicators that your IP address is blocked by Google Scholar due to excessive crawling (using the `scholarly` package).
     - One hot fix I found was to hop on a University VPN and run again. I typically experience this error after running the tool twice, and I need to disconnect and reconnect my VPN to "unblock" myself.
     - In case this does not help, you can try to change IP adress and reduce the number of processes (e.g., setting `num_processes=1`).
     - If you get `[WARNING!] Blocked by CAPTCHA or robot check` no more than several times, it's not a big deal especially if you have many citing authors.
@@ -174,7 +176,16 @@ Besides, there will be a **CSV file** recording citation information (citing aut
       ```
 ## Changelog
-[![Star History Chart](https://api.star-history.com/svg?repos=ChenLiu-1996/CitationMap&type=Date)](https://star-history.com/#ChenLiu-1996/CitationMap&Date)
+<details>
+<summary>Version 4.0 (Aug 2, 2024)</summary>
+<br>
+1. **Now you can trade off between precision and recall as we identify the affiliations.**
+2. Added caching before identifying the affiliations, since users might want to try both the conservative and aggressive approaches.
+3. Slight optimization in the affiliation to geocode stage by adding early breaking if successful.
+</details>
 <details>
 <summary>Version 3.11 (Jul 28, 2024)</summary>

{citation-map-4.0 → citation-map-4.2}/setup.py RENAMED Viewed

@@ -5,7 +5,7 @@ with open('README.md') as f:
 setup(
     name='citation-map',
-    version='4.0',
+    version='4.2',
     license='CC BY-NC-SA',
     author='Chen Liu',
     author_email='chen.liu.cl2482@yale.edu',