api-entities/sources/source-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/sources/source-object.ipynb)](https://github.com/Mearman/openalex-docs/blob/main/api-entities/sources/source-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/sources/source-object.ipynb)](https://colab.research.google.com/github/Mearman/openalex-docs/blob/main/api-entities/sources/source-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": [
        "# Source object\n",
        "\n",
        "These are the fields in a source object. When you use the API to get a single source or lists of sources, this is what's returned.\n",
        "\n",
        "### abbreviated_title\n",
        "\n",
        "_String:_ An abbreviated title obtained from the [ISSN Centre](https://issn.org).\n",
        "\n",
        "```json\n",
        "abbreviated_title: \"J. addict. med. ther. sci.\"\n",
        "```\n",
        "\n",
        "### alternate_titles\n",
        "\n",
        "_Array:_ Alternate titles for this source, as obtained from the [ISSN Centre](https://issn.org) and individual work records, like Crossref DOIs, that carry the source name as a string. These are commonly abbreviations or translations of the source's canonical name.\n",
        "\n",
        "```json\n",
        "alternate_titles: [\n",
        "   \"ACRJ\"\n",
        "]\n",
        "```\n",
        "\n",
        "### apc_prices\n",
        "\n",
        "_List:_ List of objects, each with `price` (_Integer_) and `currency` (_String_).\n",
        "\n",
        "Article processing charge information, taken directly from [DOAJ](https://doaj.org/).\n",
        "\n",
        "```json\n",
        "apc_prices: [\n",
        "    {\n",
        "        price: 3920,\n",
        "        currency: \"GBP\"\n",
        "    }\n",
        "]\n",
        "```\n",
        "\n",
        "### apc_usd\n",
        "\n",
        "_Integer:_ The source's article processing charge in US Dollars, if available from [DOAJ](https://doaj.org/).\n",
        "\n",
        "The `apc_usd` value is calculated by taking the APC price (see [`apc_prices`](./source-object.md#apc_prices)) with a currency of USD if it is available. If it's not available, we convert the first available value from `apc_prices` into USD, using recent exchange rates.\n",
        "\n",
        "```json\n",
        "apc_usd: 5200\n",
        "```\n",
        "\n",
        "### `cited_by_count`\n",
        "\n",
        "_Integer:_ The total number of [`Works`](./../works/work-object/README.ipynb) that cite a `Work` hosted in this source.\n",
        "\n",
        "```json\n",
        "cited_by_count: 133702 \n",
        "```\n",
        "\n",
        "### `country_code`\n",
        "\n",
        "_String:_ The country that this source is associated with, represented as an [ISO two-letter country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n",
        "\n",
        "```json\n",
        "country_code: \"GB\" \n",
        "```\n",
        "\n",
        "### `counts_by_year`\n",
        "\n",
        "_List:_ [`works_count`](./source-object.md#works_count) and [`cited_by_count`](./source-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 source started hosting, and how many times _any_ work in this source got cited.\n",
        "\n",
        "If the source was founded less than ten years ago, there will naturally be fewer than ten years in this list. 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: 2021,\n",
        "        works_count: 4338,\n",
        "        cited_by_count: 127268\n",
        "    },\n",
        "    {\n",
        "        year: 2020,\n",
        "        works_count: 4363,\n",
        "        cited_by_count: 119531\n",
        "    },\n",
        "    \n",
        "    // and so forth\n",
        "]\n",
        "```\n",
        "\n",
        "### `created_date`\n",
        "\n",
        "_String:_ The date this `Source` 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 name of the source.\n",
        "\n",
        "```json\n",
        "display_name: \"PeerJ\"\n",
        "```\n",
        "\n",
        "### `homepage_url`\n",
        "\n",
        "_String:_ The starting page for navigating the contents of this source; the homepage for this source's website.\n",
        "\n",
        "```json\n",
        "homepage_url: \"http://www.peerj.com/\" \n",
        "```\n",
        "\n",
        "### `host_organization`\n",
        "\n",
        "_String:_ The host organization for this source as an [OpenAlex ID](./../../how-to-use-the-api/get-single-entities/README.md#the-openalex-id). This will be an [`Institution.id`](./../institutions/institution-object.md#id) if the source is a repository, and a [`Publisher.id`](./../publishers/publisher-object.md#id) if the source is a journal, conference, or eBook platform (based on the [`type`](./source-object.md#type) field).\n",
        "\n",
        "```json\n",
        "id: \"https://openalex.org/P4310320595\"\n",
        "```\n",
        "\n",
        "### `host_organization_lineage`\n",
        "\n",
        "_List:_ [OpenAlex IDs](./../../how-to-use-the-api/get-single-entities/README.md#the-openalex-id) — See [`Publisher.lineage`](./../publishers/publisher-object.md#lineage). This will only be included if the [`host_organization`](./source-object.md#host_organization) is a publisher (and not if the `host_organization` is an institution).\n",
        "\n",
        "```json\n",
        "host_organization_lineage: [\n",
        "    \"https://openalex.org/P4310321285\",\n",
        "    \"https://openalex.org/P4310319900\",\n",
        "    \"https://openalex.org/P4310319965\"\n",
        "]\n",
        "```\n",
        "\n",
        "### `host_organization_name`\n",
        "\n",
        "_String:_ The `display_name` from the [host_organization](./source-object.md#host_organization), shown for convenience.\n",
        "\n",
        "```json\n",
        "host_organization_name: \"Elsevier BV\" \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 source.\n",
        "\n",
        "```json\n",
        "id: \"https://openalex.org/S1983995261\"\n",
        "```\n",
        "\n",
        "### `ids`\n",
        "\n",
        "_Object:_ All the external identifiers that we know about for this source. IDs are expressed as URIs whenever possible. Possible ID types:\n",
        "\n",
        "* `fatcat` (_String_: this source's [Fatcat](https://fatcat.wiki/) ID)\n",
        "* `issn` (_List:_ a list of this source's ISSNs. Same as [`Source.issn`](./source-object.md#issn))\n",
        "* `issn_l` (_String:_ this source's ISSN-L. Same as [`Source.issn_l`](./source-object.md#issn_l))\n",
        "* `mag` (_Integer:_ this source's [Microsoft Academic Graph](https://www.microsoft.com/en-us/research/project/microsoft-academic-graph/) ID)\n",
        "* `openalex` (_String:_ this source's [OpenAlex ID](./../../how-to-use-the-api/get-single-entities/README.md#the-openalex-id). Same as [`Source.id`](./source-object.md#id))\n",
        "* `wikidata` (_String_: this source's [Wikidata](https://www.wikidata.org/wiki/Wikidata:Main_Page) ID)\n",
        "\n",
        "{% hint style=\"info\" %}\n",
        "Many sources 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",
        "<details>\n",
        "\n",
        "<summary>Example</summary>\n",
        "\n",
        "{% code fullWidth=\"true\" %}\n",
        "```json\n",
        "ids: {\n",
        "    openalex: \"https://openalex.org/S1983995261\",\n",
        "    issn_l: \"2167-8359\",\n",
        "    issn: [\n",
        "        \"2167-8359\"\n",
        "    ],\n",
        "    mag: 1983995261,\n",
        "    fatcat: \"https://fatcat.wiki/container/z3ijzhu7zzey3f7jwws7rzopoq\",\n",
        "    wikidata: \"https://www.wikidata.org/entity/Q96326029\"\n",
        "}\n",
        "```\n",
        "{% endcode %}\n",
        "\n",
        "</details>\n",
        "\n",
        "### `is_in_doaj`\n",
        "\n",
        "_Boolean:_ Whether this is a journal listed in the [Directory of Open Access Journals](https://doaj.org/) (DOAJ).\n",
        "\n",
        "```json\n",
        "is_in_doaj: true \n",
        "```\n",
        "\n",
        "### `is_oa`\n",
        "\n",
        "_Boolean:_ Whether this is currently fully-open-access source. This could be `true` for a preprint repository where everything uploaded is free to read, or for a [Gold](https://en.wikipedia.org/wiki/Open_access#Colour_naming_system) or [Diamond](https://en.wikipedia.org/wiki/Diamond_open_access) open access journal, where all newly published Works are available for free under an open license.\n",
        "\n",
        "We say \"currently\" because the status of a source can change over time. It's common for journals to \"flip\" to Gold OA, after which they may make only future articles open or also open their back catalogs. It's entirely possible for a source to say `is_oa: true`, but for an article from last year to require a subscription.\n",
        "\n",
        "```json\n",
        "is_oa: true \n",
        "```\n",
        "\n",
        "### `issn`\n",
        "\n",
        "_List:_ The [ISSNs](https://en.wikipedia.org/wiki/International_Standard_Serial_Number) used by this source. Many publications have multiple ISSNs , so [ISSN-L](./source-object.md#issn_l) should be used when possible.\n",
        "\n",
        "```json\n",
        "issn: [\"2167-8359\"]\n",
        "```\n",
        "\n",
        "### `issn_l`\n",
        "\n",
        "_String:_ The [ISSN-L](https://en.wikipedia.org/wiki/International_Standard_Serial_Number#Linking_ISSN) identifying this source. This is the [Canonical External ID](./../../how-to-use-the-api/get-single-entities/README.md#canonical-external-ids) for sources.\n",
        "\n",
        "ISSN is a global and unique ID for serial publications. However, different media versions of a given publication (e.g., print and electronic) often have _different_ ISSNs. This is why we can't have nice things. The ISSN-L or Linking ISSN solves the problem by designating a single canonical ISSN for all media versions of the title. It's _usually_ the same as the print ISSN.\n",
        "\n",
        "```json\n",
        "issn_l: \"2167-8359\"\n",
        "```\n",
        "\n",
        "### societies\n",
        "\n",
        "_Array:_ Societies on whose behalf the source is published and maintained, obtained from our [crowdsourced list](https://blog.ourresearch.org/society-list/). Thanks!\n",
        "\n",
        "```json\n",
        "societies: [\n",
        "    {\n",
        "        \"url\": \"http://www.counseling.org/\",\n",
        "        \"organization\": \"American Counseling Association on behalf of the American College Counseling Association\"\n",
        "    }\n",
        "]\n",
        "```\n",
        "\n",
        "### `summary_stats`\n",
        "\n",
        "_Object:_ Citation metrics for this source\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 source.\n",
        "* `i10_index` _Integer_: The [i-10 index](https://en.wikipedia.org/wiki/Author-level_metrics#i-10-index) for this source.\n",
        "\n",
        "While the _h_-index and the i-10 index are normally author-level metrics, they can be calculated for any set of papers, so we include them for sources.\n",
        "\n",
        "```json\n",
        "summary_stats: {\n",
        "    2yr_mean_citedness: 1.5295340589458237,\n",
        "    h_index: 105,\n",
        "    i10_index: 5045\n",
        "}\n",
        "```\n",
        "\n",
        "### `type`\n",
        "\n",
        "_String:_ The type of source, which will be one of: `journal`, `repository`, `conference`, `ebook platform`, or `book series`.\n",
        "\n",
        "```json\n",
        "type: \"journal\" \n",
        "```\n",
        "\n",
        "### `updated_date`\n",
        "\n",
        "_String:_ The last time anything in this `Source` object 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:00:00\"\n",
        "```\n",
        "\n",
        "### `works_api_url`\n",
        "\n",
        "_String:_ A URL that will get you a list of all this source's `Works`.\n",
        "\n",
        "We express this as an API URL (instead of just listing the works themselves) because sometimes a source's publication list is too long to reasonably fit into a single `Source` object.\n",
        "\n",
        "```json\n",
        "works_api_url: \"https://api.openalex.org/works?filter=primary_location.source.id:S1983995261\","
      ]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": [
        "# @title { run: \"auto\", vertical-output: false }\n",
        "# https://api.openalex.org/works?filter=primary_location.source.id:S1983995261\n",
        "filter=\"primary_location.source.id:S1983995261\" # @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) this source hosts.\n",
        "\n",
        "```json\n",
        "works_count: 20184 \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` most frequently applied to works hosted by this source. 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 source 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 `DehydratedSource` object\n",
        "\n",
        "The `DehydratedSource` is stripped-down `Source` object, with most of its properties removed to save weight. Its only remaining properties are:\n",
        "\n",
        "* [`display_name`](./source-object.md#display_name)\n",
        "* [`host_organization`](./source-object.md#host_organization)\n",
        "* [`host_organization_lineage`](./source-object.md#host_organization_lineage)\n",
        "* [`host_organization_name`](./source-object.md#host_organization_name)\n",
        "* [`id`](./source-object.md#id)\n",
        "* [`is_in_doaj`](./README.md#is_in_doaj)\n",
        "* [`is_oa`](./README.md#is_oa)\n",
        "* [`issn`](./source-object.md#issn)\n",
        "* [`issn_l`](./source-object.md#issn_l)\n",
        "* [`type`](./source-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
}