>ƒFinForge

FinForge - Complete User Guide

Welcome to FinForge! This comprehensive guide covers everything you need to know to use the application effectively.

Table of Contents

  1. Getting Started
  2. Ticker Management
  3. Importing Data to Excel
  4. Creating Financial Ratios
  5. Assigning Ratios to Excel
  6. Advanced Ratio Features
  7. Quick Reference
  8. Available Data Reference
  9. Color Reference
  10. Data Cleanup System
  11. Troubleshooting
  12. Ranking Tab

1. Getting Started

What is FinForge?

FinForge is a financial analysis tool that:

  • Fetches real-time stock data from Yahoo Finance
  • Stores data efficiently in Parquet format
  • Imports financial statements into Excel
  • Lets you create custom financial ratios
  • Calculates and displays ratios for multiple tickers

Quick Start

Step 1: Launch the Application

Option A - Using the Batch File (Recommended)

  1. Double-click launch_finforge.bat in the main folder
  2. The FinForge window will open

Step 2: Open the Workspace

  1. In the launcher, click Open terminal
  2. The main workspace opens with a collapsible sidebar: Overview (Home, Search), Data (Statement Lines, Metrics, Rates), Models (Visualize, Ranking, DCF) and System (Templates, Settings)

Step 3: Add Your First Ticker

  1. Go to the Search tab
  2. Type a ticker symbol (e.g., AAPL) in the search bar
  3. Select the ticker from search results and add it to the import list
  4. Data fetching starts automatically in the background

Step 4: Import Financial Data to Excel

  1. In the Statement Lines tab, choose Balance sheet or Income statement scope
  2. Select the line items you want to print
  3. Click Import to send data to Excel

System Requirements

  • Windows 10 or later
  • Microsoft Excel (with macros enabled)
  • Python 3.10+ (included in .venv)
  • Node.js 18+ (for Electron, auto-installed by setup)
  • Internet connection (for data fetching)

First-Time Setup

If this is your first time using the app:

  1. Run setup.bat to install all dependencies
  2. Enable Excel Macros
    • Open Excel, go to File > Options > Trust Center
    • Click Trust Center Settings > Macro Settings
    • Select “Enable all macros”

Folder Structure

FinForge/
  FinForge.xlsm             <- Main Excel workbook
  launch_finforge.bat       <- Quick launcher
  setup.bat                 <- First-time setup
  data/                     <- All fetched data stored here
    fundamentals/           <- Financial statements
    holders/                <- Holder information
    metadata/               <- Company info
    prices/                 <- Price history
  ElectronHome/             <- Electron desktop UI
  Guides/                   <- Documentation
    User/                   <- User guides
    Developer/              <- Technical docs
  Importing/                <- Import scripts
  Internal/                 <- Core modules
  Ticker_management/        <- Ticker CRUD
  data_management/          <- Data persistence

2. Ticker Management

Learn how to add, edit, and manage stock tickers in your portfolio.

Opening the Ticker Manager

The ticker management is built into FinForge. Launch it by:

  • Double-clicking launch_finforge.bat, or
  • Running from command line (see Getting Started)

Adding Tickers

Single Ticker

  1. Type the ticker symbol in the input field (e.g., MSFT)
  2. Click Add or press Enter
  3. The ticker appears in the list
  4. Data fetching starts automatically in the background

Example:

Input: AAPL
Result: Apple Inc. added to list, data fetching begins

Validation Rules

  • Tickers must be 1-5 letters only
  • No numbers or special characters
  • Duplicates are not allowed

Removing Tickers

Delete a Single Ticker

  1. Find the ticker in the list
  2. Click the X (delete) button next to it
  3. Confirm the deletion

What Happens to the Data?

When you remove a ticker:

  1. The ticker is removed from your list immediately
  2. The data is scheduled for deletion in 3 days
  3. If you re-add the ticker within 3 days, the data is preserved
  4. After 3 days, data is permanently deleted on next app launch

Editing Tickers

  1. Find the ticker in the list
  2. Click the Edit button
  3. Enter the new ticker symbol
  4. Click OK

Note: Editing a ticker schedules the old ticker’s data for deletion.

Selecting Tickers for Launch

When launching the Excel dashboard:

  1. Click on tickers to select/deselect them
  2. Selected tickers will be highlighted
  3. Click Launch Dashboard to open Excel with selected tickers

Fetching Data

Automatic Fetching

Data is fetched automatically when you:

  • Add a new ticker
  • Launch the dashboard with tickers that need updates

What Data is Fetched?

For each ticker, the app fetches:

Category Data Types
Financials Income statement, balance sheet, cash flow (annual and quarterly)
Analyst Earnings estimates, revenue estimates, price targets, recommendations
Holders Major, institutional, mutual fund holders, insider roster
Insider Transactions, purchases summary
Historical Dividends, splits, price history
Other News, SEC filings, calendar, company info

Where is Ticker Data Stored?

Tickers are saved in: data/tickers.json

{
  "tickers": ["MSFT", "AAPL", "GOOGL"]
}

Stock data is stored in: data/ folder as Parquet files

3. Importing Data to Excel

Learn how to import financial statement data from your stored Parquet files into Excel.

Overview

The import system transfers data from Parquet files to your Excel workbook:

  • Balance sheet data goes to the “balance sheets” sheet
  • Income statement data goes to the “income statements” sheet

Prerequisites

Before importing:

  1. Have tickers with fetched data (see Ticker Management)
  2. Have Excel workbook open (FinForge.xlsm)
  3. Tickers should be listed in Row 4 of the respective sheet

Importing Balance Sheets

