Getting Started


The focalevents tools can be downloaded directly from Github, or cloned using git:

git clone

You can install any needed packages by navigating to the project directory and running:

pip install -r requirements.txt

You will also need to install PostgreSQL and create a database on the computer that you want to run this code. There are many online resources for installing PostgreSQL and configuring a database, so there are no utilities or instructions here for doing so.


The configuration file config.yaml specifies important information for connecting to different APIs and storing the data. Some of these fields need to be set before starting.

  1. Under keys, you need to provide API authorization tokens. Currently, focalevents only supports access to the Twitter API v2 using academic credentials.

  2. Under the psql field, you can provide information for connecting to the database. This includes the database name, user name, host, port, and password.

  3. The code outputs raw JSON to the directories specified under output.json. These can be changed from their defaults.

  4. The processed and organized data is stored in the PostgreSQL schema and tables specified under output.psql. The schema name can be changed from the default. It is not recommended to change the table names, as parts of this codebase may not be robust to those changes.

Once the database information and API tokens are set, go to the focalevents project directory and run:


This will create all of the necessary directories, schemas, and tables needed for reading and writing data.