Merge pull request #8 from Project-TAPIR/improve-documentation

Improve documentation

Author: Sandra Mierz

organization-organization/ror-organigram.ipynb

@@ -1,19 +1,28 @@
 {
  "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
   {
    "cell_type": "markdown",
    "metadata": {
     "id": "0-62NAVa8DL0"
    },
    "source": [
-    "### Query ROR for an organization and the hierarchy of sub-organizations below it\n",
+    "### Query ROR for an organization and all its suborganizations\n",
     "\n",
-    "This notebook queries the [ROR API](https://ror.readme.io/) to construct a hierarchy of sub-organizations starting at a given organization. It takes a ROR URL or ID which is used to retrieve the organizations specified in the metadata field \"`relationships`\" with `\"type\"=Child` recursively to build a tree structure. The tree represents the hierarchy of sub-organizations and will be outputted.\n"
+    "This notebook queries the [ROR API](https://ror.readme.io/) for an organization and all its suborganizations. \n",
+    "It takes a ROR URL or ROR ID as input which is used as a starting point for recursively querying the ROR API for an organization's suborganizations specified in the metadata field \"`relationships`\" having the `\"type\"=Child`. \n",
+    "The hierarchy is represented as a tree and will be outputted.\n"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "metadata": {
     "id": "VaYUrh5n2iq9",
     "scrolled": true
@@ -31,7 +40,7 @@
     "id": "YmmrIwjv3QqG"
    },
    "source": [
-    "The input value for all following queries is a ROR URL or ID, e.g. '`https://ror.org/03vek6s52`' or '`03vek6s52`'."
+    "The input for this notebook is a ROR URL or ROR ID, e.g. '`https://ror.org/03vek6s52`' or '`03vek6s52`'."
    ]
   },
   {
@@ -81,7 +90,8 @@
      },
      "user_tz": -60
     },
-    "id": "YpwZ3mrC3dHO"
+    "id": "YpwZ3mrC3dHO",
+    "scrolled": true
    },
    "outputs": [],
    "source": [
@@ -101,8 +111,8 @@
     "#---- example execution\n",
     "# uncomment following lines to see the metadata for specified example_ror\n",
     "#import pprint\n",
-    "#organization = query_ror_api(example_ror)\n",
-    "#pprint.pprint(organization)"
+    "#organization_data = query_ror_api(example_ror)\n",
+    "#pprint.pprint(organization_data)"
    ]
   },
   {
@@ -111,7 +121,7 @@
     "id": "T25jtRBf3c1T"
    },
    "source": [
-    "But in this notebook we use it as a starting point to recursively query the ROR API using the relationship type \"`Child`\" to construct the organizational hierarchy below it."
+    "but in this notebook we use it as a starting point to recursively query the ROR API using the relationship type \"`Child`\" to construct the organizational hierarchy below it."
    ]
   },
   {
@@ -133,7 +143,10 @@
      "user_tz": -60
     },
     "id": "4jh1liI56A4x",
-    "outputId": "ea1cbf18-6c90-4aa3-bfcb-10addcaa9e8f"
+    "outputId": "ea1cbf18-6c90-4aa3-bfcb-10addcaa9e8f",
+    "pycharm": {
+     "is_executing": true
+    }
    },
    "outputs": [
     {

organization-people/freya_get_people_by_organization.ipynb

@@ -6,14 +6,14 @@
     "id": "etxiXTW668ZD"
    },
    "source": [
-    "### Query the FREYA PID Graph for all people affiliated with an organization\n",
+    "### Query the FREYA PID Graph for people affiliated with an organization\n",
     "\n",
-    "This notebook queries the [FREYA PID Graph](https://blog.datacite.org/powering-the-pid-graph/) via [Datacite's GraphQL API](https://api.datacite.org/graphql) to retrieve all people affiliated with an organization. It takes a ROR URL as input which is used to retrieve the according Grid and Ringgold ID of the organization and query the ORCID API with it [for affiliated people](https://info.orcid.org/faq/how-do-i-find-orcid-record-holders-at-my-institution/). From the resulting list of people we output the ORCID iDs."
+    "This notebook queries the [FREYA PID Graph](https://blog.datacite.org/powering-the-pid-graph/) via [Datacite's GraphQL API](https://api.datacite.org/graphql) to retrieve people affiliated with an organization. It takes a ROR URL as input which is used internally to retrieve the Grid ID from the ROR API and Ringgold ID from Wikidata and use these identifiers to [find ORCID record holders at the institution](https://info.orcid.org/faq/how-do-i-find-orcid-record-holders-at-my-institution/). From the resulting list of people we output the ORCID iDs."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "metadata": {
     "id": "8Mk7-aYc7x3A",
     "scrolled": true
@@ -31,7 +31,7 @@
     "id": "J31_ejB6bWqd"
    },
    "source": [
-    "The input for the query is a ROR URL, e.g. '`https://ror.org/021k10z87`'"
+    "The input for this notebook is a ROR URL, e.g. '`https://ror.org/021k10z87`'"
    ]
   },
   {
@@ -63,7 +63,8 @@
     "id": "ba_A3Anpbl4P"
    },
    "source": [
-    "We use it to query Datacite's GraphQL API for the organization's metadata and all people connected to it. Since the API uses pagination, we need to loop through all pages to get the complete result set.\n"
+    "We use it to query Datacite's GraphQL API for the organization's metadata and all people connected to it.\n",
+    "Since the API uses pagination, we need to loop through all pages to get the complete result set.\n"
    ]
   },
   {
@@ -176,20 +177,21 @@
      "text": [
       "0000-0002-3783-6130, Irene Weipert-Fenner\n",
       "0000-0002-5452-0488, Hans-Joachim Spanger\n",
-      "0000-0001-6746-1248, Anton Peez\n",
+      "0000-0002-4621-9687, Simone Schnabel\n",
       "0000-0001-6731-5304, Julia Eckert\n",
+      "0000-0001-6746-1248, Anton Peez\n",
       "0000-0003-1575-9688, Hendrik Simon\n",
       "0000-0002-1712-2624, Julian Junk\n",
       "0000-0003-0035-5840, Raphael Oidtmann\n",
       "0000-0002-5925-043X, Ariadne Natal\n",
       "0000-0002-7012-6739, Peter Kreuzer\n",
       "0000-0001-7843-4480, Dirk Peters\n",
-      "0000-0003-0039-9827, Eldad Ben Aharon\n",
       "0000-0001-6823-6819, Janna Lisa Chalmovsky\n",
       "0000-0003-1940-8877, Mikhail Polianskii\n",
       "0000-0001-7302-444X, Katja Freistein\n",
-      "0000-0001-7286-3575, Paul Chambers\n",
       "0000-0002-8739-2486, Elvira Rosert\n",
+      "0000-0001-7286-3575, Paul Chambers\n",
+      "0000-0003-0039-9827, Eldad Ben Aharon\n",
       "0000-0002-4259-6071, Felix S. Bethke\n"
      ]
     }

