MC9 - topics entities.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Media Cloud: Topics: Entities\n",
    "=============================\n",
    "\n",
    "At this point you have a topic created in Media Cloud - a corpus of open-news web content related to an issue you want to investigate, discovered on mulitple platforms across the internet. Topics don't expose special endpoints for examining the entities mentioned - people, places and organizations. See the \"entities\" notebook for more about how to investigate entities overall. All that information applies here.\n",
    "\n",
    "To examine entities within a topic corpus, you simply call `storyTagCount` with the `timespans_id` you are interested in. This shortcut is generally useful for experimenting - you can limit any non-topic call to a timespan by quering with a `timespans_id:12345` clause."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup a Connection and Some Constants"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Grab your API key from the environment variable and create a client for talking to Media Cloud\n",
    "import os, mediacloud.api\n",
    "from dotenv import load_dotenv\n",
    "from IPython.display import JSON\n",
    "load_dotenv()  # load config from .env file\n",
    "mc = mediacloud.api.MediaCloud(os.getenv('MC_API_KEY'))\n",
    "mediacloud.__version__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# we'll use this topic for the explanantion\n",
    "SOURDOUGH_TOPIC = 4138\n",
    "# find the latest snapshot\n",
    "snapshots = mc.topicSnapshotList(SOURDOUGH_TOPIC)\n",
    "latest_snapshot_id = snapshots[0]['snapshots_id'] # grab the id of the latest snapshot\n",
    "# pull out the automatically-generated monthly timespans, and the overall one\n",
    "timespans = mc.topicTimespanList(SOURDOUGH_TOPIC)\n",
    "overall_timespan = [t for t in timespans if t['period'] == 'overall'][0]\n",
    "monthly_timespans = [t for t in timespans if t['period'] == 'monthly']\n",
    "# grab a subtopic to work with as well\n",
    "focal_sets = mc.topicFocalSetList(SOURDOUGH_TOPIC)\n",
    "reddit_foci_id = focal_sets[0]['foci'][0]['foci_id']\n",
    "# and some timespans in the reddit subtopic\n",
    "reddit_timespans = mc.topicTimespanList(SOURDOUGH_TOPIC, foci_id=reddit_foci_id)\n",
    "reddit_overall_timespan = [t for t in reddit_timespans if t['period'] == 'overall'][0]\n",
    "reddit_monthly_timespans = [t for t in reddit_timespans if t['period'] == 'monthly']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Who is Being Mentioned?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# let's see who is being mentioned most in the corpus\n",
    "import mediacloud.tags\n",
    "results = mc.storyTagCount(\"timespans_id:{}\".format(overall_timespan['timespans_id']),\n",
    "                           tag_sets_id=mediacloud.tags.TAG_SET_CLIFF_PEOPLE)\n",
    "[t['tag'] for t in results[:10]]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What Organizations are Being Mentioned?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# let's which organizations are being mentioned most in stories about \"climate change\" in US national sources\n",
    "import mediacloud.tags\n",
    "results = mc.storyTagCount(\"timespans_id:{}\".format(overall_timespan['timespans_id']),\n",
    "                           tag_sets_id=mediacloud.tags.TAG_SET_CLIFF_ORGS)\n",
    "[t['tag'] for t in results[:10]]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What Places are Being Talked About?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# let's which places are being mentioned most in stories about \"climate change\" in US national sources\n",
    "import mediacloud.tags\n",
    "results = mc.storyTagCount(\"timespans_id:{}\".format(overall_timespan['timespans_id']),\n",
    "                           tag_sets_id=mediacloud.tags.TAG_SET_CLIFF_PLACES)\n",
    "[t['description'] for t in results[:10]]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}