Skip to content

About

Experimental financial ephemeris and XGBoost machine learning research pipeline combining Swiss Ephemeris (pyswisseph) natal/transit planetary calculations with Dask parallelization, automated Jupyter nbconvert workflows, pre-computed 9-ticker models, and a Flask REST API.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

134 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

๐Ÿช pyAstroTrader โ€” Financial Ephemeris & XGBoost Research Pipeline

Quantitative research framework investigating correlations between astronomical ephemeris geometry (Swiss Ephemeris natal charts, planetary longitudes, retrograde cycles, and harmonic transits) and equity price action using Dask parallelization and XGBoost gradient-boosted trees.

Overview โ€ข Capabilities โ€ข Methodology โ€ข Architecture โ€ข Structure โ€ข Setup & Usage โ€ข API

Python 3.8+ Swiss Ephemeris XGBoost and Dask MIT License

Flask API Yahoo Finance and Alpha Vantage Pipeline Automation Pre-Computed Assets

Warning

Educational & Experimental Research Only: pyAstroTrader investigates planetary ephemeris correlations with market series as an academic machine learning exercise. Do NOT use model outputs for live trading or investment decisions.


๐Ÿ“Š Overview

Financial Astrology Historical Quote

pyAstroTrader combines high-precision astronomical calculations via Swiss Ephemeris (pyswisseph) with XGBoost regression/classification pipelines executed through automated Jupyter notebooks and a Flask REST server. Given an equity or ETF ticker and its historical listing ("natal") timestamp, the system computes daily geocentric/sidereal planetary longitudes, pairwise angular separations, and natal-to-transit aspects, then trains boosted tree models to predict directional price-change or swing-trade targets across upcoming trading days.

Pre-Computed Asset Artifacts Included

The notebooks/input/ and notebooks/output/ directories contain ready-to-inspect datasets, trained .model files, ranked feature-importance logs, and 30-calendar-day forecast workbooks for 9 US equities and ETFs:

Ticker Daily Bars (notebooks/input/) Trained Model (notebooks/output/) Recorded Training MSE (*.score.price.change.txt) Ranked Features Top Feature
AAPL 100 rows (2025-08-15 โ†’ 2026-01-07) AAPL_price_change.model 3.64e-07 40 ASTRO_SUN_POSITION
DIA 100 rows (2025-08-15 โ†’ 2026-01-07) DIA_price_change.model 1.55e-07 40 ASTRO_SUN_POSITION
GLD 100 rows (2025-11-07 โ†’ 2026-04-02) GLD_price_change.model 2.49e-07 45 ASTRO_SUN_POSITION
GOOGL 100 rows (2025-11-07 โ†’ 2026-04-02) GOOGL_price_change.model 4.98e-07 45 ASTRO_SUN_POSITION
MSFT 100 rows (2025-08-15 โ†’ 2026-01-07) MSFT_price_change.model 8.94e-07 39 ASTRO_SUN_POSITION
NVDA 100 rows (2025-08-15 โ†’ 2026-01-07) NVDA_price_change.model 8.93e-07 41 ASTRO_SUN_POSITION
QQQ 100 rows (2025-08-15 โ†’ 2026-01-07) QQQ_price_change.model 3.60e-07 41 ASTRO_SUN_POSITION
SLV 100 rows (2025-08-15 โ†’ 2026-01-07) SLV_price_change.model 3.47e-07 40 ASTRO_SUN_POSITION
SPY 100 rows (2025-08-15 โ†’ 2026-01-07) SPY_price_change.model 4.74e-07 41 ASTRO_SUN_POSITION

Note: Brazilian equities (PETR4.SA, VALE3.SA, ITUB4.SA, BBDC4.SA, ABEV3.SA) and ^BVSP also have configured natal timestamps in notebooks/settings.py and assets_to_calculate.txt.


๐Ÿงฉ Core Capabilities and Modules

