equities 1.3.7

equities aims to democratize access to publically avaliable financial data.

🦈 equities

Overview:

equities is a python library that allows easy access to the SEC's XLBR dataset.
Parsed data is stored locally and served to the user in pandas dataframes. 

The Dataset:

https://www.sec.gov/dera/data/financial-statement-data-sets.html

TUTORIAL:

The library consists of two central objects, Universe and Company.

Universe:

A Universe should be thought of as a set of Companies. The universe object gives us the ability to download, access and purge our data.

from equities.objects import Universe

universe = Universe()

Note:

From the perspective of your computer, a universe is a little shell class that links to a location on your system. This location stores both the raw and parsed versions of our juicy sec data.

Downloading Data:

On first use the universe is empty. Before calling the download function we can optionally supply the universe with an array of quarters(str) and/or an array of "CIK" or "Central Index Key"(integers). A "CIK" number is a unique integer of 10 digits assigned to each company by the sec.

quarters = ["2019q1","2019q2","2019q3","2019q4","2020q1"] # quarters to be downloaded
ciks = 50 # limits parsing to first 50 companies/ciks. 

If no optional arguments are supplied, we will proceed to download the entire dataset and parse all companies.

To download data we call

universe.download(quarters=quarters,ciks=ciks)

The requested data will then be downloaded, parsed and saved locally. This means that anytime you reinstantiate the universe object, python remembers what you have already parsed.

A small note on deleting data. To delete all locally saved data call

universe.purge()

Note:

Note that calling the download function automatically purges the current universe before data is downloaded. It is critically important that you purge universes after use as data on your system will persistent even after you uninstall the package. If however, the use of pesistent data fits within the scope of what you're trying to do by all means use it. This was intended in the design. On a more personal note, one of my many qualms with open source financial data providers today is the limitations that come with having to GET requesting everything. Once parsed, data from the equities library is quickly and reliably accessed.

Core Functionality:

To see the number of companies in the universe we can do:

print(len(universe))

Universe objects are indexable by "CIK" integers. To get a full list of the cik numbers in the universe one can do:

print(universe.ciks)

A dataframe summary of all companies in the universe is included in:

print(universe.properties())

To access the first company in the above list you can do:

first_cik = universe.ciks[0]
print(universe[first_cik])

This returns a Company Object.

Company:

A Company object should be thought of as an abstract representation of a real company. Every company must have an associated Universe of origin.

from equities.object import Company

Accessing the Financial Statements

Consider the first Company in our universe, universe[first_cik]. It is a Company object.

company = universe[first_cik]

Dataframes of the company's financial statements over the universe in question is given by:

company.income()      # income statement dataframe

company.balance()     # Balancesheet dataframe

company.cash()        # Cash Flow Statement dataframe

company.equity()      # Consolidatad Equity dataframe

Additional Company Methods

company.name()        # Returns company name
company.sic()         # Returns company sic group

Example

I really want to demonstrate the beauty of this dataset as that is often difficult when looking at thousands of numeric datatables. So let's take a very naive peek by plotting various statements as a kind of stacked timeseries.

The following is a start to finish example of how one might plot the first quarter income statements of the companies below in the sec universe from 2016-2019.

Company CIKS:

1556593
1499200
1220754
917520
1040593
24741

Code:

# Import modules
import matplotlib.pyplot as plt
from equities.objects import Universe, Company

# Instantiate universe
u = Universe()

# Download data
quarters = ["2016q1,"2017q1","2018q1","2019q1"]
ciks = [1556593,1499200,1220754,917520,1040593,24741]
u.download(quarters=quarters,ciks=ciks)

# Plot Income Statements
for cik in ciks:
    income_df = u[cik].income()
    income_df.plot(kind="bar",
                   stacked=True,
                   fig_size=(20,10))
plt.show()

# Purge local data store
u.purge()