organization-people/openalex_get_people_by_organization.ipynb

@@ -7,14 +7,14 @@
     "id": "ac7bedaf-05fb-4eb0-9bf5-e4d1d68a08c3"
    },
    "source": [
-    "### Query OpenAlex for all people affiliated with an organization\n",
-    "This script queries the [OpenAlex API](https://docs.openalex.org/api) via its '`/authors`' endpoint for all authors affiliated with an organization.\n",
-    "It takes a ROR URL as input which is used to retrieve all authors that specified the ROR ID in their metadata field '`last_known_institution.ror`'. From the resulting list of people we output their respective ORCID iDs."
+    "### Query OpenAlex for people affiliated with an organization\n",
+    "This notebook queries the [OpenAlex API](https://docs.openalex.org/api) via its '`/authors`' endpoint for all authors affiliated with an organization.\n",
+    "It takes a ROR URL as input which is used to retrieve authors with the specified ROR URL in their metadata field '`last_known_institution.ror`'. From the resulting list of people we output the ORCID iDs."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "id": "IUqshUWKwSk2",
    "metadata": {
     "executionInfo": {
@@ -43,7 +43,7 @@
     "id": "nSJjdkxGdWll"
    },
    "source": [
-    "The input for the query is a ROR URL, e.g. '`https://ror.org/021k10z87`'"
+    "The input for the notebook is a ROR URL, e.g. '`https://ror.org/021k10z87`'"
    ]
   },
   {
@@ -77,7 +77,7 @@
     "id": "MiXVDKXid9tq"
    },
    "source": [
-    "We use it to query the OpenAlex API for authors that specified the organization's ROR ID in the field '`last_known_institution.ror`'.  Since the OpenAlex API uses [pagination](https://docs.openalex.org/api/get-lists-of-entities#pagination), we need to loop through all pages to get the complete result set."
+    "We use it to query the OpenAlex API endpoint for `'authors'` with the specified ROR URL in their metadata field '`last_known_institution.ror`'.  Since the API uses [pagination](https://docs.openalex.org/api/get-lists-of-entities#pagination), we need to loop through all pages to get the complete result set."
    ]
   },
   {
@@ -141,7 +141,9 @@
     "id": "CwRzvAQweuoW"
    },
    "source": [
-    "From the resulting list of people we extract and print out each ORCID and name."
+    "From the resulting list of people we extract and print out each ORCID iD and name.\n",
+    "\n",
+    "*Note: people that do not have an ORCID within their `ids` metadata, will not be printed.*"
    ]
   },
   {
@@ -173,15 +175,15 @@
      "text": [
       "0000-0002-3824-5375, Nicole Deitelhoff\n",
       "0000-0002-7348-7206, Jonas Wolff\n",
-      "0000-0002-6891-770X, Francis O’Connor\n",
       "0000-0002-3536-8898, Felix Anderl\n",
       "0000-0002-4259-6071, Felix S. Bethke\n",
       "0000-0002-3136-0901, Thorsten Gromes\n",
       "0000-0001-9698-2616, Annika Elena Poppe\n",
       "0000-0002-3783-6130, Irene Weipert-Fenner\n",
       "0000-0002-4793-9010, Arvid Bell\n",
       "0000-0002-7012-6739, Peter Kreuzer\n",
-      "0000-0002-0143-5183, Christina Kohler\n"
+      "0000-0002-1185-8673, Daniel Mullis\n",
+      "0000-0001-6746-1248, Anton Peez\n"
      ]
     }
    ],