Component Path Responsibility
Ephemeris Core pyastrotrader/calculate/calculate.py Computes Julian Day UT (swe.julday), ecliptic positions (swe.calc_ut), Placidus house cusps (swe.houses), coordinate flags (truegeo, topo, helio), sidereal mode (FAGAN_BRADLEY), and retrograde flags.
Aspect & Transit Engine pyastrotrader/transits/transits.py Evaluates intra-chart (calculate_aspects) and radix-to-transit (calculate_transits) angular separations across 11 aspects (0ยฐโ€“180ยฐ) within a 4ยฐ orb tolerance.
Celestial Constants pyastrotrader/constants.py Indexes 35 bodies/points (SUN through TRUE_LILITH) and 11 aspect definitions (CONJUNCTION, SEMISEXTILE, SEMISQUARE, SEXTILE, QUINTILE, SQUARE, TRINE, SESQUIQUADRATE, BIQUINTILE, QUINCUNX, OPPOSITION).
Market Data Fetcher pyastrotrader/data_fetcher.py Provides fetch_data_yfinance (20-year history via yfinance), fetch_data_alphavantage (TIME_SERIES_DAILY), and fetch_stock_data(..., source='auto') fallback.
Config & Input Builder pyastrotrader/config.py, pyastrotrader/utils/__init__.py Validates SWISSEPH_PATH and chart JSON schema; builds input payloads using default_config.json and default_parameters.json.
Feature & Label Helpers notebooks/helpers.py, notebooks/settings.py Generates trend/swing/volatility labels, quantized planetary features, iterative XGBoost boosting (get_best_booster), and clamped predictions (predict_score).
Notebook Pipeline notebooks/*.ipynb DownloadData.ipynb โ†’ CreateModel.price.change.ipynb / CreateModel.swing.trade.ipynb โ†’ Predict.price.change.ipynb / Predict.swing.trade.ipynb.
Flask API & Runners astrotrader_server.py, run_astro.ps1, run_notebooks*.sh Automates end-to-end execution via jupyter nbconvert and serves prediction results over HTTP JSON endpoints.

๐Ÿงฎ Analytical and ML Methodology

1. Ephemeris Feature Engineering

For each trading date $t$ (evaluated at 10:00:00-03:00 in generate_charts), CreateModel.price.change.ipynb computes ecliptic longitudes $\theta_i(t) \in [0^\circ, 360^\circ)$ for planets in PLANETS_TO_CALCULATE = [SUN, MOON, VENUS, MERCURY, MARS, JUPITER, SATURN] and quantizes features into $3^\circ$ buckets (computing single-planet ASTRO_{i}_POSITION for non-Saturn bodies and pairwise differences across all pairs):

$$\text{ASTRO}_{i,\text{POS}}(t) = \left\lfloor \frac{\theta_i(t)}{3} \right\rfloor, \qquad \text{ASTRO}_{i,j,\text{DIFF}}(t) = \left\lfloor \frac{\theta_i(t) - \theta_j(t)}{3} \right\rfloor, \qquad \text{ASTRO}_{i,j,\text{ABS}}(t) = \left|\left\lfloor \frac{\theta_i(t) - \theta_j(t)}{3} \right\rfloor\right|$$

When ASPECTS_TO_CALCULATE is populated, binary flags (is_aspected, is_aspected_transiting) test whether $\big||\theta_i - \theta_j| - \alpha_k\big| < 4^\circ$ for aspect angle $\alpha_k \in {0^\circ, 30^\circ, 45^\circ, 60^\circ, 72^\circ, 90^\circ, 120^\circ, 135^\circ, 144^\circ, 150^\circ, 180^\circ}$.

2. Target Variables (notebooks/helpers.py)

  • Daily Price-Change Signal (TARGET_PRICE_CHANGE): $$y_t = \begin{cases} +1 & \text{if } \left(\frac{P_t}{P_{t-1}} - 1\right)\times 100 > 1% \ -1 & \text{if } \left(\frac{P_t}{P_{t-1}} - 1\right)\times 100 < -1% \ 0 & \text{otherwise} \end{cases}$$
  • Swing-Trade Signals (CreateModel.swing.trade.ipynb): Compares backward and forward SWING_TRADE_DURATION = 5 day trends against IntradayVolatility ($\times 3.5$) and detects local 5-bar lows (TARGET_IS_SWING_BOTTOM) or directional moves exceeding STAGNATION_THRESHOLD = 5%.

3. Iterative XGBoost Training (get_best_booster)

helpers.py trains xgb.train (booster='gbtree', objective='reg:squarederror', eta=0.3, max_depth=7, subsample=0.5, num_round=1000) sequentially up to MAX_INTERACTIONS = 50 rounds on random 70/30 splits (xgb_model=booster), retaining the model minimizing full-sample $\text{MSE}$ (stopping early if $\text{MSE} &lt; 10^{-6}$). Predictions in Predict.*.ipynb cover the next DAYS_TO_PREDICT = 30 calendar days (excluding weekends) and clamp outputs to $[-1, 1]$.


๐Ÿ—๏ธ Architecture

flowchart TD
    subgraph Ingestion["Market Data Ingestion"]
        AV["Alpha Vantage API\n(DownloadData.ipynb)"]
        YF["Yahoo Finance\n(pyastrotrader/data_fetcher.py)"]
        IN["notebooks/input/{TICKER}_Daily.csv"]
    end

    subgraph Ephemeris["Swiss Ephemeris Computation"]
        SWE["pyastrotrader/swisseph/*.se1"]
        CALC["pyastrotrader/calculate\n(Natal & Daily Charts)"]
        TRN["pyastrotrader/transits\n(Aspects & Transits)"]
    end

    subgraph Features["Dask Feature Pipeline & Training"]
        FEAT["notebooks/helpers.py\n(3-deg Quantized Positions & Targets)"]
        XGB["XGBoost Booster\n(get_best_booster, up to 50 iterations)"]
        MOD["notebooks/output/{TICKER}_price_change.model\n+ .score + .features + .Analisys.xlsx"]
    end

    subgraph Serving["Forecasting and API Layer"]
        PRED["Predict.price.change.ipynb\n(30-Day Weekday Forecast)"]
        XLSX["notebooks/output/{TICKER}.Predict.Simplified.xlsx"]
        FLASK["astrotrader_server.py\n(Flask REST API on :5000)"]
    end

    AV --> IN
    YF -.-> IN
    IN --> FEAT
    SWE --> CALC --> TRN --> FEAT
    FEAT --> XGB --> MOD
    MOD --> PRED --> XLSX
    XLSX --> FLASK
Loading

๐Ÿ“‚ Repository Structure

pyAstroTrader-master/
โ”œโ”€โ”€ .gitattributes
โ”œโ”€โ”€ .gitignore
โ”œโ”€โ”€ LICENSE                                      # MIT License
โ”œโ”€โ”€ README.md
โ”œโ”€โ”€ requirements.txt                             # Flask, yfinance, XGBoost, pyswisseph, Dask, Jupyter
โ”œโ”€โ”€ assets_to_calculate.txt                      # Batch ticker list (PETR4.SA..ABEV3.SA)
โ”œโ”€โ”€ astrotrader_server.py                        # Flask REST API wrapping run_astro.ps1 & Excel outputs
โ”œโ”€โ”€ run_astro.ps1                                # Windows PowerShell end-to-end notebook runner
โ”œโ”€โ”€ run_all.sh                                   # Batch wrapper running assets_to_calculate.txt
โ”œโ”€โ”€ run_notebooks.sh                             # Linux/macOS single-asset pipeline runner
โ”œโ”€โ”€ run_notebooks_multiple.sh                    # Iterative multi-model runner (PRICE_CHANGE / SWING_TRADE)
โ”œโ”€โ”€ start_notebooks.sh                           # Launches JupyterLab on port 8080
โ”œโ”€โ”€ clean_notebooks.sh                           # Strips outputs from notebooks/*.ipynb
โ”œโ”€โ”€ debug_runner.py                              # Standalone runner for debug_create_model_price_change.py
โ”œโ”€โ”€ test_api.py                                  # Alpha Vantage API connectivity check
โ”œโ”€โ”€ extract_script.py                            # Exports CreateModel.ipynb code cells to Python
โ”œโ”€โ”€ fix_multiprocessing.py                       # Notebook multiprocessing patch utility
โ”œโ”€โ”€ patch_notebook.py                            # Patches DownloadData.ipynb API parameters
โ”œโ”€โ”€ patch_notebook_threads.py                    # Switches Dask scheduler to threads in Predict
โ”œโ”€โ”€ patch_notebook_xls.py                        # Converts .xls output paths to .xlsx in Predict
โ”œโ”€โ”€ docs/
โ”‚   โ””โ”€โ”€ jpmorgan.jpg
โ”œโ”€โ”€ pyastrotrader/
โ”‚   โ”œโ”€โ”€ __init__.py                              # Public API exports
โ”‚   โ”œโ”€โ”€ config.py                                # SWISSEPH_PATH & JSON schema validation
โ”‚   โ”œโ”€โ”€ constants.py                             # Planet & aspect IDs and angle tables
โ”‚   โ”œโ”€โ”€ data_fetcher.py                          # Yahoo Finance + Alpha Vantage fetcher
โ”‚   โ”œโ”€โ”€ calculate/
โ”‚   โ”‚   โ”œโ”€โ”€ __init__.py
โ”‚   โ”‚   โ””โ”€โ”€ calculate.py                         # Swiss Ephemeris chart & house calculation
โ”‚   โ”œโ”€โ”€ transits/
โ”‚   โ”‚   โ”œโ”€โ”€ __init__.py
โ”‚   โ”‚   โ””โ”€โ”€ transits.py                          # Planetary aspects, transits & angular separation
โ”‚   โ”œโ”€โ”€ utils/
โ”‚   โ”‚   โ””โ”€โ”€ __init__.py                          # create_input_json helper
โ”‚   โ”œโ”€โ”€ swisseph/                                # Swiss Ephemeris data files (*.se1, fixstars.cat)
โ”‚   โ””โ”€โ”€ test/                                    # default_config.json, default_parameters.json, sample natal JSON
โ”œโ”€โ”€ notebooks/
โ”‚   โ”œโ”€โ”€ settings.py                              # Natal dates, hyperparameters & environment checks
โ”‚   โ”œโ”€โ”€ helpers.py                               # Indicator, aspect & XGBoost training helpers
โ”‚   โ”œโ”€โ”€ debug_create_model_price_change.py       # Script export of CreateModel.price.change
โ”‚   โ”œโ”€โ”€ DownloadData.ipynb                       # Alpha Vantage daily quote downloader
โ”‚   โ”œโ”€โ”€ CreateModel.price.change.ipynb           # Price-change (+/-1%) XGBoost training notebook
โ”‚   โ”œโ”€โ”€ CreateModel.swing.trade.ipynb            # Swing-trade bottom XGBoost training notebook
โ”‚   โ”œโ”€โ”€ Predict.price.change.ipynb               # 30-day price-change inference notebook
โ”‚   โ”œโ”€โ”€ Predict.swing.trade.ipynb                # 30-day swing-trade inference notebook
โ”‚   โ”œโ”€โ”€ config/                                  # default_config.json, default_parameters.json
โ”‚   โ”œโ”€โ”€ input/                                   # {TICKER}_Daily.csv & .xlsx for 9 assets
โ”‚   โ””โ”€โ”€ output/                                  # Trained .model, .cache, .Analisys.xlsx & .Predict*.xlsx
โ””โ”€โ”€ test/
    โ””โ”€โ”€ test_calculate.py                        # Swiss Ephemeris natal chart & transit smoke test

๐Ÿš€ Installation and Usage

Prerequisites

  • Python 3.8+ (note requirements.txt contains pinned legacy versions such as xgboost==0.90, pandas==0.25.3, and pyswisseph==2.0.0.post2 alongside flask>=3.0.0 and yfinance>=0.2.0; if installing on Python 3.12+, install current compatible wheels for numpy, pandas, dask[dataframe], scikit-learn, xgboost, pyswisseph, openpyxl, plotly, jupyter, flask, flask-cors, and yfinance)
  • Alpha Vantage API Key (required by DownloadData.ipynb and /api/run-prediction; optional when using pyastrotrader/data_fetcher.py directly with yfinance)

1. Clone and Setup Environment

git clone https://github.com/khalid-naami/pyAstroTrader-master.git
cd pyAstroTrader-master

python -m venv .venv
# Windows (PowerShell)
.venv\Scripts\Activate.ps1
# macOS / Linux
source .venv/bin/activate
pip install -r requirements.txt

2. Configure Environment Variables

# Windows (PowerShell)
$Env:ASSET_TO_CALCULATE = "AAPL"
$Env:ALPHAVANTAGE_KEY = "YOUR_ALPHAVANTAGE_API_KEY"
$Env:PYTHONPATH = "$PWD;$PWD\notebooks"
$Env:SWISSEPH_PATH = "$PWD\pyastrotrader\swisseph"
# macOS / Linux
export ASSET_TO_CALCULATE="AAPL"
export ALPHAVANTAGE_KEY="YOUR_ALPHAVANTAGE_API_KEY"
export PYTHONPATH="$PWD:$PWD/notebooks"
export SWISSEPH_PATH="$PWD/pyastrotrader/swisseph"

3. Run the Automated Pipeline

# Windows PowerShell (executes DownloadData -> CreateModel.price.change -> Predict.price.change)
.\run_astro.ps1 -Asset "AAPL" -ApiKey "YOUR_ALPHAVANTAGE_API_KEY"
# Linux / macOS (JupyterLab interactive mode)
./start_notebooks.sh

# Or run Swiss Ephemeris unit smoke test from test/
cd test && python test_calculate.py

4. Fetch Data via Python (yfinance / Alpha Vantage)

from pyastrotrader.data_fetcher import fetch_stock_data

df = fetch_stock_data("AAPL", source="yfinance")
print(df.head())

๐ŸŒ Flask API Endpoints

Start the Flask API server on port 5000:

python astrotrader_server.py
Endpoint Method Behavior
/api/run-prediction POST Accepts JSON {"ticker": "AAPL", "apiKey": "YOUR_KEY"}, runs run_astro.ps1 (10-minute timeout), and returns parsed predictions and model MSE score.
/api/get-results/<ticker> GET Reads notebooks/output/{TICKER}.Predict.Simplified.xlsx and {TICKER}.score.price.change.txt and returns JSON predictions.
/api/available-tickers GET Scans notebooks/output/*.Predict.Simplified.xlsx and lists all tickers with generated forecasts.
/ GET Serves astrotrader_web.html if present in the repository root (note: only the JSON REST endpoints are tracked in the current repository).

๐Ÿ“œ License

Released under the MIT License โ€” see LICENSE for full terms.

About

Experimental financial ephemeris and XGBoost machine learning research pipeline combining Swiss Ephemeris (pyswisseph) natal/transit planetary calculations with Dask parallelization, automated Jupyter nbconvert workflows, pre-computed 9-ticker models, and a Flask REST API.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages