Metadata-Version: 2.1
Name: equities
Version: 2.1.2
Summary: equities aims to democratize access to publicly available sec xlbr financial data.
Home-page: https://github.com/ljc-codes/equities.git
Author: Tiger Shark
Author-email: ljwcharles@gmail.com
License: UNKNOWN
Keywords: sec stock stockmarket equities equity scrapper parser pandas
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: alive-progress (==1.6.1)
Requires-Dist: chardet (==3.0.4)
Requires-Dist: idna (==2.7)
Requires-Dist: isort (==4.3.4)
Requires-Dist: matplotlib (==3.2.0)
Requires-Dist: numpy (==1.18.0)
Requires-Dist: pandas (==1.0.1)
Requires-Dist: psutil (==5.6.2)
Requires-Dist: pytz (==2018.5)
Requires-Dist: requests (==2.21.0)
Requires-Dist: six (==1.11.0)
Requires-Dist: tqdm (==4.43.0)
Requires-Dist: wrapt (==1.10.11)


# 🐋 equities 

## Overview: 

    equities allows for easy access to the SEC's XLBR Financial Statement 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

## Install: 

    pip3 install equities

## Donate: 

Consider donating bitcoin to fund the future development of this project. 

    bitcoin wallet address: 3LU5MEaAXRJoCo6vx67g1Jj7qDFRKhMs5t

## TUTORIAL: 

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

## Universe: 

#### Building the Universe

We begin by initializing our universe and downloading our sec data packages.

    from equities import Universe
    u = Universe()

    # Downloading data and building local storage.
    u.build()

#### Essential Methods 

To get the number of companies in the universe call: 
    print(len(u))

To get a dataframe of XLBR metadata from of all companies in the universe call: 

    print(u.properties())

"CIK" numbers are the sec's official unique identifier for public companies. To get a full list of the cik numbers call:

    print(u.ciks())

#### Accessing Companies

Universe objects are indexable by "CIK" integers. As an example, to access the first company in the universe call: 

    first_cik = universe.ciks()[0]
    print(u[first_cik]) # This prints an 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 import Company

#### Accessing the Financial Statements

Consider the first Company in our universe, universe[u.ciks()[0]]. It is a Company object. 

    c = u[u.ciks()[0]]

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

    c.income()      # income statement dataframe

    c.balance()     # Balancesheet dataframe

    c.cash()        # Cash Flow Statement dataframe

    c.equity()      # Consolidated Equity dataframe


#### Additional Company Details 

To get company XLBR metadata for a give company as a pandas series call: 

    c.properties()

#### Example 

I really want to demonstrate the beauty of this dataset as that is often difficult when looking
at thousands of numeric datatables. 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,
cashflow  statements and balance sheets of the first three companies in the universe.

To perform this experiment, run the following: 

    from equities import test
    test()

Here is the code that this function executes: 

    import pandas as pd
    from equities import Universe, Company
    import matplotlib.pyplot as plt

    u = Universe()
    u.build()

    k,f,s = 'bar',(20,10),True
    for cik in u.ciks()[:3]:

        u[cik].income().T.plot(
            kind=k,
            figsize=f,
            stacked=s)

        u[cik].cash().T.plot(
            kind=k,
            figsize=f,
            stacked=s)

        u[cik].balance().T.plot(
            kind=k,
            figsize=f,
            stacked=s)

    plt.show()


