Skip to content

Commit

Permalink
convert README to md
Browse files Browse the repository at this point in the history
  • Loading branch information
@theOGognf
theOGognf committed Mar 28, 2024
1 parent e0bf3cd commit 0ff3bbb
Show file tree
Hide file tree
Showing 2 changed files with 65 additions and 45 deletions.
108 changes: 64 additions & 44 deletions README.rst → README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,24 +18,24 @@ Installation

Install with pip for the latest stable version.

.. code:: console
pip install finagg
```console
pip install finagg
```

Install from GitHub for the latest unstable version.

.. code:: console
git clone https://github.com/theOGognf/finagg.git
pip install ./finagg/
```console
git clone https://github.com/theOGognf/finagg.git
pip install ./finagg/
```

Optionally install the recommended datasets (economic data, company
financials, stock histories, etc.) from 3rd party APIs into a local SQL
database.

.. code:: console
finagg install -ss economic -ts indices -z -r
```console
finagg install -ss economic -ts indices -z -r
```

The installation will point you where to get free API keys for each API that
requires one and will write those API keys to a local ``.env`` file for storage.
Expand All @@ -44,7 +44,7 @@ Run ``finagg install --help`` for more installation options and details.
Basic Usage
-----------

These are just **finagg** usage samples. See the `documentation`_ for all the
These are just **finagg** usage samples. See the [documentation][4] for all the
supported APIs and features.

Explore the APIs directly
Expand All @@ -54,16 +54,19 @@ Explore the APIs directly

Get Bureau of Economic Analysis (BEA) data.

```pycon
>>> finagg.bea.api.gdp_by_industry.get(year=[2019]).head(5)
table_id freq year quarter industry industry_description ...
0 1 Q 2019 1 11 Agriculture, forestry, fishing, and hunting ...
1 1 Q 2019 1 111CA Farms ...
2 1 Q 2019 1 113FF Forestry, fishing, and related activities ...
3 1 Q 2019 1 21 Mining ...
4 1 Q 2019 1 211 Oil and gas extraction ...
```

Get Federal Reserve Economic Data (FRED).

```pycon
>>> finagg.fred.api.series.observations.get(
... "CPIAUCNS",
... realtime_start=0,
Expand All @@ -76,16 +79,19 @@ Get Federal Reserve Economic Data (FRED).
2 1949-06-24 1953-02-26 1949-05-01 169.2 CPIAUCNS
3 1949-07-22 1953-02-26 1949-06-01 169.6 CPIAUCNS
4 1949-08-26 1953-02-26 1949-07-01 168.5 CPIAUCNS
```

Get Securities and Exchange Commission (SEC) filings.

```pycon
>>> finagg.sec.api.company_facts.get(ticker="AAPL").head(5)
end value accn fy fp form filed ...
0 2009-06-27 895816758.0 0001193125-09-153165 2009 Q3 10-Q 2009-07-22 ...
1 2009-10-16 900678473.0 0001193125-09-214859 2009 FY 10-K 2009-10-27 ...
2 2009-10-16 900678473.0 0001193125-10-012091 2009 FY 10-K/A 2010-01-25 ...
3 2010-01-15 906794589.0 0001193125-10-012085 2010 Q1 10-Q 2010-01-25 ...
4 2010-04-09 909938383.0 0001193125-10-088957 2010 Q2 10-Q 2010-04-21 ...
```

Use installed raw data for exploring the most popular features
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -96,6 +102,7 @@ downloading and installing raw data through the* ``finagg install`` *or*

Get the most popular FRED features all in one dataframe.

```pycon
>>> finagg.fred.feat.economic.from_raw().head(5)
CIVPART LOG_CHANGE(CPIAUCNS) LOG_CHANGE(CSUSHPINSA) FEDFUNDS ...
date ...
Expand All @@ -104,9 +111,11 @@ date ...
2014-10-13 62.8 0.0 0.0 0.09 ...
2014-10-15 62.8 0.0 0.0 0.09 ...
2014-10-20 62.8 0.0 0.0 0.09 ...
```

Get quarterly report features from SEC data.

```pycon
>>> finagg.sec.feat.quarterly.from_raw("AAPL").head(5)
LOG_CHANGE(Assets) LOG_CHANGE(AssetsCurrent) ...
fy fp filed ...
Expand All @@ -115,9 +124,11 @@ fy fp filed ...
Q3 2010-07-21 0.000000 0.000000 ...
2011 Q1 2011-01-19 0.459174 0.278241 ...
Q2 2011-04-21 0.000000 0.000000 ...
```

Get an aggregation of quarterly and daily features for a particular ticker.

```pycon
>>> finagg.fundam.feat.fundam.from_raw("AAPL").head(5)
PriceBookRatio PriceEarningsRatio
date
Expand All @@ -126,6 +137,7 @@ date
2010-01-27 0.178813 2.475448
2010-01-28 0.177154 2.452471
2010-01-29 0.173825 2.406396
```

Use installed features for exploring refined aggregations of raw data
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -135,6 +147,7 @@ Use installed features for exploring refined aggregations of raw data

Get a ticker's industry's averaged quarterly report features.

```pycon
>>> finagg.sec.feat.quarterly.industry.from_refined(ticker="AAPL").head(5)
mean ...
name AssetCoverageRatio BookRatio DebtEquityRatio ...
Expand All @@ -144,9 +157,11 @@ fy fp filed ...
Q3 2014-11-14 10.731301 9.448954 0.158318 ...
2015 Q1 2015-05-15 16.738972 9.269250 0.294238 ...
Q2 2015-08-13 16.738972 9.269250 0.294238 ...
```

Get a ticker's industry-averaged quarterly report features.

```pycon
>>> finagg.sec.feat.quarterly.normalized.from_refined("AAPL").head(5)
NORM(LOG_CHANGE(Assets)) NORM(LOG_CHANGE(AssetsCurrent)) ...
fy fp filed ...
Expand All @@ -155,22 +170,27 @@ fy fp filed ..
2011 Q1 2011-01-19 0.978816 0.074032 ...
Q2 2011-04-21 0.000000 0.000000 ...
Q3 2011-07-20 -0.353553 -0.353553 ...
```

Get tickers sorted by an industry-averaged quarterly report feature.

```pycon
>>> finagg.sec.feat.quarterly.normalized.get_tickers_sorted_by(
... "NORM(EarningsPerShareBasic)",
... year=2019
... )[:5]
['XRAY', 'TSLA', 'SYY', 'WHR', 'KMB']
```

Get tickers sorted by an industry-averaged fundamental feature.

```pycon
>>> finagg.fundam.feat.fundam.normalized.get_tickers_sorted_by(
... "NORM(PriceEarningsRatio)",
... date="2019-01-04"
... )[:5]
['AMD', 'TRGP', 'HPE', 'CZR', 'TSLA']
```

Configuration
=============
Expand All @@ -185,9 +205,9 @@ APIs programmatically. The following environment variables are used for
configuring API keys and user agents:

* ``BEA_API_KEY`` is for the Bureau of Economic Analysis's API key. You can get
a free API key from the `BEA API site`_.
a free API key from the [BEA API site][3].
* ``FRED_API_KEY`` is for the Federal Reserve Economic Data API key. You can get
a free API key from the `FRED API site`_.
a free API key from the [FRED API site][8].
* ``INDICES_API_USER_AGENT`` is for scraping popular indices' compositions from
Wikipedia and should be equivalent to a browser's user agent declaration.
This defaults to a hardcoded value, but it may not always work.
Expand All @@ -212,29 +232,29 @@ locations by modifying the respective environment variables:
Dependencies
============

* `pandas`_ for fast, flexible, and expressive representations of relational data.
* `requests`_ for HTTP requests to 3rd party APIs.
* `requests-cache`_ for caching HTTP requests to avoid getting throttled by 3rd
* [pandas][11] for fast, flexible, and expressive representations of relational data.
* [requests][12] for HTTP requests to 3rd party APIs.
* [requests-cache][13] for caching HTTP requests to avoid getting throttled by 3rd
party API servers.
* `SQLAlchemy`_ for a SQL Python interface.
* `yfinance`_ for historical stock data from Yahoo! Finance.
* [SQLAlchemy][17] for a SQL Python interface.
* [yfinance][18] for historical stock data from Yahoo! Finance.

