Metadata-Version: 2.4
Name: the-marketlab-project
Version: 0.1.8
Summary: Python tool to download data of financial market such as price, candales, volume from BINANCE and computing indicators. 
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: numpy<3,>=1.26.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: scipy<2,>=1.11.0
Requires-Dist: websocket-client>=1.8.0

# Market Lab

Market Lab is an interactive Python application for manipulating Binance crypto-market data. It stores downloaded OHLCV data in SQLite, calculates various technical indicators, marks events such as a cross between two series, plots series, and produces simple quantile-based statistics vizualised by a heatmap or a simple graph. It is intended for research and experimentation; it does not place orders or provide trading advice.

## What it does

- Creates a SQLite database for a Binance `USDT` market and timeframe.
- Downloads historical candles from Binance's public REST API and updates an existing database.
- Calculates built-in or user-defined indicators and stores them as columns in the SQLite table `candles`.
- Calculates events and stores their status values as columns in SQLite table `status`.
- Plots one or more series, with positive and negative event markers when selected.
- Produces one- and two-variable quantile statistics (classic two dimensional graph or heatmap).

The built-in indicator catalogue includes moving averages, VWEMA, correlation, ATR, relative changes, returns, RSI, Bollinger bands, Savitzky-Golay filtering, and other formulas. The event catalogue includes crossings, extrema, over/under comparisons, and peak detection (full list [here](indicators_and_event_list.md)).

## Requirements

- Python 3.11 or over
- Internet access to Binance for downloads and updates
- A desktop environment capable of displaying Matplotlib windows

Runtime dependencies are declared in `pyproject.toml`: `matplotlib`, `numpy`, `questionary`, `requests`, `rich`, `scipy`, and `websocket-client`.

## Install and run

You can install Market Lab directly with pip:

```bash
python -m pip install the-marketlab-project
```

Then open a Python terminal and run:

```python
from market_lab import main
main()
```

Or clone the github repo:

```bash
https://github.com/Cla1tra2algo/Market-Lab.git
````

Then lunch this file:

````run_marketlab.py```

This is the supported way to launch the packaged application after installation.

At launch, choose **Create a database** or **Open a database**. When creating one, enter a base symbol such as `BTC` (Market Lab appends `USDT`) and choose a supported Binance timeframe. Then use the main menu:

1. **Download Data** — retrieve all available history or a selected date range.
2. **Calculate Indicators** — choose a formula, its input columns, arguments, and window.
3. **Calculate Events** — choose a rule and the columns it should inspect.
4. **Plot** or **Calculate Statistics** — explore saved data.
5. **Update Data** — download newer candles and attempt to extend saved calculations.

Download data before calculating an indicator or event. A window must contain no more candles than are available.

Download data before calculating an indicator or event. A window must contain no more candles than are available.

## Data model

Each database has these main tables:

| Table | Purpose |
| --- | --- |
| `candles` | Binance OHLCV fields plus calculated indicator columns, keyed by `open_time`. |
| `status` | Event-status columns, keyed by `open_time`. Positive and negative values are used by plots and statistics. |
| `indicators_metadata` | Formula name, parameters, window, arguments, and a calculation hash for each indicator. |
| `events_metadata` | Equivalent metadata for each event. |
| `database_metadata` | Symbol, timeframe, and registered custom-module information. |

The downloaded candle fields on BINANCE are `open_time`, `open`, `high`, `low`, `close`, `volume`, `close_time`, `quote_asset_vol`, `number_of_trades`, `taker_buy_base_asset_volume`, and `taker_buy_quote_asset_volume`.

Indicator output begins at the final candle of its first window; earlier rows are left empty. Calculating a column with the same name will ask you to replace the existing column or rename the indicator you are triying to calculate, so use clear, unique names when preserving experiments matters.

## Custom indicators and events

Market Lab can import Python modules that define `indicator_dict` and/or `event_dict`. Custom Python is executed during import, so only load code you have reviewed and trust.

Use **Settings → Manage Custom Indicators and Events → Create custom_indicators.py** to generate a starter module, edit it, then use **Register custom module** to validate, register, and load it. The complete, code-aligned extension contract and working examples are in [How to create your own indicators and events](how_to_create_your_own_indicators_and_events.md).

## Project layout

| File | Role |
| --- | --- |
| `run_marketlab.py` | Recommended local launcher for opening the app. |
| `desktop.py` | Interactive terminal user interface and main application entry point. |
| `commands.py` | Menu workflows for download, calculations, plotting, statistics, and custom-module management. |
| `database.py` | SQLite schema, metadata, and data-access helpers. |
| `data_extraction_service.py` | Binance candle downloader. |
| `math_formula.py` | Built-in indicator functions and their registry. |
| `event.py` | Built-in event functions and their registry. |
| `indicators_service.py` / `events_service.py` | Rolling-window calculation engines. |
| `custom_indicators.py` | Example custom module. |
| `math_formula.py`| Registery of native indicators formulas. |
| `event.py`| Registery of native event formulas.|
| `validations_of_user_entry.py`|Validations of user inputs.|
|`display.py`| Manage display for centralised display control.|
|`_service.py` files | Manage back ground labour of MarketLab for the feature indicated.|






## Notes and limitations

- Because the market data come from BINANCE, availability, symbols, and historical coverage are controlled by Binance.
- The application is interactive rather than a stable programmatic API.
- SQLite files and generated custom modules are created next to the project files. Back up databases before replacing columns or registering untrusted changes.
- This project is for analysis, not a recommendation to buy or sell any asset.

## Verification

The repository includes a lightweight custom-module smoke test:

```bash
python test_smoke.py
```
