Project documentation: https://model.calvin.sg
The Stock History Analysis project aims to determine the preferred portfolio composition from constituents within the S&P 500 index. This is achieved by analyzing historical stock data using various technical analysis models. The project is currently in its initial iteration and is a work in progress.
The primary objective of this iteration is to:
- Retrieve and clean historical stock data for analysis.
- Calculate key financial metrics that will serve as inputs for technical analysis models.
- Store historical stock price data with a suitable schema in Google Firestore document database.
- Prepare the groundwork for integrating various technical analysis models in future iterations.
The key implementation and rationale of the financial-modelling project are:
- Data Retrieval from stock data source: The
get_stock_data
function fetches historical stock data for a given ticker and period using theOpenBB
library fromyfinance
data source. - Data Retrieval from Firestore document database: Determine the most recent stock price data stored in database, to update with up to date data from stock data source.
- Firestore document database schema: Each ticker symbols is stored in a separate Firestore collection. Each collection contains documents of stock price data, with ISO 8601 date string as document id and fields storing stock price data.
- Data Processing: The retrieved data is cleaned and processed to calculate various metrics like closing price, percentage change, holding period yield, holding period return, and portfolio value assuming an initial investment of $1000.
- Main Execution: The main block of the notebook orchestrates the reading of ticker symbols and the retrieval of stock data for each symbol. The results are then appended to a list and printed in JSON format.
To use this project, follow these steps:
- Clone the GitHub repository to your local machine using
git clone https://github.com/calvindotsg/financial-modelling.git
. - Create a Python virtual environment for this project using
python -m venv venv
and activate it usingsource venv/bin/activate
(Linux/Mac) orvenv\Scripts\activate
(Windows). - Provide environment variables in the
./.env
file in your project directory. You can use the./.env.example
file as a template. Make sure to include Firebase service account key file in the./env
folder. - Install the required dependencies as per the
requirements.txt
file usingpip install -r requirements.txt
. - To run the project, execute the main script
python app.py
, in the following pathsrc/main/app.py
. This will initiate the analysis and provide insights into the preferred portfolio composition based on historical stock data.
To access accompanying Jupyter Notebook in this project, follow these steps:
- Ensure you have Jupyter Notebook or JupyterLab installed.
- Clone the repository and navigate to the project directory.
- Open the
notebooks/stock-history.ipynb
notebook. - Run the cells in sequence to perform the analysis.
The next steps for this project include:
- Integration of technical analysis models to evaluate stock performance.
- Optimization of portfolio composition based on historical performance and technical indicators.
- Development of a user interface to interact with the analysis results.
- Expansion of the dataset to include additional financial metrics and a broader range of stocks.
This repository follows a well-organized structure to enhance maintainability, modularity, and ease of collaboration. The key components include:
main/
: Contains the main application logic.data_models/
: Houses Pydantic data models.helpers/
: Stores helper functions.tests/
: TODO: Includes unit tests for application logic, data models, and helper functions.
app_config.py
: Centralized configuration file for application settings.
conf.py
: Sphinx configuration file.index.rst
: Main documentation file.
- Stores images used in documentation.
- Contains Jupyter notebooks for analysis or experimentation.
- Houses data sources, such as CSV files.
test_integration.py
: TODO: Integration tests.- Other test files organized by functionality.
- Lists project dependencies.
- Service account credential JSON files
How to cite, bibtex example:
@misc{Loh_Zeyrek_2024,
title={calvindotsg/Financial-modelling: Determine the preferred portfolio composition from constituents within the S&P 500 index},
author={Loh, Calvin and Zeyrek, Genevieve},
year={2024},
url={https://github.com/calvindotsg/financial-modelling/},
}
This project is available under the CC-BY-SA-4.0 License. This license enables reusers to distribute, remix, adapt, and build upon the material in any medium or format, so long as attribution is given to the creator. The license allows for commercial use. If you remix, adapt, or build upon the material, you must license the modified material under identical terms.
Contributions are welcome. If you would like to contribute to the project, please fork the repository and submit a pull request with your proposed changes.
For any queries or discussions regarding the project, please open an issue in the repository.
- Data provided by Yahoo Finance via the
OpenBB platform
library withyfinance
extension, (OpenBB Platform documentation). - S&P 500 company list sourced from the publicly available dataset on GitHub, provided by Rufus Pollock and the Open Knowledge Foundation, (GitHub Repo).
Disclaimer: This project is in the early stages of development and is subject to significant changes. The current functionality is limited to data retrieval and preliminary processing. Users should be aware that the analysis models are not yet implemented, and the results should not be used for actual trading or investment decisions.