lecture/Install TQuant Lab.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "37436890",
   "metadata": {},
   "source": [
    "# TQuant Lab 安裝教學\n",
    "## 使用的套件以及環境\n",
    "\n",
    "* Main package：Zipline\n",
    "* 支援的 Python 版本：Python 3.8~3.11（建議使用Python 3.11）\n",
    "* 支援的作業系統：Microsoft Windows OS or macOS\n",
    "* 建議的 Pandas 版本：1.5.3 或 2.0.0（> 2.0.0 可能會有未預期的錯誤）\n",
    "* 建議的 Numpy 版本：1.23.5（> 1.23.5 可能會有未預期的錯誤）\n",
    "\n",
    "# 以下將提供A、B、C 三種安裝zipline-tej的方式（**擇一即可，但推薦使用方法 A 或 B**）\n",
    "\n",
    "---\n",
    "\n",
    "## A. 透過docker 安裝 zipline-tej（**推薦**）\n",
    "\n",
    "#### 先決條件\n",
    "\n",
    "* 已安裝好docker-desktop\n",
    "\n",
    "#### 啟動終端機(CMD)\n",
    "\n",
    "#### (方法一) 透過下載Dockerfile\n",
    "\n",
    "[下載tquant_jupyter](https://github.com/tejtw/zipline-tej/blob/main/dockerfile/tquant_jupyter) (Jupyter使用)\n",
    "\n",
    "[下載tquant_bash](https://github.com/tejtw/zipline-tej/blob/main/dockerfile/tquant_bash) (排程使用)\n",
    "\n",
    "```\n",
    "$ # 於終端機透過 cd 到已下載 dockerfile的目錄之下\n",
    "$ docker build -f tquant_jupyter . -t \"tquant:latest\"\n",
    "```\n",
    "#### (方法二) 直接從docker hub下載（**推薦**）\n",
    "\n",
    "```\n",
    "# 於終端機輸入以下指令\n",
    "$ docker pull tej87681088/tquant:latest\n",
    "```\n",
    "### 2 建置一個volume以傳輸雙方資料\n",
    "\n",
    "```\n",
    "# 於終端機輸入以下指令\n",
    "$ docker volume create data\n",
    "```\n",
    "\n",
    "### 3. 透過image建置container\n",
    "\n",
    "```\n",
    "# 於終端機輸入以下指令\n",
    "(若透過方法一下載)\n",
    "$ docker run -v data:/app -p 8888:8888 --name tquant tquant\n",
    "(若透過方法二下載)\n",
    "$ docker run -v data:/app -p 8888:8888 --name tquant tej87681088/tquant\n",
    "```\n",
    "\n",
    "* 此命令將會啟動一個container並將container內部的 8888 埠映射到本機的 8888 埠，並且將可以透過volume傳輸資料\n",
    "\n",
    "* (以筆者Windows10的電腦為例：volume的位置在 \\\\\\wsl$\\docker-desktop-data\\data\\docker\\volumes\\data\\\\_data)\n",
    "* (若希望不要保留container，可加入 --rm)\n",
    "\n",
    "### 4. 開始使用jupyter\n",
    "\n",
    "* 此時應該會在終端機看到一串網址類似\n",
    "\n",
    "```\n",
    "$ http://127.0.0.1:8888/tree?token=XXXXXXXXXXXXXXXX\n",
    "```\n",
    "\n",
    "* 將其複製並貼上至瀏覽器便可開始使用\n",
    "\n",
    "### Appendix\n",
    "\n",
    "* 若想使用之前已創建過的但關閉的container操作，可透過以下指令取得網址\n",
    "\n",
    "```\n",
    "# 找尋container ID\n",
    "$ docker ps -a \n",
    "# 啟動 指定container\n",
    "$ docker start <CONTAINER_ID>\n",
    "# 顯示 container 內部終端機最近印出的提示\n",
    "$ docker logs --tail 3 <CONTAINER_ID>\n",
    "```\n",
    "\n",
    "---\n",
    "\n",
    "## B. 透過`Anaconda Prompt`一鍵安裝 zipline-tej（**推薦**）\n",
    "\n",
    "* 首先，需要下載以下套件文件。\n",
    "\n",
    "    1. Windows [(zipline-tej.yml)](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/tejtw/zipline-tej/blob/main/zipline-tej.yml)\n",
    "\n",
    "    2. Mac [(zipline-tej_mac.yml)](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/tejtw/zipline-tej/blob/main/zipline-tej_mac.yml)\n",
    "\n",
    "\n",
    "* 接著，在 Anaconda 的命令提示字元中，創建一個虛擬環境並安裝相應版本的依賴套件。我們強烈推薦使用虛擬環境，以保持每個項目的獨立性。[(原因說明)](https://csguide.cs.princeton.edu/software/virtualenv#definition)\n",
    "\n",
    "```\n",
    "    Window 使用者\n",
    "\n",
    "    # 將下載好的 zipline-tej.yml檔案放在以下路徑中\n",
    "    $ cd <C:\\Users\\username\\Downloads>\n",
    "\n",
    "    # 透過yml檔安裝所需套件並創建虛擬環境\n",
    "    $ conda env create -f zipline-tej.yml\n",
    "\n",
    "    # 開啟虛擬環境\n",
    "    $ conda activate zipline-tej\n",
    "\n",
    "    Mac 使用者\n",
    "    \n",
    "    # 將下載好的 zipline-tej.yml檔案放在以下路徑中\n",
    "    $ cd \\Users\\username\\Downloads\n",
    "\n",
    "    # 創建虛擬環境\n",
    "    $ conda env create -f zipline-tej_mac.yml\n",
    "\n",
    "    # 開啟虛擬環境\n",
    "    $ conda activate zipline-tej\n",
    "```\n",
    "\n",
    "* 至此，便可開始使用zipline-tej。\n",
    "\n",
    "---\n",
    "## C. 直接透過pip install 安裝 zipline-tej（**使用此方式安裝可能會有未預期的錯誤，可能會需自行 debug**）\n",
    "\n",
    "* **於本機端安裝 zipline-tej**\n",
    "\n",
    "    * 在開始安裝之前，我們建議使用 [Anaconda](https://www.anaconda.com/data-science-platform) 作為開發環境。\n",
    "\n",
    "    * 為避免環境的套件衝突，創建虛擬環境是相當重要的。因此我們建議先建立虛擬環境後，逐一安裝所需的套件。\n",
    "\n",
    "    * 以下我們建議兩種建立虛擬環境的方式(擇一即可)\n",
    "\n",
    "```\n",
    "    (方法一)\n",
    "    # 透過Anaconda指令\n",
    "    # 於Anaconda Prompt\n",
    "    # create virtual env\n",
    "    $ conda create -n <env_name> python=3.11\n",
    "    \n",
    "    # activate virtual env\n",
    "    $ conda activate <env_name>\n",
    "\n",
    "    # download packages\n",
    "    $ pip install zipline-tej\n",
    "    $ pip install notebook\n",
    "    $ conda install -c conda-forge nb_conda_kernels\n",
    "```\n",
    "\n",
    "```\n",
    "    (方法二)\n",
    "    # 透過Python原生指令\n",
    "    # 於CMD\n",
    "    # create virtual env\n",
    "    $ python -m venv venv\n",
    "\n",
    "    # activate virtual env\n",
    "    $ venv\\Scripts\\activate.bat\n",
    "    # download packages\n",
    "    $ pip install zipline-tej\n",
    "    $ pip install notebook\n",
    "```\n",
    "\n",
    "* **於 google colab 使用 zipline-tej**\n",
    "\n",
    "    * 若您使用 google colab，可以直接執行以下程式碼，下載 `zipline-tej`。\n",
    "\n",
    "    <br>\n",
    "\n",
    "    ```\n",
    "      !pip install zipline-tej\n",
    "    ```\n",
    "\n",
    "    <br>\n",
    "\n",
    "    * 並同時將pandas版本改為1.5.3，降低遇到版本衝突的可能性。\n",
    "\n",
    "    <br>\n",
    "\n",
    "    ```\n",
    "      !pip install  pandas==1.5.3\n",
    "    ```\n",
    "    <br>\n",
    "    \n",
    "    * 若有使用Pyfolio，可以一併執行下列指令避免出現 Warning。\n",
    "\n",
    "    <br>\n",
    "\n",
    "    ```\n",
    "      import matplotlib\n",
    "      !wget -O MicrosoftJhengHei.ttf https://drive.google.com/uc?id=1nMlvxPOPUGkHxYD5kuP8Ur37EmKlZAW_&export=download\n",
    "      !wget -O ArialUnicodeMS.ttf https://drive.google.com/uc?id=1Y4O8Flv7lfrzHqOE8dkFTSctyYOpAJ0N&export=download\n",
    "\n",
    "      matplotlib.font_manager.fontManager.addfont('MicrosoftJhengHei.ttf')\n",
    "      matplotlib.rc('font', family='sans-serif')\n",
    "\n",
    "      matplotlib.font_manager.fontManager.addfont('ArialUnicodeMS.ttf')\n",
    "      matplotlib.rc('font', family='sans-serif')\n",
    "    ```\n",
    "\n",
    "## 檢查 zipline-tej 版本\n",
    "\n",
    "* 若已安裝好zipline-tej，我們可透過以下指令顯示當前zipline-tej的版本。\n",
    "\n",
    "```\n",
    "  !pip show zipline-tej\n",
    "```\n",
    "\n",
    "* 為確保當前版本為最新，可以透過以下指令以更新zipline-tej。\n",
    "\n",
    "```\n",
    "  !pip install --upgrade zipline-tej\n",
    "```\n",
    "\n",
    "* [zipline-tej當前版本](https://pypi.org/project/zipline-tej/)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5ce2c4e6",
   "metadata": {},
   "source": [
    "## 其他資訊\n",
    "\n",
    "* [TQuant Lab 官方網站](https://tquant.tejwin.com/)\n",
    "* [TQuant Lab Github](https://github.com/tejtw/TQuant-Lab)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.19"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}