From Excel (VBA Macro)

  1. Open FinForge.xlsm
  2. Go to the “balance sheets” sheet
  3. Run the macro: ImportBalanceSheets()
    • Press Alt + F8
    • Select ImportBalanceSheets
    • Click Run

From Python

cd <your-finforge-folder>
.\.venv\Scripts\Activate.ps1
python -c "from Importing.import_balance_sheets import main; main()"

What Gets Imported

Row Content
4 Ticker symbols (you place these)
5 Most recent date
6 Second most recent date
7+ Financial line items

Example Layout:

       A          B              C              D
4   INDEX       MSFT           AAPL           GOOGL
5              2024-06-30     2024-06-30     2024-06-30
6              2024-03-31     2024-03-31     2024-03-31
7   Total Assets  $411.9B       $352.5B        $402.3B
8   Cash          $18.3B        $28.4B         $24.0B
...

Importing Income Statements

From Excel (VBA Macro)

  1. Open FinForge.xlsm
  2. Go to the “income statements” sheet
  3. Run the macro: ImportIncomeStatements()
    • Press Alt + F8
    • Select ImportIncomeStatements
    • Click Run

From Python

cd <your-finforge-folder>
.\.venv\Scripts\Activate.ps1
python -c "from Importing.import_income_statements import main; main()"

Customizing Which Items to Import

Using the Settings Sheet

  1. Go to the “Settings” sheet in Excel
  2. Find the section for Balance Sheet or Income Statement items
  3. List the items you want to import (one per row)
  4. Run the import again

Example Settings:

Balance Sheet Items:
  Total Assets
  Total Liabilities
  Stockholders Equity
  Cash And Cash Equivalents
  Total Debt

Understanding Color Codes

After importing, cells are color-coded:

Color Meaning
Orange text Data found and imported successfully
Red text Data not available for this ticker
White text Empty/no value

Tips for Successful Imports

Setting Up Tickers

  1. In the import sheet (balance sheets or income statements)
  2. Go to Row 4
  3. Column A should say “INDEX”
  4. Enter ticker symbols in columns B, C, D, etc.

Example:

Row 4: INDEX | MSFT | AAPL | GOOGL | AMZN

After Adding New Tickers

  1. First, fetch data using the launcher or fetch script
  2. Then run the import macro
  3. Data will populate for the new tickers

Refreshing Data

To update with latest data:

  1. Run the fetch script to get new data from Yahoo Finance
  2. Run the import macro to update Excel

4. Creating Financial Ratios

Learn how to create custom financial ratios using the Ratio Maker tool.

What are Financial Ratios?

Financial ratios are calculations that use financial statement data to measure:

  • Profitability (e.g., Profit Margin, ROE)
  • Liquidity (e.g., Current Ratio, Quick Ratio)
  • Leverage (e.g., Debt-to-Equity)
  • Efficiency (e.g., Asset Turnover)
  • Valuation (e.g., P/E Ratio, P/B Ratio)

Opening the Ratio Maker

From Excel

  1. Open FinForge.xlsm
  2. Run the macro: OpenRatioMaker()
    • Press Alt + F8
    • Select OpenRatioMaker
    • Click Run

From Python

cd <your-finforge-folder>
.\.venv\Scripts\Activate.ps1
python Importing/ratio_maker.py

Built-in Ratios

FinForge ships with a ready-made set of the most widely used financial ratios, so you do not have to build them yourself before you can analyse a company.

They live inside the built-in Beginning Template. Open the Templates tab and the Beginning Template is listed with a lock icon. Select it and click Load template to copy its ratios into your workspace. The Metrics tab then lists all of them, grouped by category:

Category Examples
Liquidity Current Ratio, Quick Ratio, Cash Ratio, Working Capital, Operating Cash Flow Ratio
Profitability Gross Margin, Operating Margin, Net Profit Margin, EBITDA Margin, Return on Assets, Return on Equity, Return on Invested Capital, Return on Capital Employed
Efficiency Asset Turnover, Inventory Turnover, Receivables Turnover, Days Sales Outstanding, Cash Conversion Cycle
Leverage and Solvency Debt to Equity, Debt to Assets, Net Debt to EBITDA, Interest Coverage, Equity Multiplier
Cash Flow Operating Cash Flow Margin, Free Cash Flow Margin, Cash Flow to Net Income, Dividend Payout Ratio
Valuation P/E Ratio, PEG Ratio, Price to Book, EV/EBITDA, EV/Revenue, Dividend Yield
Growth and Per Share Revenue Growth YoY, EPS Growth YoY, Book Value per Share, Free Cash Flow per Share

Notes on how they behave:

  1. Most ratios are calculated from the financial statements, so they follow the statement periods and produce a history you can chart.
  2. The Valuation ratios come from live market data and show a single current value rather than a history. That is a limit of the data provider, not of the ratio.
  3. Growth ratios report percentages, so 12.5 means twelve and a half percent. All other ratios report a decimal fraction, so 0.125 means twelve and a half percent.
  4. Each ratio carries a short note explaining what it measures.

The Beginning Template itself cannot be edited or deleted. You can still change any of its ratios after loading it, and you can add, rename or delete your own ratios as usual.

Creating Your First Ratio

Step 1: Click “New Ratio”

The Create Ratio dialog opens.

Step 2: Enter Ratio Name

Give your ratio a descriptive name:

  • “Gross Margin”
  • “Current Ratio”
  • “Debt to Equity”

Step 3: Build the Formula

Use the field selector and operators to build your formula.

Available Data Sources:

