cleanBib.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "kernel": "SoS"
   },
   "source": [
    "# Clean Bibliography\n",
    "\n",
    "To goal of this notebook is to clean your `.bib` file to ensure that it only contains the full first names of references that you have cited in your paper. The full first names will then be used to query the probabilistic gender classifier, [Gender API](https://gender-api.com). The full names will be used to query for probabilistic race using the [ethnicolr package](https://ethnicolr.readthedocs.io/).\n",
    "\n",
    "The only required file you need is your manuscript's bibliography in `.bib` format. __Your `.bib` must only contain references cited in the manuscript__. Otherwise, the estimated proportions will be inaccurate.\n",
    "\n",
    "If you intend to analyze the reference list of a published paper instead of your own manuscript in progress, search the paper on [Web of Knowledge](http://apps.webofknowledge.com/) (you will need institutional access). Next, [download the .bib file from Web of Science following these instructions, but start from Step 4 and on Step 6 select BibTeX instead of Plain Text](https://github.com/jdwor/gendercitation/blob/master/Step0_PullingWOSdata.pdf).\n",
    "\n",
    "If you are not using LaTeX, collect and organize only the references you have cited in your manuscript using your reference manager of choice (e.g. Mendeley, Zotero, EndNote, ReadCube, etc.) and export that selected bibliography as a `.bib` file. __Please try to export your .bib in an output style that uses full first names (rather than only first initials) and using the full author lists (rather than abbreviated author lists with \"et al.\").__ If first initials are included, our code will automatically retrieve about 70% of those names using the article title or DOI. \n",
    "\n",
    "   * [Export `.bib` from Mendeley](https://blog.mendeley.com/2011/10/25/howto-use-mendeley-to-create-citations-using-latex-and-bibtex/)\n",
    "   * [Export `.bib` from Zotero](https://libguides.mit.edu/ld.php?content_id=34248570)\n",
    "   * [Export `.bib` from EndNote](https://www.reed.edu/cis/help/LaTeX/EndNote.html). Note: Please export full first names by either [choosing an output style that does so by default (e.g. in MLA style)](https://canterbury.libguides.com/endnote/basics-output) or by [customizing an output style.](http://bibliotek.usn.no/cite-and-write/endnote/how-to-use/how-to-show-the-author-s-full-name-in-the-reference-list-article185897-28181.html)\n",
    "   * [Export `.bib` from Read Cube Papers](https://support.papersapp.com/support/solutions/articles/30000024634-how-can-i-export-references-from-readcube-papers-)\n",
    "\n",
    "For those working in LaTeX, we can use an optional `.aux` file to automatically filter your `.bib` to check that it only contains entries which are cited in your manuscript.\n",
    "\n",
    "| Input                 | Output                                                                                                                        |\n",
    "|-----------------------|-------------------------------------------------------------------------------------------------------------------------------|\n",
    "| `.bib` file(s)**(REQUIRED)**    | `cleanBib.csv`: table of author first names, titles, and .bib keys                                                            |\n",
    "| `.aux` file (OPTIONAL)| `predictions.csv`: table of author first names, estimated gender classification, and confidence                                   |\n",
    "| `.tex` file (OPTIONAL) | `race_gender_citations.pdf`: heat map of your citations broken down by probabilistic gender and race estimations\n",
    "|                       | `yourTexFile_gendercolor.tex`: your `.tex` file modified to compile .pdf with in-line citations colored-coded by gender pairs |\n",
    "\n",
    "## 1. Import functions\n",
    "\n",
    "Upload your `.bib` file(s) and _optionally_ an `.aux` file generated from compiling your LaTeX manuscript and your `.tex` file\n",
    "\n",
    "![upload button](img/upload.png)\n",
    "\n",
    "![confirm upload button](img/confirmUpload.png)\n",
    "\n",
    "Then, run the code block below. (click to select the block and then press Ctrl+Enter; or click the block and press the Run button in the top menubar)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "kernel": "Python 3"
   },
   "outputs": [],
   "source": [
    "import glob\n",
    "from habanero import Crossref\n",
    "import sys\n",
    "import os\n",
    "from pathlib import Path\n",
    "wd = Path(os.getcwd())\n",
    "sys.path.insert(1, f'{wd.absolute()}/utils')\n",
    "from preprocessing import *\n",
    "from ethnicolr import pred_fl_reg_name\n",
    "os.environ[\"TF_CPP_MIN_LOG_LEVEL\"] = \"3\"\n",
    "import tensorflow as tf\n",
    "import seaborn as sns\n",
    "import matplotlib.pyplot as plt\n",
    "np.warnings.filterwarnings('ignore', category=np.VisibleDeprecationWarning)\n",
    "import warnings\n",
    "warnings.simplefilter(action='ignore', category=FutureWarning)\n",
    "\n",
    "cr = Crossref()\n",
    "homedir = '/home/jovyan/'\n",
    "bib_files = glob.glob(homedir + '*.bib')\n",
    "paper_aux_file = glob.glob(homedir + '*.aux')\n",
    "paper_bib_file = 'library_paper.bib'\n",
    "try:\n",
    "    tex_file = glob.glob(homedir + \"*.tex\")[0]\n",
    "except:\n",
    "    print('No optional .tex file found.')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "kernel": "SoS"
   },
   "source": [
    "### 2. Define the _first_ and _last_ author of your paper.\n",
    "\n",
    "For example: \n",
    "```\n",
    "yourFirstAuthor = 'Teich, Erin G.'\n",
    "yourLastAuthor = 'Bassett, Danielle S.'\n",
    "```\n",
    "\n",
    "And optionally, define any co-first or co-last author(s), making sure to keep the square brackets to define a list.\n",
    "\n",
    "For example:\n",
    "```\n",
    "optionalEqualContributors = ['Dworkin, Jordan', 'Stiso, Jennifer']\n",
    "```\n",
    "\n",
    "or \n",
    "\n",
    "```\n",
    "optionalEqualContributors = ['Dworkin, Jordan']\n",
    "```\n",
    "\n",
    "If you are analyzing published papers' reference lists from Web of Science, change the variable checkingPublishedArticle to True:\n",
    "```\n",
    "checkingPublishedArticle = True\n",
    "```\n",
    "\n",
    "Then, run the code block below. (click to select the block and then press Ctrl+Enter; or click the block and press the Run button in the top menubar)\n",
    "\n",
    "__NOTE__: Please edit your .bib file using information printed by the code and provided in cleanedBib.csv. Edit directly within the Binder environment by clicking the .bib file (as shown below), making modifications, and saving the file (as shown below).\n",
    "\n",
    "![open button](img/openBib.png)\n",
    "\n",
    "![save button](img/saveBib.png)\n",
    "\n",
    "Common issues include:\n",
    "\n",
    "* Bibliography entry did not include a last author because the author list was truncated by \"and Others\" or \"et al.\"\n",
    "* Some older journals articles only provide first initial and not full first names, in which case you will need to go digging via Google to identify that person.\n",
    "* In rare cases where the author cannot be identified even after searching by hand, replace the first name with \"UNKNOWNNAMES\" so that the classifier will estimate the gender as unknown."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "kernel": "Python 3"
   },
   "outputs": [],
   "source": [
    "yourFirstAuthor = 'LastName, FirstName OptionalMiddleInitial'\n",
    "yourLastAuthor = 'LastName, FirstName OptionalMiddleInitial'\n",
    "optionalEqualContributors = ['LastName, FirstName OptionalMiddleInitial', 'LastName, FirstName OptionalMiddleInitial']\n",
    "checkingPublishedArticle = False\n",
    "\n",
    "if paper_aux_file:\n",
    "    find_unused_cites(paper_aux_file)\n",
    "\n",
    "bib_data = get_bib_data(bib_files[0])\n",
    "if checkingPublishedArticle:\n",
    "    get_names_published(homedir, bib_data, cr)\n",
    "else:\n",
    "    # find and print duplicates\n",
    "    bib_data = get_duplicates(bib_data, bib_files[0])\n",
    "    # get names, remove CDS, find self cites\n",
    "    get_names(homedir, bib_data, yourFirstAuthor, yourLastAuthor, optionalEqualContributors, cr)\n",
    "    \n",
    "bib_check(homedir)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Estimate gender and race of authors from cleaned bibliography\n",
    "\n",
    "### Checkpoint for cleaned bibliography and using Gender API to estimate genders and race by names\n",
    "After registering for a [gender-api](https://gender-api.com/) account (free), use your 500 free monthly search credits by __pasting your API key in the code for the line indicated below__ (replace only YOUR ACCOUNT KEY HERE):\n",
    "\n",
    "```genderAPI_key = '&key=YOUR ACCOUNT KEY HERE'```\n",
    "\n",
    "[You can find your key in your account's profile page.](https://gender-api.com/en/account/overview#my-api-key)\n",
    "\n",
    "Then, run the code blocks below to estimate how many credits we will need to use. (click to select the block and then press Ctrl+Enter; or click the block and press the Run button in the top menubar)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "kernel": "R"
   },
   "outputs": [],
   "source": [
    "genderAPI_key = '&key='\n",
    "\n",
    "# Check your credit balance\n",
    "check_genderAPI_balance(genderAPI_key, homedir)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "kernel": "SoS"
   },
   "source": [
    "## 4. Describe the proportions of genders in your reference list and compare it to published base rates in neuroscience.\n",
    "\n",
    "__NOTE__: your free GenderAPI account has 500 queries per month. This box contains the code that will use your limited API credits/queries if it runs without error. Re-running all code repeatedly will repeatedly use these credits.\n",
    "\n",
    "Run the code blocks below. (click to select the block and then press Ctrl+Enter; or click the block and press the Run button in the top menubar)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "kernel": "Python 3"
   },
   "outputs": [],
   "source": [
    "mm, wm, mw, ww, WW, aw, wa, aa, citation_matrix, paper_df = get_pred_demos((yourFirstAuthor+' '+yourLastAuthor).replace(',',''), homedir, bib_data, genderAPI_key)\n",
    "statement, statementLatex = print_statements(mm, wm, mw, ww, WW, aw, wa, aa)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "kernel": "Python 3"
   },
   "source": [
    "## 5. Print the Diversity Statement and visualize your results\n",
    "\n",
    "The example template can be copied and pasted into your manuscript. We have included it in our methods or references section. If you are using LaTeX, [the bibliography file can be found here](https://github.com/dalejn/cleanBib/blob/master/diversityStatement/).\n",
    "\n",
    "### Additional info about the neuroscience benchmark\n",
    "For the top 5 neuroscience journals (Nature Neuroscience, Neuron, Brain, Journal of Neuroscience, and Neuroimage), the expected gender proportions in reference lists as reported by [Dworkin et al.](https://www.biorxiv.org/content/10.1101/2020.01.03.894378v1.full.pdf) are 58.4% for man/man, 9.4% for man/woman, 25.5% for woman/man, and 6.7% for woman/woman. Expected proportions were calculated by randomly sampling papers from 28,505 articles in the 5 journals, estimating gender breakdowns using probabilistic name classification tools, and regressing for relevant article variables like publication date, journal, number of authors, review article or not, and first-/last-author seniority. See [Dworkin et al.](https://www.biorxiv.org/content/10.1101/2020.01.03.894378v1.full.pdf) for more details. \n",
    "\n",
    "Using a similar random draw model regressing for relevant variables, the expected race proportions in reference lists as reported by Bertolero et al. were 51.8% for white/white, 12.8% for white/author-of-color, 23.5% for author-of-color/white, and 11.9% for author-of-color/author-of-color. \n",
    "\n",
    "This box does NOT contain code that will use your limited API credits/queries.\n",
    "\n",
    "Run the code block below. (click to select the block and then press Ctrl+Enter; or click the block and press the Run button in the top menubar)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "kernel": "Python 3"
   },
   "outputs": [],
   "source": [
    "print('Plain text template:')\n",
    "print(statement)\n",
    "print('\\n')\n",
    "print('LaTeX template:')\n",
    "print(statementLatex)\n",
    "\n",
    "paper_df.to_csv('/home/jovyan/predictions.csv')\n",
    "\n",
    "plot_heatmaps(citation_matrix, homedir)\n",
    "\n",
    "plot_histograms()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "kernel": "SoS"
   },
   "source": [
    "### (OPTIONAL) Color-code your .tex file using the estimated gender classifications\n",
    "\n",
    "Running this code-block will optionally output your uploaded `.tex` file with color-coding for gender pair classifications. You can find the [example below's pre-print here.](https://www.biorxiv.org/content/10.1101/664250v1)\n",
    "\n",
    "![Color-coded .tex file, Eli Cornblath](img/texColors.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "kernel": "Python 3"
   },
   "outputs": [],
   "source": [
    "colorful_latex(paper_df, homedir, tex_file, bib_data)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.6"
  },
  "sos": {
   "kernels": [
    [
     "Python 3",
     "python3",
     "python3",
     "",
     {
      "name": "ipython",
      "version": 3
     }
    ],
    [
     "R",
     "ir",
     "R",
     "",
     "r"
    ]
   ],
   "panel": {
    "displayed": true,
    "height": 0
   },
   "version": "0.20.1"
  },
  "vscode": {
   "interpreter": {
    "hash": "66f30d3a05dff018f3baf45891c3cf21b32f9380ea78dc5d1d8b601d704d86ef"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}