ferro-ta/examples/quickstart.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# ferro-ta Quick Start\n",
    "\n",
    "This notebook demonstrates the core ferro-ta API.\n",
    "\n",
    "Install:\n",
    "```bash\n",
    "pip install ferro-ta\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "from ferro_ta import BBANDS, EMA, MACD, RSI, SMA\n",
    "\n",
    "# Synthetic OHLCV data\n",
    "np.random.seed(42)\n",
    "n = 200\n",
    "close = np.cumprod(1 + np.random.randn(n) * 0.01) * 100\n",
    "high = close * (1 + np.abs(np.random.randn(n)) * 0.005)\n",
    "low = close * (1 - np.abs(np.random.randn(n)) * 0.005)\n",
    "volume = np.random.randint(1_000, 10_000, n).astype(float)\n",
    "\n",
    "print(f\"Generated {n} bars\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Moving Averages"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sma_20 = SMA(close, timeperiod=20)\n",
    "ema_20 = EMA(close, timeperiod=20)\n",
    "\n",
    "print(\"SMA(20):\", sma_20[-5:])\n",
    "print(\"EMA(20):\", ema_20[-5:])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## RSI"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rsi = RSI(close, timeperiod=14)\n",
    "print(\"RSI(14):\", rsi[-5:])\n",
    "print(f\"RSI range: [{np.nanmin(rsi):.2f}, {np.nanmax(rsi):.2f}]\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## MACD"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "macd_line, signal, hist = MACD(close, fastperiod=12, slowperiod=26, signalperiod=9)\n",
    "print(\"MACD line:  \", macd_line[-5:])\n",
    "print(\"Signal:     \", signal[-5:])\n",
    "print(\"Histogram:  \", hist[-5:])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Bollinger Bands"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "upper, middle, lower = BBANDS(close, timeperiod=20, nbdevup=2.0, nbdevdn=2.0)\n",
    "print(\"Upper band: \", upper[-5:])\n",
    "print(\"Middle band:\", middle[-5:])\n",
    "print(\"Lower band: \", lower[-5:])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Batch API — multiple symbols at once"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ferro_ta.batch import batch_rsi, batch_sma\n",
    "\n",
    "# Simulate 5 symbols\n",
    "data = np.random.default_rng(0).random((200, 5)) * 100 + 50\n",
    "sma_result = batch_sma(data, timeperiod=20)\n",
    "rsi_result = batch_rsi(data, timeperiod=14)\n",
    "\n",
    "print(\"Batch SMA shape:\", sma_result.shape)  # (200, 5)\n",
    "print(\"Batch RSI shape:\", rsi_result.shape)  # (200, 5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Pipeline API — compose multiple indicators"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ferro_ta.pipeline import Pipeline\n",
    "\n",
    "pipe = (\n",
    "    Pipeline()\n",
    "    .add(\"sma_20\", SMA, timeperiod=20)\n",
    "    .add(\"ema_20\", EMA, timeperiod=20)\n",
    "    .add(\"rsi_14\", RSI, timeperiod=14)\n",
    "    .add(\n",
    "        \"bb\",\n",
    "        BBANDS,\n",
    "        output_keys=[\"bb_upper\", \"bb_mid\", \"bb_lower\"],\n",
    "        timeperiod=20,\n",
    "        nbdevup=2.0,\n",
    "        nbdevdn=2.0,\n",
    "    )\n",
    ")\n",
    "\n",
    "results = pipe.run(close)\n",
    "print(\"Pipeline outputs:\", list(results.keys()))\n",
    "print(\"SMA last 3:\", results[\"sma_20\"][-3:])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Pandas Integration"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    import pandas as pd\n",
    "\n",
    "    s = pd.Series(close, name=\"close\")\n",
    "    sma_pd = SMA(s, timeperiod=20)\n",
    "    print(\"Result type:\", type(sma_pd))  # pandas.Series\n",
    "    print(\"Index preserved:\", list(sma_pd.index[:3]))\n",
    "except ImportError:\n",
    "    print(\"pandas not installed\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Error Handling"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ferro_ta import FerroTAValueError\n",
    "from ferro_ta.exceptions import check_timeperiod\n",
    "\n",
    "try:\n",
    "    check_timeperiod(0)\n",
    "except FerroTAValueError as e:\n",
    "    print(\"Caught:\", e)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.11.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}