API References
==============

* The `BEA API`_ and the `BEA API key registration link`_.
* The `FRED API`_ and the `FRED API key registration link`_.
* The `SEC API`_.
* The [BEA API][1] and the [BEA API key registration link][2].
* The [FRED API][6] and the [FRED API key registration link][7].
* The [SEC API][14].

Related Projects
================

* `FinRL`_ is a collection of financial reinforcement learning environments
* [FinRL][5] is a collection of financial reinforcement learning environments
and tools.
* `fredapi`_ is an implementation of the FRED API.
* `OpenBBTerminal`_ is an open-source version of the Bloomberg Terminal.
* `sec-edgar`_ is an implementation of a file-based SEC EDGAR parser.
* `sec-edgar-api`_ is an implementation of the SEC EDGAR REST API.
* [fredapi][9] is an implementation of the FRED API.
* [OpenBBTerminal][10] is an open-source version of the Bloomberg Terminal.
* [sec-edgar][15] is an implementation of a file-based SEC EDGAR parser.
* [sec-edgar-api][16] is an implementation of the SEC EDGAR REST API.

Frequently Asked Questions
==========================
Expand Down Expand Up @@ -277,21 +297,21 @@ using Linux or WSL in practice. The package performs a good amount of I/O and
interprocess operations that could result in a noticeable performance
degradation on Windows.

.. _`BEA API`: https://apps.bea.gov/api/signup/
.. _`BEA API key registration link`: https://apps.bea.gov/API/signup/
.. _`BEA API site`: https://apps.bea.gov/API/signup/
.. _`documentation`: https://theogognf.github.io/finagg/
.. _`FinRL`: https://github.com/AI4Finance-Foundation/FinRL
.. _`FRED API`: https://fred.stlouisfed.org/docs/api/fred/
.. _`FRED API key registration link`: https://fredaccount.stlouisfed.org/login/secure/
.. _`FRED API site`: https://fredaccount.stlouisfed.org/login/secure/
.. _`fredapi`: https://github.com/mortada/fredapi
.. _`OpenBBTerminal`: https://github.com/OpenBB-finance/OpenBBTerminal
.. _`pandas`: https://pandas.pydata.org/
.. _`requests`: https://requests.readthedocs.io/en/latest/
.. _`requests-cache`: https://requests-cache.readthedocs.io/en/stable/
.. _`SEC API`: https://www.sec.gov/edgar/sec-api-documentation
.. _`sec-edgar`: https://github.com/sec-edgar/sec-edgar
.. _`sec-edgar-api`: https://github.com/jadchaar/sec-edgar-api
.. _`SQLAlchemy`: https://www.sqlalchemy.org/
.. _`yfinance`: https://github.com/ranaroussi/yfinance
[1]: https://apps.bea.gov/api/signup/
[2]: https://apps.bea.gov/API/signup/
[3]: https://apps.bea.gov/API/signup/
[4]: https://theogognf.github.io/finagg/
[5]: https://github.com/AI4Finance-Foundation/FinRL
[6]: https://fred.stlouisfed.org/docs/api/fred/
[7]: https://fredaccount.stlouisfed.org/login/secure/
[8]: https://fredaccount.stlouisfed.org/login/secure/
[9]: https://github.com/mortada/fredapi
[10]: https://github.com/OpenBB-finance/OpenBBTerminal
[11]: https://pandas.pydata.org/
[12]: https://requests.readthedocs.io/en/latest/
[13]: https://requests-cache.readthedocs.io/en/stable/
[14]: https://www.sec.gov/edgar/sec-api-documentation
[15]: https://github.com/sec-edgar/sec-edgar
[16]: https://github.com/jadchaar/sec-edgar-api
[17]: https://www.sqlalchemy.org/
[18]: https://github.com/ranaroussi/yfinance
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ dependencies = [
]
dynamic = ["version"]
license = {file = "LICENSE"}
readme = "README.rst"
readme = "README.md"
requires-python = ">=3.10"

[project.scripts]
Expand Down

0 comments on commit 0ff3bbb

Please sign in to comment.