Skip to main content

Jupyter Setup Guide

· 2 min read
Max Kaido
Max Kaido
Architect

This guide explains how to use Jupyter notebooks within the TON Arcana monorepo, specifically for the Mercury TA service.

Directory Structure​

apps/mercury-ta/
├── notebooks/           # Jupyter notebooks directory
│   ├── examples/       # Example notebooks
│   ├── research/       # Research and analysis notebooks
│   └── production/     # Production-ready notebooks
├── src/                # Main source code
└── tests/              # Tests

Setup​

  1. Install Python dependencies:
cd apps/mercury-ta
pnpm install
pip install jupyter ipykernel notebook pandas numpy matplotlib seaborn
python -m ipykernel install --user --name mercury-ta
  1. Configure VS Code:
  • Install required extensions:
    • Jupyter (ms-toolsai.jupyter)
    • Python (ms-python.python)
    • Jupyter Keymap (ms-toolsai.jupyter-keymap)
    • Jupyter Renderers (ms-toolsai.jupyter-renderers)
  1. Start working:
cd apps/mercury-ta
code notebooks/examples/getting_started.ipynb

Best Practices​

  1. Directory Organization

    • Keep notebooks in appropriate subdirectories:
      • examples/: Tutorial and example notebooks
      • research/: Analysis and research notebooks
      • production/: Production-ready notebooks

  2. Code Structure

    • Use relative imports from the project
    • Import project modules using: 
      import sys
      from pathlib import Path
      sys.path.append(str(Path.cwd().parent))
      from src.your_module import your_function

  3. Environment

    • Always use the project's virtual environment
    • Document dependencies in requirements.txt
    • Keep notebooks clean by clearing outputs before committing

  4. Version Control

    • Clear cell outputs before committing
    • Use .gitignore for .ipynb_checkpoints/
    • Add meaningful commit messages

  5. Documentation

    • Start notebooks with a markdown cell describing purpose
    • Document data sources and preprocessing steps
    • Include example outputs and visualizations

Keyboard Shortcuts​

  • Shift+Enter: Run cell and move to next
  • Ctrl+Enter: Run cell and stay
  • Alt+Enter: Run cell and insert below
  • Ctrl+Shift+P: Command palette
    • "Jupyter: Create New Blank Notebook"
    • "Jupyter: Change Kernel"

Integration with Mercury TA​

Notebooks can access all Mercury TA functionality:

from src.services.technical_analysis import TechnicalAnalysisService
from src.services.market_data import MarketDataService

# Initialize services
ta_service = TechnicalAnalysisService()
market_data = MarketDataService()

# Use in analysis
data = market_data.get_historical_data('BTCUSDT', '1d')
analysis = ta_service.analyze(data)

Example Notebooks​

  1. examples/getting_started.ipynb: Basic setup and usage
  2. examples/technical_analysis.ipynb: TA indicators and strategies
  3. research/market_analysis.ipynb: Market research templates