api-entities/institutions/institution-object.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "[![GitHub Repository](https://img.shields.io/badge/GitHub-Repository-181717?style=for-the-badge&logo=GitHub&link=https://github.com/Mearman/openalex-docs/tree/main)](https://github.com/Mearman/openalex-docs/tree/main)[![Open in GitHub](https://img.shields.io/badge/Open%20in-GitHub-181717?style=for-the-badge&logo=github&link=https://github.com/Mearman/openalex-docs/blob/main/api-entities/institutions/institution-object.ipynb)](https://github.com/Mearman/openalex-docs/blob/main/api-entities/institutions/institution-object.ipynb)[![Open in Colab](https://img.shields.io/badge/Open%20in-Colab-F9AB00?style=for-the-badge&logo=Google%20Colab&link=https://colab.research.google.com/github/Mearman/openalex-docs/blob/main/api-entities/institutions/institution-object.ipynb)](https://colab.research.google.com/github/Mearman/openalex-docs/blob/main/api-entities/institutions/institution-object.ipynb)"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "%pip install --upgrade \"git+https://github.com/Mearman/openalex-python-pydantic-v1.git\"\n",
        "%pip install pandasai"
      ],
      "outputs": [],
      "execution_count": null
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "import json\n",
        "import pandas as pd\n",
        "import numpy as np\n",
        "from openalex_api import Configuration, ApiClient, AutocompleteApi, AuthorsApi, ConceptsApi, FundersApi, InstitutionsApi, PublishersApi, SourcesApi, WorksApi\n",
        "\n",
        "configuration = Configuration(host=\"https://api.openalex.org\")\n",
        "autocomplete_api = AutocompleteApi(ApiClient(configuration))\n",
        "authors_api = AuthorsApi(ApiClient(configuration))\n",
        "concepts_api = ConceptsApi(ApiClient(configuration))\n",
        "funders_api = FundersApi(ApiClient(configuration))\n",
        "institutions_api = InstitutionsApi(ApiClient(configuration))\n",
        "publishers_api = PublishersApi(ApiClient(configuration))\n",
        "sources_api = SourcesApi(ApiClient(configuration))\n",
        "works_api = WorksApi(ApiClient(configuration))\n",
        "\n",
        "from pandasai import SmartDataframe\n",
        "from pandasai.llm import OpenAI"
      ],
      "outputs": [],
      "execution_count": null
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "# @title  { run: \"auto\", display-mode: \"form\" }\n",
        "openapi_token = \"\" # @param {type:\"string\"}"
      ],
      "outputs": [],
      "execution_count": null
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Institution object\n",
        "\n",
        "These are the fields in an institution object. When you use the API to get a [single institution](./get-a-single-institution.ipynb) or [lists of institutions](./get-lists-of-institutions.ipynb), this is what's returned.\n",
        "\n",
        "### `associated_institutions`\n",
        "\n",
        "_List:_ `Institutions` related to this one. Each associated institution is represented as a [dehydrated Institution](./institution-object.md#the-dehydratedinstitution-object) object, with one extra property:\n",
        "\n",
        "* `relationship` (_String_): The type of relationship between this institution and the listed institution. Possible values: `parent`, `child`, and `related`.\n",
        "\n",
        "Institution associations and the _relationship_ vocabulary come from [ROR's `relationships`](https://ror.readme.io/docs/ror-data-structure#relationships).\n",
        "\n",
        "```json\n",
        "associated_institutions: [\n",
        "    {\n",
        "        id: \"https://openalex.org/I2802101240\",\n",
        "        ror: \"https://ror.org/0483mr804\",\n",
        "        display_name: \"Carolinas Medical Center\",\n",
        "        country_code: \"US\",\n",
        "        type: \"healthcare\",\n",
        "        relationship: \"related\"\n",
        "    },\n",
        "    {\n",
        "        id: \"https://openalex.org/I69048370\",\n",
        "        ror: \"https://ror.org/01s91ey96\",\n",
        "        display_name: \"Renaissance Computing Institute\",\n",
        "        country_code: \"US\",\n",
        "        type: \"education\",\n",
        "        relationship: \"related\"\n",
        "    },\n",
        "    \n",
        "    // and so forth\n",
        "]\n",
        "```\n",
        "\n",
        "### `cited_by_count`\n",
        "\n",
        "_Integer:_ The total number [`Works`](./../works/work-object/README.ipynb) that cite a work created by an author affiliated with this institution. Or less formally: the number of citations this institution has collected.\n",
        "\n",
        "```json\n",
        "cited_by_count: 21199844 \n",
        "```\n",
        "\n",
        "### `country_code`\n",
        "\n",
        "_String:_ The country where this institution is located, represented as an [ISO two-letter country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n",
        "\n",
        "```json\n",
        "country_code: \"US\"\n",
        "```\n",
        "\n",
        "### `counts_by_year`\n",
        "\n",
        "_List:_ [`works_count`](./institution-object.md#works_count) and [`cited_by_count`](./institution-object.md#cited_by_count) for each of the last ten years, binned by year. To put it another way: each year, you can see how many new works this institution put out, and how many times _any_ work affiliated with this institution got cited.\n",
        "\n",
        "Years with zero citations and zero works have been removed so you will need to add those in if you need them.\n",
        "\n",
        "```json\n",
        "counts_by_year: [\n",
        "    {\n",
        "        year: 2022,\n",
        "        works_count: 133,\n",
        "        cited_by_count: 32731\n",
        "    },\n",
        "    {\n",
        "        year: 2021,\n",
        "        works_count: 12565,\n",
        "        cited_by_count: 2180827\n",
        "    },\n",
        "    \n",
        "    // and so forth\n",
        "]\n",
        "```\n",
        "\n",
        "### `created_date`\n",
        "\n",
        "_String:_ The date this `Institution` object was created in the OpenAlex dataset, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string.\n",
        "\n",
        "```json\n",
        "created_date: \"2017-08-08\"\n",
        "```\n",
        "\n",
        "### `display_name`\n",
        "\n",
        "_String:_ The primary name of the institution.\n",
        "\n",
        "```json\n",
        "display_name: \"University of North Carolina at Chapel Hill\"\n",
        "```\n",
        "\n",
        "### `display_name_acronyms`\n",
        "\n",
        "_List:_ Acronyms or initialisms that people sometimes use instead of the full [`display_name`](./institution-object.md#display_name).\n",
        "\n",
        "```json\n",
        "display_name_acronyms:[\"UNC\"]\n",
        "```\n",
        "\n",
        "### `display_name_alternatives`\n",
        "\n",
        "_List:_ Other names people may use for this institution.\n",
        "\n",
        "```json\n",
        "display_name_alternatives: [\n",
        "    \"UNC-Chapel Hill\"\n",
        "]\n",
        "```\n",
        "\n",
        "### `geo`\n",
        "\n",
        "_Object:_ A bunch of stuff we know about the location of this institution:\n",
        "\n",
        "* `city` (_String_): The city where this institution lives.\n",
        "* `geonames_city_id` (_String_): The city where this institution lives, as a [GeoNames database](http://www.geonames.org/) ID.\n",
        "* `region` (_String_): The sub-national region (state, province) where this institution lives.\n",
        "* `country_code` (_String_): The country where this institution lives, represented as an [ISO two-letter country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n",
        "* `country` (_String_): The country where this institution lives.\n",
        "* `latitude` (_Float_): Does what it says.\n",
        "* `longitude` (_Float_): Does what it says.\n",
        "\n",
        "```json\n",
        "geo: {\n",
        "    city: \"Chapel Hill\",\n",
        "    geonames_city_id: \"4460162\",\n",
        "    region: \"North Carolina\",\n",
        "    country_code: \"US\",\n",
        "    country: \"United States\",\n",
        "    latitude: 35.9083,\n",
        "    longitude: -79.0492\n",
        "}\n",
        "```\n",
        "\n",
        "### `homepage_url`\n",
        "\n",
        "_String:_ The URL for institution's primary homepage.\n",
        "\n",
        "```json\n",
        "homepage_url: \"http://www.unc.edu/\"\n",
        "```\n",
        "\n",
        "### `id`\n",
        "\n",
        "_String:_ The [OpenAlex ID](./../../how-to-use-the-api/get-single-entities/README.md#the-openalex-id) for this institution.\n",
        "\n",
        "```json\n",
        "id: \"https://openalex.org/I114027177\"\n",
        "```\n",
        "\n",
        "### `ids`\n",
        "\n",
        "_Object:_ All the external identifiers that we know about for this institution. IDs are expressed as URIs whenever possible. Possible ID types:\n",
        "\n",
        "* `grid` (_String:_ this institution's [GRID](https://www.grid.ac/) [ID](https://en.wikipedia.org/wiki/RAS_syndrome))\n",
        "* `mag` (_Integer:_ this institution's [Microsoft Academic Graph](https://www.microsoft.com/en-us/research/project/microsoft-academic-graph/) ID)\n",
        "* `openalex` (_String:_ this institution's [OpenAlex ID](./../../how-to-use-the-api/get-single-entities/README.md#the-openalex-id). Same as [`Institution.id`](./institution-object.md#id))\n",
        "* `ror` (_String:_ this institution's ROR ID. Same as [`Institution.ror`](./institution-object.md#ror))\n",
        "* `wikipedia` (_String:_ this institution's Wikipedia page URL)\n",
        "* `wikidata` (_String:_ this institution's [Wikidata ID](https://www.wikidata.org/wiki/Wikidata:Identifiers))\n",
        "\n",
        "{% hint style=\"info\" %}\n",
        "Many institution are missing one or more ID types (either because we don't know the ID, or because it was never assigned). Keys for null IDs are not displayed.\n",
        "{% endhint %}\n",
        "\n",
        "```json\n",
        "ids: {\n",
        "    openalex: \"https://openalex.org/I114027177\",\n",
        "    ror: \"https://ror.org/0130frc33\",\n",
        "    grid: \"grid.10698.36\",\n",
        "    wikipedia: \"https://en.wikipedia.org/wiki/University%20of%20North%20Carolina%20at%20Chapel%20Hill\",\n",
        "    wikidata: \"https://www.wikidata.org/wiki/Q192334\",\n",
        "    mag: 114027177\n",
        "}  \n",
        "```\n",
        "\n",
        "### `image_thumbnail_url`\n",
        "\n",
        "_String:_ Same as [`image_url`](./institution-object.md#image_url-1), but it's a smaller image.\n",
        "\n",
        "```json\n",
        "image_thumbnail_url: \"https://upload.wikimedia.org/wikipedia/en/thumb/5/5c/University_of_North_Carolina_at_Chapel_Hill_seal.svg/100px-University_of_North_Carolina_at_Chapel_Hill_seal.svg.png\"\n",
        "```\n",
        "\n",
        "### `image_url`\n",
        "\n",
        "_String:_ URL where you can get an image representing this institution. Usually this is hosted on Wikipedia, and usually it's a seal or logo.\n",
        "\n",
        "```json\n",
        "image_url: \"https://upload.wikimedia.org/wikipedia/en/5/5c/University_of_North_Carolina_at_Chapel_Hill_seal.svg\"\n",
        "```\n",
        "\n",
        "### `international`\n",
        "\n",
        "_Object:_ The institution's display name in different languages. Derived from the wikipedia page for the institution in the given language.\n",
        "\n",
        "* `display_name` (_Object_)\n",
        "  * `key` (String): language code in [wikidata language code](https://www.wikidata.org/wiki/Property:P9753) format. Full list of languages is [here](https://doc.wikimedia.org/mediawiki-core/master/php/Names_8php_source.html).\n",
        "  * `value` (String): `display_name` in the given language\n",
        "\n",
        "```json\n",
        "international: {\n",
        "    display_name: {\n",
        "        \"ar\": \"جامعة نورث كارولينا في تشابل هيل\",\n",
        "        \"en\": \"University of North Carolina at Chapel Hill\",\n",
        "        \"es\": \"Universidad de Carolina del Norte en Chapel Hill\",\n",
        "        \"zh-cn\": \"北卡罗来纳大学教堂山分校\",\n",
        "        ...\n",
        "    }\n",
        "}\n",
        "```\n",
        "\n",
        "### `lineage`\n",
        "\n",
        "_List:_ [OpenAlex IDs](./../../how-to-use-the-api/get-single-entities/README.md#the-openalex-id) of institutions. The list will include this institution's ID, as well as any parent institutions. If this institution has no parent institutions, this list will only contain its own ID.\n",
        "\n",
        "This information\n",
        "\n",
        "This information comes from [ROR's `relationships`](https://ror.readme.io/docs/ror-data-structure#relationships), specifically the Parent/Child relationships.\n",
        "\n",
        "```json\n",
        "id: \"https://openalex.org/I170203145\",\n",
        "...\n",
        "lineage: [\n",
        "    \"https://openalex.org/I170203145\",\n",
        "    \"https://openalex.org/I90344618\"\n",
        "]\n",
        "```\n",
        "\n",
        "### `repositories`\n",
        "\n",
        "_List:_ Repositories ([`Sources`](./../sources/README.ipynb) with `type: repository`) that have this institution as their [`host_organization`](./../sources/source-object.md#host_organization)\n",
        "\n",
        "```json\n",
        "repositories: [\n",
        "    {\n",
        "        id: \"https://openalex.org/S4306402521\",\n",
        "        display_name: \"University of Minnesota Digital Conservancy (University of Minnesota)\",\n",
        "        host_organization: \"https://openalex.org/I130238516\",\n",
        "        host_organization_name: \"University of Minnesota\",\n",
        "        host_organization_lineage: [\"https://openalex.org/I130238516\"]\n",
        "    }\n",
        "    // and so forth\n",
        "]\n",
        "```\n",
        "\n",
        "### `roles`\n",
        "\n",
        "_List:_ List of role objects, which include the `role` (one of `institution`, `funder`, or `publisher`), the `id` ([OpenAlex ID](./../../how-to-use-the-api/get-single-entities/README.md#the-openalex-id)), and the `works_count`.\n",
        "\n",
        "In many cases, a single organization does not fit neatly into one role. For example, Yale University is a single organization that is a research university, funds research studies, and publishes an academic journal. The `roles` property links the OpenAlex entities together for a single organization, and includes counts for the works associated with each role.\n",
        "\n",
        "The `roles` list of an entity ([Funder](./../funders/README.ipynb), [Publisher](./../publishers/README.ipynb), or [Institution](./README.ipynb)) always includes itself. In the case where an organization only has one role, the `roles` will be a list of length one, with itself as the only item.\n",
        "\n",
        "```json\n",
        "roles: [\n",
        "    {\n",
        "        role: \"funder\",\n",
        "        id: \"https://openalex.org/F4320308380\",\n",
        "        works_count: 1004,\n",
        "    },\n",
        "    {\n",
        "        role: \"publisher\",\n",
        "        id: \"https://openalex.org/P4310315589\",\n",
        "        works_count: 13986,\n",
        "    },\n",
        "    {\n",
        "        role: \"institution\",\n",
        "        id: \"https://openalex.org/I32971472\",\n",
        "        works_count: 250031,\n",
        "    }\n",
        "]\n",
        "```\n",
        "\n",
        "### `ror`\n",
        "\n",
        "_String:_ The [ROR](https://ror.org/) ID for this institution. This is the [Canonical External ID](./../../how-to-use-the-api/get-single-entities/README.md#canonical-external-ids) for institutions.\n",
        "\n",
        "The ROR (Research Organization Registry) identifier is a globally unique ID for research organization. [ROR is the successor to GRiD](https://www.digital-science.com/press-release/grid-passes-torch-to-ror/), which is no longer being updated.\n",
        "\n",
        "```json\n",
        "ror: \"https://ror.org/0130frc33\"\n",
        "```\n",
        "\n",
        "### `summary_stats`\n",
        "\n",
        "_Object:_ Citation metrics for this institution\n",
        "\n",
        "* `2yr_mean_citedness` _Float_: The 2-year mean citedness for this source. Also known as [impact factor](https://en.wikipedia.org/wiki/Impact_factor). We use the year prior to the current year for the citations (the numerator) and the two years prior to that for the citation-receiving publications (the denominator).\n",
        "* `h_index` _Integer_: The [_h_-index](https://en.wikipedia.org/wiki/H-index) for this institution.\n",
        "* `i10_index` _Integer_: The [i-10 index](https://en.wikipedia.org/wiki/Author-level_metrics#i-10-index) for this institution.\n",
        "\n",
        "While the _h_-index and the i-10 index are normally author-level metrics and the 2-year mean citedness is normally a journal-level metric, they can be calculated for any set of papers, so we include them for institutions.\n",
        "\n",
        "```json\n",
        "summary_stats: {\n",
        "    2yr_mean_citedness: 5.065784263815827,\n",
        "    h_index: 985,\n",
        "    i10_index: 176682\n",
        "}\n",
        "```\n",
        "\n",
        "### `type`\n",
        "\n",
        "_String:_ The institution's primary type, using the [ROR \"type\" controlled vocabulary](https://ror.readme.io/docs/ror-data-structure).\n",
        "\n",
        "Possible values are: `Education`, `Healthcare`, `Company`, `Archive`, `Nonprofit`, `Government`, `Facility`, and `Other`.\n",
        "\n",
        "```json\n",
        "type: \"education\"\n",
        "```\n",
        "\n",
        "### `updated_date`\n",
        "\n",
        "_String:_ The last time anything in this `Institution` changed, expressed as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string. This date is updated for _any change at all_, including increases in various counts.\n",
        "\n",
        "```json\n",
        "updated_date: \"2022-01-02T00:27:23.088909\"\n",
        "```\n",
        "\n",
        "### `works_api_url`\n",
        "\n",
        "_String:_ A URL that will get you a list of all the [`Works`](./../works/work-object/README.ipynb) affiliated with this institution.\n",
        "\n",
        "We express this as an API URL (instead of just listing the `Works` themselves) because most institutions have way too many works to reasonably fit into a single return object.\n",
        "\n",
        "```json\n",
        "works_api_url: \"https://api.openalex.org/works?filter=institutions.id:I114027177\""
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "# @title { run: \"auto\", vertical-output: false }\n",
        "# https://api.openalex.org/works?filter=institutions.id:I114027177\n",
        "filter=\"institutions.id:I114027177\" # @param {type: \"string\"}\n",
        "\n",
        "response = works_api.get_works(\n",
        "\tfilter=filter\n",
        ")\n",
        "\n",
        "df = pd.DataFrame(response.results)\n",
        "display(df)"
      ],
      "outputs": [],
      "execution_count": null
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "numeric_df = df[['id', 'display_name'] +\n",
        "\t[col for col in df.columns if df[col].dtype in ['int64', 'float64'] and col != 'relevance_score']]\n",
        "display(numeric_df)"
      ],
      "outputs": [],
      "execution_count": null
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "try:\n",
        "\tprompt = \"Visualize this data\" # @param {type:\"string\"}\n",
        "\tSmartDataframe(\n",
        "\t\tnumeric_df,\n",
        "\t\tconfig={\"llm\": (OpenAI(api_token=openapi_token))},\n",
        "\t).chat(prompt)\n",
        "except:\n",
        "\tif not openapi_token:\n",
        "\t\tprint(\"Error: openapi_token not set\")\n",
        "\telse:\n",
        "\t\tprint(\"Error when creating SmartDataframe\")"
      ],
      "outputs": [],
      "execution_count": null
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "```\n",
        "\n",
        "### `works_count`\n",
        "\n",
        "_Integer:_ The number of [`Works`](./../works/work-object/README.ipynb) created by authors affiliated with this institution. Or less formally: the number of works coming out of this institution.\n",
        "\n",
        "```json\n",
        "works_count: 202704    \n",
        "```\n",
        "\n",
        "### `x_concepts`\n",
        "\n",
        "{% hint style=\"danger\" %}\n",
        "The \"x\" in `x_concepts` is because it's experimental and subject to removal with very little warning. We plan to replace it with a custom link to the Concepts API endpoint.\n",
        "{% endhint %}\n",
        "\n",
        "_List:_ The [`Concepts`](./../concepts/concept-object.ipynb) most frequently applied to works affiliated with this institution. Each is represented as a [dehydrated Concept](./../concepts/concept-object.md#the-dehydratedconcept-object) object, with one additional attribute:\n",
        "\n",
        "* `score` (_Float_): The strength of association between this institution and the listed concept, from 0-100.\n",
        "\n",
        "```json\n",
        "x_concepts: [\n",
        "    {\n",
        "        id: \"https://openalex.org/C86803240\",\n",
        "        wikidata: null,\n",
        "        display_name: \"Biology\",\n",
        "        level: 0,\n",
        "        score: 86.7\n",
        "    },\n",
        "    {\n",
        "        id: \"https://openalex.org/C185592680\",\n",
        "        wikidata: null,\n",
        "        display_name: \"Chemistry\",\n",
        "        level: 0,\n",
        "        score: 51.4\n",
        "    },\n",
        "    \n",
        "    // and so forth\n",
        "]\n",
        "```\n",
        "\n",
        "## The `DehydratedInstitution` object\n",
        "\n",
        "The `DehydratedInstitution` is a stripped-down [`Institution`](./institution-object.ipynb) object, with most of its properties removed to save weight. Its only remaining properties are:\n",
        "\n",
        "* [`country_code`](./institution-object.md#country_code)\n",
        "* [`display_name`](./institution-object.md#display_name)\n",
        "* [`id`](./institution-object.md#id)\n",
        "* [`lineage`](./institution-object.md#lineage)\n",
        "* [`ror`](./institution-object.md#ror)\n",
        "* [`type`](./institution-object.md#type)"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "pygments_lexer": "ipython3",
      "version": "3.8.5"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 4
}