Prefix Source Example Fields
IS: Income Statement Total Revenue, Net Income, EBITDA
BS: Balance Sheet Total Assets, Total Debt, Cash
CF: Cash Flow Operating Cash Flow, Free Cash Flow
RATIO: Other Ratios Use your previously created ratios

Available Operators:

Button Operation
+ Addition
- Subtraction
* Multiplication
/ Division
( Open parenthesis
) Close parenthesis

Step 4: Add Notes (Optional)

Add a description or notes about the ratio:

  • What it measures
  • How to interpret it
  • Reference ranges

Step 5: Save

Click Save to store the ratio in ratio_config.json.

Formula Examples

Profitability Ratios

Gross Margin

(IS: Total Revenue - IS: Cost Of Revenue) / IS: Total Revenue

Operating Margin

IS: Operating Income / IS: Total Revenue

Net Profit Margin

IS: Net Income / IS: Total Revenue

Return on Assets (ROA)

IS: Net Income / BS: Total Assets

Return on Equity (ROE)

IS: Net Income / BS: Stockholders Equity

Liquidity Ratios

Current Ratio

BS: Current Assets / BS: Current Liabilities

Quick Ratio

(BS: Current Assets - BS: Inventory) / BS: Current Liabilities

Leverage Ratios

Debt to Equity

BS: Total Debt / BS: Stockholders Equity

Debt to Assets

BS: Total Debt / BS: Total Assets

Efficiency Ratios

Asset Turnover

IS: Total Revenue / BS: Total Assets

Using Other Ratios

ROE using DuPont Analysis

RATIO: Net Profit Margin * RATIO: Asset Turnover * RATIO: Equity Multiplier

Understanding Syntax Highlighting

As you type, the formula is color-coded:

Color Meaning
Green Income Statement fields (IS:)
Light Blue Balance Sheet fields (BS:)
Purple Price/Cash Flow fields
Orange Operators (+, -, *, /)
Yellow Parentheses
Gold Other Ratios (RATIO:)
Light Blue Numbers
Red + Wavy Errors (typos, invalid fields)

Editing Existing Ratios

  1. Select the ratio in the list
  2. Click Edit
  3. Modify the name, formula, or notes
  4. Click Save

Note: If the ratio is assigned to an Excel column, the column header is automatically updated with the new name.

Deleting Ratios

  1. Select the ratio in the list
  2. Click Delete
  3. Confirm the deletion

Warning: If the ratio is assigned to an Excel column, unassign it first.

Where are Ratios Stored?

Ratios are saved in: Importing/ratio_config.json

The file is a flat map of ratio name to definition:

{
  "Gross Margin": {
    "formula": "(IS: Total Revenue - IS: Cost Of Revenue) / IS: Total Revenue",
    "notes": "Measures profitability after direct costs",
    "row": "",
    "folder": "Profitability"
  },
  "Current Ratio": {
    "formula": "BS: Current Assets / BS: Current Liabilities",
    "notes": "Measures short-term liquidity",
    "row": "",
    "folder": "Liquidity"
  }
}
Field Meaning
formula The calculation. Uses BS:, IS:, CF:, P:, M: and other references.
notes Optional description shown in the Metrics tab.
row Optional fixed row in the Excel Metrics sheet. Leave empty to auto-assign from row 7.
folder Category used by the folder filter and the Folders subtab. Leave empty for ungrouped.

Tips for Creating Good Ratios

  1. Use descriptive names - “Gross Margin” not “GM1”
  2. Add notes - Document what the ratio measures
  3. Test with known values - Verify calculations are correct
  4. Use parentheses - Ensure correct order of operations
  5. Check field names - Use exact field names from the data

5. Assigning Ratios to Excel

Learn how to assign your created metrics to rows in Excel for automatic calculation.

Key Features

What You Can Do:

  1. Assign Metrics: Give any saved metric a row in Column A of the Metrics sheet
  2. View Status: See every metric and whether it has a row yet
  3. View Notes: Read the notes saved with a metric
  4. Calculate Metrics: Compute every assigned metric for every ticker using Parquet data
  5. Tickers: Tickers come from Row 4, so the ones you imported in the Statement Lines tab are used automatically

Benefits:

  • Fast: Uses Parquet data for quick calculations
  • Reliable: Minimal VBA, all logic in Python
  • Simple: Clean UI with clear feedback
  • Flexible: Any metric can sit in any free row

Excel Layout (Metrics Sheet)

The Metrics sheet is a grid: metric names run down Column A, and one column per ticker runs across Row 4.

Row 4:  ticker symbols in row 4
        A4: empty, B4: AAPL, C4: MSFT, D4: GOOGL
Row 5:  reserved, left empty
Row 6:  reserved, left empty
Row 7:  A7: Current Ratio, B7: 1.2500, C7: 1.3000, D7: 1.1800
Row 8:  A8: Quick Ratio,   B8: 0.8500, C8: 0.9200, D8: 0.7800
Row 9:  A9: Debt to Equity, B9: 0.4500, C9: 0.3800, D9: 0.5200

Column Structure:

  • Column A: Metric names, written by FinForge from Row 7 onwards
  • Columns B onwards: Ticker symbols in Row 4, calculated values below

Row Functions:

  • Row 4: Ticker symbols, plus the special INDEX and CUSTOM column types
  • Rows 5 and 6: Reserved and left empty
  • Row 7+: Metric names in Column A and their calculated values per ticker

A column marked INDEX in Row 4 is filled with the metric names, mirroring the balance sheet and income statement sheets. A column marked CUSTOM is never touched by FinForge, so your own formulas there stay intact.

How to Use

Step 1: Create Your Metrics

Metrics are created in the Metrics tab of the FinForge workspace, or loaded from the built-in Beginning Template (see Creating Ratios).

Step 2: Assign a Row to Each Metric

  1. Open the FinForge workspace
  2. Go to the Metrics tab
  3. Click the Assignments subtab
  4. Every saved metric is listed with a row box on the right
  5. Type the row it should occupy in Column A (7 or higher) and press Enter

Rules:

  • Rows must be 7 or higher - the earlier rows are reserved for headers
  • Two metrics cannot share a row - a duplicate row is flagged in red
  • Leave a row box empty to keep a metric out of the sheet (shown as N/A)
  • Metrics are written to Column A in row order, so gaps are allowed

Step 3: View Metric Notes

Notes are stored with each metric. Open the metric in the Metrics tab, or read its notes field in Importing/ratio_config.json.

Step 4: Set the Tickers

Tickers are read from Row 4 of the Metrics sheet, columns B onwards. They come from the tickers you imported in the Statement Lines tab, so there is normally nothing to type.

Step 5: Calculate the Metrics

From the FinForge Workspace:

  1. Go to the Metrics tab
  2. Click Refresh metrics sheet in the Actions panel

From Python:

python -c "from Internal.Ratios.ratio_calculator import calculate_ratios; calculate_ratios()"

What Happens:

  • The system reads the tickers from Row 4 and the metric names from Column A
  • Loads financial data from the Parquet files
  • Calculates each assigned metric for each ticker
  • Writes the results into the matching cells
  • Reports progress while it runs

Step 6: Update an Assignment

  1. Go back to the Assignments subtab
  2. Change the row number for the metric, or clear it to remove it
  3. Click Refresh metrics sheet so the sheet is rewritten for the new layout

Excel Ribbon

The FinForge add-in adds a FinForge tab with two groups:

  • Dashboard > Dashboard opens the FinForge app
  • Formulas > Refresh Custom Formulas regenerates the FF.* worksheet functions from your saved metrics

The sheet refresh itself is driven from the workspace, so there is no separate macro to run in Excel.

Example Workflow

Complete Example:

  1. Create the metrics in the Metrics tab

    • Current Ratio: BS: Current Assets / BS: Current Liabilities
    • Quick Ratio: BS: Cash / BS: Current Liabilities

  2. Assign rows in the Assignments subtab

    • Current Ratio > row 7
    • Quick Ratio > row 8

  3. Check the tickers in Row 4 of the Metrics sheet

    B4: AAPL    C4: MSFT    D4: GOOGL

  4. Calculate

    • Click Refresh metrics sheet in the Metrics tab
    • See results:
    B7: 1.2500    C7: 1.3000    D7: 1.1800
B8: 0.8500    C8: 0.9200    D8: 0.7800

  5. Update if Needed

    • Change a row number in the Assignments subtab, then refresh again

Best Practices

  1. Create metrics first before trying to assign rows
  2. Import tickers before calculating, so Row 4 is populated
  3. Use meaningful metric names for easy identification
  4. Add notes to metrics to remember what they do
  5. Refresh data regularly to keep metrics up to date
  6. Save the workbook after a refresh

6. Advanced Ratio Features

Horizontal Operator Layout

All operators and buttons are arranged left-to-right for an intuitive workflow.

Operator Buttons:

  • + Addition
  • - Subtraction
  • * Multiplication
  • / or division sign Division (toggleable)
  • ( Opening parenthesis
  • ) Closing parenthesis

Real-Time Syntax Highlighting

As you type or insert items, the formula is immediately color-coded:

Element Color Example
Operators Orange (#FF9800) +, -, *, /
Brackets Yellow (#FFD700) (, )
Income Statement Green (#81C784) IS: Revenue, IS: Net Income
Balance Sheet Light Blue (#81D4FA) BS: Total Assets, BS: Cash
Price Data Purple (#CE93D8) P: Closing Price
Functions Yellow-Orange (#FFC107) AVERAGE, SUM, MAX
Numbers Light Blue (#90CAF9) 100, 1.5, 0.25
Errors Red (#F44336) Invalid fields, typos

Error Detection and Highlighting

Invalid tokens are automatically detected and marked with:

  • Red text color
  • Wavy red underline

Examples of errors:

  • Typos: IS: Reveneu (misspelled)
  • Invalid fields: XYZ: Unknown
  • Incomplete operators: IS: Revenue + (missing right operand)

Advanced Functions

Advanced functions are coming soon. Currently supported features include:

  • Basic price data (Close, Open, High, Low, Volume)
  • Historical price offsets using [-XD] syntax
  • Calculated fields (Change, Change Percent)

Color Legend

A built-in color legend appears above the formula preview showing:

Operators  Brackets  IS: Items  BS: Items  P: Items  Errors

Each bullet is colored to match its syntax highlighting.

Usage Examples

Example 1: Simple Ratio with Highlighting

Gross Margin Formula:

(IS: Revenue - IS: Cost of Revenue) / IS: Revenue

How it appears:

  • ( and ) in yellow
  • IS: Revenue in green
  • - and / in orange
  • IS: Cost of Revenue in green

Example 2: Price Data with Historical Offset

10-Day Price Change Percent:

P: Change Percent [-10D]

How it appears:

  • P: Change Percent in purple
  • [-10D] offset in brackets
  • ( and ) in yellow
  • IS: Revenue in green
  • 50 in light blue

Example 3: Error Detection

Typo in field name:

IS: Reveneu / IS: Cost

How it appears:

  • IS: in green (valid prefix)
  • Reveneu in red with wavy underline (invalid field)
  • / in orange
  • IS: Cost in red with wavy underline (incomplete field name)

Best Practices

Use Color Feedback

  • Green/Blue/Purple = Valid fields
  • Orange/Yellow = Valid operators/brackets
  • Red = Fix immediately!

Validation Before Saving

  1. Check for red errors
  2. Verify all fields are green, blue, or purple
  3. Ensure operators are orange or yellow

7. Quick Reference

Color Guide (At-a-Glance)

Orange     >  Operators       >  + - * /
Yellow     >  Brackets        >  ( )
Green      >  IS: Items       >  Revenue, Net Income, EBITDA
Light Blue >  BS: Items       >  Total Assets, Cash, Debt
Purple     >  P: Items        >  Close Price, Change Percent
Light Blue >  Numbers         >  100, 1.5, 3.14
Red + Wave >  Errors          >  Typos, invalid fields

Button Layout (Horizontal)

Operators:  [ + ]  [ - ]  [ * ]  [ / ]  [ ( ]  [ ) ]

Common Formulas

Gross Margin

(IS: Revenue - IS: Cost of Revenue) / IS: Revenue

Current Ratio

BS: Current Assets / BS: Current Liabilities

P/E Ratio

P: Closing Price / IS: Earnings Per Share

ROE (Return on Equity)

IS: Net Income / BS: Total Equity

Debt-to-Equity

BS: Total Debt / BS: Total Equity

Operating Margin

IS: Operating Income / IS: Revenue

Working Capital

BS: Current Assets - BS: Current Liabilities

Pre-Save Checklist

  1. No red errors
  2. All fields are green/blue/purple
  3. Operators are orange/yellow
  4. Brackets match
  5. Formula makes sense

Quick Actions

Action How
Add field Select > Insert Field
Add operator Click operator button
Add function Click Advanced Functions
Add notes Click Notes
Save ratio Click green Save
Cancel Click Cancel

File Locations

  • Ratio Config: Importing/ratio_config.json
  • Main App: Importing/ratio_maker.py

8. Available Data Reference

This section lists all data fetched from Yahoo Finance and stored in Parquet format.

Data Storage Structure

data/
  fundamentals/
    income_statement/{TICKER}.parquet
    balance_sheet/{TICKER}.parquet
    cash_flow/{TICKER}.parquet
    quarterly_income_statement/{TICKER}.parquet
    quarterly_balance_sheet/{TICKER}.parquet
    quarterly_cash_flow/{TICKER}.parquet
    earnings_estimate/{TICKER}.parquet
    revenue_estimate/{TICKER}.parquet
    analyst_price_targets/{TICKER}.parquet
    eps_trend/{TICKER}.parquet
    growth_estimates/{TICKER}.parquet
    earnings_history/{TICKER}.parquet
    recommendations/{TICKER}.parquet
    recommendations_summary/{TICKER}.parquet
    upgrades_downgrades/{TICKER}.parquet
    insider_transactions/{TICKER}.parquet
    insider_purchases/{TICKER}.parquet
    calendar/{TICKER}.parquet
    dividends/{TICKER}.parquet
    splits/{TICKER}.parquet
    actions/{TICKER}.parquet
    news/{TICKER}.parquet
    sec_filings/{TICKER}.parquet
  holders/
    major_holders/{TICKER}.parquet
    institutional_holders/{TICKER}.parquet
    mutualfund_holders/{TICKER}.parquet
    insider_roster_holders/{TICKER}.parquet
  prices/
    {TICKER}.parquet
  metadata/
    {TICKER}.json

Income Statement Fields

Field Description
Total Revenue Total revenue from all sources
Operating Revenue Revenue from core operations
Cost Of Revenue Direct costs of goods/services sold
Gross Profit Revenue minus cost of revenue
Operating Expense Operating costs (R&D, SG&A, etc.)
Research And Development R&D spending
Selling General And Administration SG&A expenses
Operating Income Profit from core operations
Pretax Income Income before taxes
Tax Provision Income tax expense
Net Income Net income attributable to company
Net Income Common Stockholders Net income for common shareholders
Basic EPS Earnings per share (basic)
Diluted EPS Earnings per share (diluted)
EBIT Earnings before interest and taxes
EBITDA Earnings before interest, taxes, depreciation and amortization

Balance Sheet Fields

Assets

Field Description
Total Assets Sum of all assets
Current Assets Assets convertible to cash within 1 year
Cash And Cash Equivalents Cash on hand
Receivables Money owed to company
Inventory Goods held for sale
Total Non Current Assets Long-term assets
Net PPE Property, plant and equipment (net)
Goodwill Goodwill from acquisitions

Liabilities

Field Description
Total Liabilities Net Minority Interest All liabilities
Current Liabilities Debts due within 1 year
Accounts Payable Supplier payables
Current Debt Short-term borrowings
Long Term Debt Long-term borrowings

Equity

Field Description
Total Equity Gross Minority Interest Total equity
Stockholders Equity Shareholder equity
Common Stock Common shares value
Retained Earnings Accumulated profits

Calculated Metrics

Field Description
Net Debt Total debt minus cash
Total Debt Sum of all debt
Working Capital Current assets minus current liabilities
Invested Capital Equity plus debt

Cash Flow Statement Fields

Operating Activities

Field Description
Operating Cash Flow Cash from operations
Net Income From Continuing Operations Starting net income
Depreciation Amortization Depletion Non-cash depreciation
Stock Based Compensation Stock-based comp expense
Change In Working Capital Working capital changes

Investing Activities

Field Description
Investing Cash Flow Cash used in investing
Capital Expenditure CapEx spending
Purchase Of Investment Investment purchases
Sale Of Investment Investment sales

Financing Activities

Field Description
Financing Cash Flow Cash from financing
Issuance Of Debt New debt raised
Repayment Of Debt Debt repayments
Common Stock Issuance Common stock issued
Cash Dividends Paid Dividend payments

Summary

Field Description
Changes In Cash Total cash change
Free Cash Flow Operating cash minus CapEx

Analyst Estimates

Earnings Estimate

Column Description
avg Average EPS estimate
low Low EPS estimate
high High EPS estimate
yearAgoEps EPS from same period last year
numberOfAnalysts Number of analysts
growth Expected growth rate

Revenue Estimate

Column Description
avg Average revenue estimate
low Low revenue estimate
high High revenue estimate
numberOfAnalysts Number of analysts

Analyst Price Targets

Field Description
current Current stock price
high Highest analyst target
low Lowest analyst target
mean Average target price
median Median target price

Holder Data

Major Holders

Metric Description
insidersPercentHeld Percentage held by insiders
institutionsPercentHeld Percentage held by institutions
institutionsFloatPercentHeld Institutional % of float
institutionsCount Number of institutional holders

Institutional Holders

Column Description
Holder Institution name
pctHeld Percentage of shares held
Shares Number of shares
Value Dollar value of position

Price Data

Column Description
Date Trading date
Open Opening price
High Day high
Low Day low
Close Closing price
Volume Trading volume
Dividends Dividend amount (if any)
Stock Splits Split ratio (if any)

Using This Data in Ratio Formulas

Use these prefixes to reference data:

Prefix Data Source
IS: Income Statement
BS: Balance Sheet
CF: Cash Flow

Example formulas:

  • IS: Net Income / BS: Total Assets (ROA)
  • BS: Total Debt / BS: Stockholders Equity (Debt to Equity)
  • CF: Free Cash Flow / IS: Net Income (FCF Conversion)

9. Color Reference

Syntax Highlighting Color Palette

Operator Colors

ORANGE (#FF9800) - Arithmetic Operators
  + (addition)
  - (subtraction)
  * (multiplication)
  / (division)

Bracket Colors

YELLOW (#FFD700) - Grouping Brackets
  ( (open parenthesis)
  ) (close parenthesis)

Financial Item Colors

Income Statement Items

GREEN (#81C784) - Income Statement Fields
  IS: Revenue
  IS: Net Income
  IS: Operating Income
  IS: EBITDA
  ... (any field prefixed with "IS:")

Balance Sheet Items

LIGHT BLUE (#81D4FA) - Balance Sheet Fields
  BS: Total Assets
  BS: Total Equity
  BS: Total Liabilities
  BS: Cash
  ... (any field prefixed with "BS:")

Price/Market Data

PURPLE (#CE93D8) - Price & Market Data
  P: Closing Price
  P: Opening Price
  P: Volume
  ... (any field prefixed with "P:")

Function Colors

YELLOW-ORANGE (#FFC107) - Advanced Functions
  AVERAGE
  SUM
  MAX
  MIN
  MEDIAN
  STDEV

Number Colors

LIGHT BLUE (#90CAF9) - Numeric Literals
  100
  1.5
  0.25

Error Colors

RED (#F44336) - Invalid Tokens/Errors
  - Misspelled field names
  - Unknown prefixes
  - Unrecognized tokens
  - Typos

  Visual indicators:
  - Red text color
  - Wavy red underline

Example Formulas with Color Coding

Gross Margin

(IS: Revenue - IS: Cost of Revenue) / IS: Revenue

Colors:

  • (, ) = Yellow
  • IS: Revenue = Green (appears twice)
  • IS: Cost of Revenue = Green
  • -, / = Orange

Current Ratio

BS: Current Assets / BS: Current Liabilities

Colors:

  • BS: Current Assets = Light Blue
  • BS: Current Liabilities = Light Blue
  • / = Orange

P/E Ratio

P: Closing Price / IS: Earnings Per Share

Colors:

  • P: Closing Price = Purple
  • IS: Earnings Per Share = Green
  • / = Orange

Error Example (Typo)

IS: Reveneu / BS: Totl Assets

Colors:

  • IS: = Green (valid prefix)
  • Reveneu = Red + wavy underline (invalid)
  • / = Orange
  • BS: = Light Blue (valid prefix)
  • Totl Assets = Red + wavy underline (invalid)

Dark Theme Background Colors

Dialog Background

  • Main: #121212 (Very Dark Gray)
  • Input Fields: #1E1E1E (Dark Gray)
  • Borders: #2C2C2C (Medium Dark Gray)

Text Colors

  • Primary Text: #E0E0E0 (Light Gray)
  • Secondary Text: #B0B0B0 (Medium Gray)

Accent Colors

  • Primary Accent: #29B6F6 (Light Blue)
  • Success: #4CAF50 (Green)
  • Danger: #E57373 (Red)
  • Warning: #FFA726 (Orange)

10. Data Cleanup System

Overview

FinForge includes an automatic data cleanup system that manages parquet file storage when tickers are removed or changed. This prevents the system from accumulating unused data while providing a safety window to recover accidentally deleted tickers.

How It Works

Delayed Deletion (3-Day Grace Period)

When you remove or change a ticker in the UI, the system does NOT immediately delete the data. Instead:

  1. The ticker is added to a pending deletions list (data/pending_deletions.json)
  2. A deletion date is set for 3 days in the future
  3. The actual data deletion occurs on the next app launch after the 3-day period

Automatic Cleanup on Startup

Every time you launch FinForge:

  1. The system checks pending_deletions.json for any tickers past their deletion date
  2. For each ticker past its 3-day grace period, all associated data is permanently deleted
  3. The pending deletions list is updated

Recovery Window

If you accidentally remove a ticker, you have 3 days to re-add it:

  • Simply add the ticker again using the launcher
  • The pending deletion will be automatically cancelled
  • Your existing data will be preserved

What Gets Deleted

When a ticker’s data is permanently deleted, the following files are affected:

Data Type File Location Action
Price History data/prices/{TICKER}.parquet File deleted
Metadata data/metadata/{TICKER}.json File deleted
Income Statement data/fundamentals/income_statement/{TICKER}.parquet File deleted
Balance Sheet data/fundamentals/balance_sheet/{TICKER}.parquet File deleted
Cash Flow data/fundamentals/cash_flow/{TICKER}.parquet File deleted
Recommendations data/fundamentals/recommendations/{TICKER}.parquet File deleted
Major Holders data/holders/major_holders/{TICKER}.parquet File deleted
Institutional Holders data/holders/institutional_holders/{TICKER}.parquet File deleted
Mutual Fund Holders data/holders/mutualfund_holders/{TICKER}.parquet File deleted

Actions That Trigger Deletion Scheduling

Action Result
Remove ticker (delete button) Ticker scheduled for deletion in 3 days
Edit ticker to new symbol Old ticker scheduled for deletion in 3 days
Clear all tickers Each ticker scheduled for deletion in 3 days

Actions That Cancel Scheduled Deletions

Action Result
Add a ticker that was pending deletion Deletion cancelled, data preserved

Pending Deletions File

The pending deletions are tracked in data/pending_deletions.json:

{
  "TICKER1": {
    "scheduled_date": "2025-12-06T21:28:50.896922",
    "deletion_date": "2025-12-09T21:28:50.896910"
  }
}
  • scheduled_date: When the ticker was removed from the UI
  • deletion_date: When the data will be permanently deleted

11. Troubleshooting

Ticker Management Issues

“Invalid Ticker” Error

Cause: Ticker contains numbers or is too long Solution: Use only letters, 1-5 characters

“Duplicate Ticker” Message

Cause: Ticker already exists in your list Solution: Check your list, ticker is already there

Data Not Fetching

Cause: Network issue or invalid ticker symbol Solution:

  1. Check your internet connection
  2. Verify the ticker exists on Yahoo Finance
  3. Check the terminal for error messages

Ticker Shows No Data

Cause: Yahoo Finance doesn’t have data for this ticker Solution: Some tickers (especially foreign or OTC) have limited data

Import Issues

No Data Appears

Possible Causes:

  1. Tickers not in Row 4
  2. Data not fetched yet
  3. Column A doesn’t say “INDEX”

Solutions:

  1. Verify tickers are in Row 4, starting from column B
  2. Run the fetch script first
  3. Ensure column A, Row 4 contains “INDEX”

“Cannot find data” Error

Cause: Parquet file doesn’t exist for the ticker Solution: Run the fetch script to download data

Import Takes Too Long

Cause: Many tickers or slow disk access Solution:

  • Import fewer tickers at once
  • Close other Excel workbooks
  • Wait for the process to complete

Ratio Issues

Red Error Highlighting

Cause: Invalid field name Solution: Check spelling, use the field selector dropdown

“Field not found” Error

Cause: Field doesn’t exist in the data Solution: See Available Data Reference for valid field names

Calculation Shows #N/A

Cause:

  • Data missing for the ticker
  • Division by zero

Solution:

  • Verify data exists for the ticker
  • Add logic to handle zero denominators

Ratio Not Appearing in Manager

Cause: Save failed or file permission issue Solution:

  • Check if ratio_config.json is writable
  • Try saving again

Ratio Assignment Issues

“No ratios found”

Solution: Create or load metrics first

“No tickers found in row 4”

Solution: Import tickers in the Statement Lines tab, or type the symbols into Row 4 of the Metrics sheet starting at column B

“Failed to load Parquet data”

Solution: Make sure data/fundamentals/balance_sheet/ and data/fundamentals/income_statement/ contain Parquet files. Run an import from the Statement Lines tab first if needed.

“Duplicate row”

Solution: Two metrics are claiming the same row in Column A. Clear one of the boxes in the Assignments subtab and refresh

Calculation shows “N/A”

Reason: Financial data not found for that ticker/item Check: Ticker spelling and data availability

Calculation shows “DIV/0”

Reason: Denominator is zero Normal: Some ratios can legitimately be undefined

General Tips

  1. Always fetch data first before trying to import or calculate
  2. Check your internet connection if data fetching fails
  3. Verify ticker symbols exist on Yahoo Finance
  4. Enable Excel macros for full functionality
  5. Save your work frequently when working with Excel

12. Ranking Tab

The Ranking tab scores a group of stocks across the metrics you choose and produces a single ranked score for each one. Instead of looking at each ratio on its own, you pick the metrics that matter to you, tell FinForge which direction is “good” (higher or lower), assign each metric a weight, and the app combines everything into one 0-100 score per stock.

Opening the Ranking Tab

  1. Launch the FinForge workspace (see Getting Started)
  2. In the sidebar, expand Models
  3. Click Ranking

The Ranking screen has three main areas:

  • Left panel - choose tickers, choose metrics, and manage presets
  • Scoring cards - one card per selected metric, where you set the weight and curve
  • Ticker cards panel - the results, showing each stock’s points and total score

Quick Start

  1. Choose tickers - in the left panel’s Tickers subtab, select the stocks to rank
  2. Choose metrics - in the Metrics subtab, toggle on the metrics to score
  3. Click Analyze - FinForge computes the latest value of each metric for every selected stock
  4. Read the results - the bottom Ticker cards panel shows each stock’s points and total score

Step 1: Select Tickers

In the left panel, click the Tickers icon (top of the panel).

  • Type in the Search tickers box to filter the list
  • Click a ticker row to select or deselect it
  • Use All to select every imported ticker
  • Use Remove all to clear the selection
  • The selected count is shown at the bottom

Step 2: Select Metrics

Click the Metrics icon (middle of the left panel).

  • Metrics are grouped by folder (the same folders used in the Metrics tab)
  • Use Search metrics to filter
  • Click a metric row to add or remove it
  • Show selected filters the list to only the metrics you have chosen
  • Remove all clears the metric selection

Step 3: Set Weights and Curves

Every selected metric appears as a scoring card on the right. Each card controls how that metric contributes to the final score.

Max pts (Weight)

  • The Max pts box is the metric’s weight
  • A metric can earn at most this many points
  • A bigger Max pts means the metric matters more in the final ranking

Direction

Choose which direction is “better”:

  • Higher - larger values score more points (e.g., ROE, revenue growth)
  • Lower - smaller values score more points (e.g., debt-to-equity)
  • Target - only available for the Bell curve; values near the center score best

Curve Type

The curve determines how a raw value is converted into points:

Curve What it does Parameters
Percentile Ranks each stock against the others in your selection; outlier-robust None (automatic)
Bell Full points at a center value, falling off to the sides Center, Steepness
S-Curve Smooth transition from low to high points around a midpoint Midpoint, Slope
Linear Straight-line scoring between a low and high anchor Low anchor, High anchor
Steps Score is set by which bucket (bin) the value falls into Thresholds, Points per bin
Custom Draw your own curve by adding points Points, Smoothness

Curve Parameters and the Mini-Chart

  • Each card shows a small chart of the curve with one dot per selected stock
  • Yellow handles on the curve can be dragged to reshape it; you can also type values into the parameter boxes (blank = automatic)
  • When a parameter is left blank, FinForge derives it from your selected stocks (e.g., median, range)

Per-curve controls:

  • Percentile - no parameters; fully automatic
  • Bell - drag the center handle to move the peak and the width handle to change steepness
  • S-Curve - drag the midpoint and slope handles
  • Linear - drag the low and high anchor handles
  • Steps - drag a threshold handle sideways to move a boundary, or drag a score handle up/down; click empty chart space to insert a new threshold; edit the Thresholds / Points columns below the chart
  • Custom - click empty chart space to add a point, drag a point to move it, right-click a point to delete it; the Smoothness slider blends straight lines (0) with smooth curves (1); edit points in the list below the chart

Step 4: Run the Analysis

Click Analyze in the toolbar to compute (or refresh) the ranking. FinForge takes the latest available value of each metric for each selected stock, converts each value to points, and combines them into a 0-100 score.

  • Collapse all - collapses every scoring card to keep the screen tidy
  • The status text (top-right of the toolbar) shows what is happening

How the Scoring Works

  • Each stock’s score = 100 x (points earned) / (maximum points available)
  • Every metric that has data for a stock contributes its points; metrics with missing data are skipped for that stock and the score is re-normalized, so a missing value never unfairly penalizes a stock
  • Scores are always shown on a 0-100 scale

Reading the Results

Ticker Cards Panel (bottom)

After you click Analyze, the panel at the bottom shows each selected stock:

  • One Pts column per metric (the metric’s max points is shown in the header)
  • A trailing Total column showing total points / max points
  • Use the Search tickers box to filter the rows
  • Click a ticker row to focus it - the charts draw a guide line on that stock so you can see where it sits on each curve

Results Table (full screen)

Click Results in the toolbar to open a full-screen, sortable table:

  • Columns: Ticker, one points column per metric, and a Total column
  • Click any column header to sort:
    • Ticker - A-Z, then Z-A
    • Metric - by that metric’s points (stocks with no data always sort last)
    • Total - click repeatedly to cycle: total points down, total points up, score down, score up
  • Click Back to return to the ranking screen

Advanced View (single metric)

Click Advanced to open a full-screen, enlarged view of one metric’s scoring card:

  • Use the metric dropdown (top-left) to switch between metrics; metrics already added show an “added” label
  • Create new metric jumps to the Metrics tab and starts the editor
  • All curve editing works exactly as in the grid (drag handles, add points, pan the chart)
  • Click Back to return to the ranking grid

Saving and Loading Presets

The left panel’s Presets subtab lets you save and restore your ranking configuration (tickers + metrics + curves + weights):

  • Name - type a name for the preset
  • Save - save the current configuration under that name
  • Load - pick a preset from the dropdown to restore it
  • New - clear the current configuration to start fresh
  • Delete - remove the currently loaded preset

Tips

  1. Pick metrics that fit your strategy - a mix of profitability, growth, and valuation metrics usually ranks better than several similar ones
  2. Use weights deliberately - raise Max pts on the metrics that matter most to you
  3. Watch the direction - make sure “Higher” vs “Lower” matches what good looks like for each metric
  4. Missing data is handled - stocks without a metric’s data are scored on the remaining metrics, so a stock is not penalized for missing a single value
  5. Save good setups as presets - you can quickly re-run a ranking you like on new data

Support

For additional help:

  • Check the Guides folder for more documentation
  • Review the Developer guides for technical details
  • Ensure all prerequisites are installed correctly

Document Version: 1.0 Last Updated: December 2025 Data Source: Yahoo Finance via yfinance library