Metadata-Version: 2.4
Name: kamakuraquantlab-hase
Version: 0.10.0
Summary: Kamakura Quant Lab analysis toolkit
Author-email: Kamakura Quant Lab <support@kamakuraquantlab.jp>
License-Expression: Apache-2.0
Project-URL: Homepage, https://kamakuraquantlab.jp
Project-URL: Documentation, https://kamakuraquantlab.jp/support/
Project-URL: Source, https://github.com/kamakuraquantlab/Hase
Project-URL: The data, https://kamakuraquantlab.jp/data/
Keywords: cryptocurrency,market-data,order-book,japan,quantitative-finance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: kamakuraquantlab-komachi>=0.8.0
Requires-Dist: kamakuraquantlab-qate>=0.2
Requires-Dist: pyarrow>=15.0
Requires-Dist: pandas>=2.0
Requires-Dist: numpy
Requires-Dist: matplotlib>=3.8
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# Hase

The **Kamakura Quant Lab** analysis toolkit. Reads the bronze data Komachi
downloads, derives the silver and gold datasets the articles are written on,
and draws it.

Named for the district where the Great Buddha sits. Komachi is where you get
things; Hase is where you go to look at them.

```bash
pip install kamakuraquantlab-hase
hase local       --market COINCHECK:BTC_SPOT
hase derive MarketPrice --market COINCHECK:BTC_SPOT --start 2025-07-01 --end 2025-07-28
hase derive Volatility  --market COINCHECK:BTC_SPOT --start 2025-07-01 --end 2025-07-28
hase derive Spread      --market GMO:BTC_JPY --execution-size 0.002 --start 2026-06-01 --end 2026-06-30 \
                        --params 300 --params 900
hase derive Volatility  --market GMO:BTC_JPY --execution-size 0.002 --start 2026-06-01 --end 2026-06-30 \
                        --params 60:300:120 --params 60:900:300
hase plot-trades --market COINCHECK:BTC_SPOT --date 2025-07-01 --output trades.png
hase plot-book   --market COINCHECK:BTC_SPOT --date 2025-07-01 --output book.png
```

## What it derives

Komachi downloads `bronze/`. Hase turns it into the datasets the articles are
written on, beside it under the same root, in the layout the warehouse uses.

| Dataset | Layer | What it is |
|---|---|---|
| `BookState` | silver | Best bid and ask per snapshot, with mid, spread and the depth resting at the touch |
| `MarketPrice` | silver | What a given trade size would actually pay, by walking the book |
| `Spread` | gold | The spread's moving average on a regular clock, in bps |
| `Volatility` | gold | Realized volatility and the volatility of returns over a window, on a regular clock, in bps |

**Size is in base currency.** `--execution-size 0.002` is 0.002 BTC, and it is
the default because it means the same trade on every venue and on every day.
`--execution-notional 1000000` walks to a cash amount instead, which is a
different question and a different partition: ¥1,000,000 bought 0.0647 BTC in
July 2025 and 0.0796 BTC in September 2026, so a notional is not comparable
with itself over time, and a USDT-quoted book cannot be walked to a yen target
at all.

Deriving costs about a quarter of a second per market-day, so a market-year is
a minute and a half. `MarketPrice` is around an eighth the size of the bronze
it reads.

**Nothing is dropped silently.** `MarketPrice` holds only snapshots with a
real price. A size the visible book cannot fill is left out rather than priced
as a partial fill, and so is a snapshot whose walked spread exceeds 100 bps:
those are collector artefacts from a resync, present in historical bronze. How
many of each a day held is written into the file (`df.attrs["dropped"]` after
`pd.read_parquet`) and printed by `hase derive`, because it is a fact about the
archive worth being able to count.

## Spread and volatility: one grid, two datasets, any parameters

Both are measured on the quote put on a clock: the last bid and ask in each
step, carried through a step with no update (`hase.derive.grid.quote_grid`).
The grid is not stored -- it is a tenth of a second a day from data already on
disk, with nothing to choose but the step -- so each dataset holds only what
its own parameters make. A script that wants the mid on a clock calls
`quote_grid`.

Each is measured either at the top of the book (the default) or on what a size
would actually pay (`--execution-size`, read from `MarketPrice`), and each set
of windows is its own partition, so any number sit side by side:

```
gold/dataset=Spread/exchange=GMO/symbol=BTC_JPY/execution_size=0.002/param_id=g1s_ema300s/date=2026-06-01/data.parquet
gold/dataset=Volatility/exchange=GMO/symbol=BTC_JPY/execution_size=touch/param_id=g1s_h60s_lb300s_ema120s/date=2026-06-01/data.parquet
```

| Dataset | Windows (seconds) | Columns, all bps |
|---|---|---|
| `Spread` | `--span`: the EMA span | `spread_bps_ema` |
| `Volatility` | `--horizon`: the return; `--lookback`: the window it is measured over; `--smooth`: the EMA span | `rv_bps` (root of summed squared one-step log returns over `lookback`), `vol_bps` (standard deviation of `horizon` returns over `lookback`), `vol_bps_ema` |

`--step` is the grid for both. `--params`, repeated, derives several sets from
one read of each day: `SPAN` for Spread, `HORIZON:LOOKBACK:SMOOTH` for
Volatility. Both are in bps, so `vol_bps_ema / spread_bps_ema` -- how far price
moves for what a round trip costs -- needs no conversion; it is not stored,
because it is a choice of which two windows to divide.

The formulas are `spread.measure` and `volatility.measure`, and code that needs
the figures on a grid of its own -- a labeller resampling ticks -- calls those
rather than writing them again.

Each day is read with the eight hours before it, so the windows at 00:00 JST
are full when the previous day is on disk; without it, they are NaN until a
window has passed.

## Agreement with the pipeline that produced the data

Hase reimplements these derivations rather than importing them from the
pipeline that built the archive, because a tool you install must not depend on
trading code. That is only safe if the two agree, so the test suite checks
`MarketPrice` against the pipeline's own stored output where that warehouse is
mounted, and skips where it is not. Measured on a full day of
`COINCHECK:BTC_SPOT` and `GMO:BTC_JPY`, the largest relative difference is
4e-16 — floating-point last-bit, from accumulating the levels in a different
order. `Spread` and `Volatility` at an execution size agree with the warehouse
pipeline's stored VolSpread to 2e-9 relative, and the test suite holds the same
formulas written out independently.

## Bronze as trading data

For code that trades rather than plots -- a backtest, a strategy's research
notebook -- `hase.bronze` returns [qate](https://github.com/kamakuraquantlab/qate)'s
objects rather than dataframes:

```python
from hase import bronze
from hase.bronze import DataType
from qate.core.model import Market

market = Market.from_str("BINANCE:BTC_USDT")
bronze.markets()  # [Market, ...] on disk
bronze.dates(market, DataType.ORDER_BOOK)  # complete JST days
books = bronze.load(market, DataType.ORDER_BOOK, "2026-09-01", "2026-09-07")
```

`load` is strict: a missing day raises rather than reading as a quiet market.
`load_day` is the same for one day.

Hase asks Komachi which file holds each market-day (`komachi.bronze.file`)
and opens it; Komachi never looks inside a file, and Hase never builds a bronze
path. That is the whole division: Komachi places files, Hase reads them as
trading data.

## It holds no credential

Hase reads local files. It reaches no API, holds no token, and knows nothing
about entitlement or billing. That single rule is what lets one tool serve both
as a customer product and as an analysis environment for data you already have:
point it at a Komachi download or at your own warehouse, and it behaves the
same.

If a day is missing, Hase says so and tells you the `komachi` command that
would fetch it. It will not fetch anything itself.

## Where it reads from

`--root`, then `ROOT_PATH` in the environment, then `ROOT_PATH` in
`~/.kamakuraquantlab.env`, then `~/kamakuraquantlab-data`. That file is the one
Komachi writes on first use, so the two tools agree without being configured
twice — and if Hase is installed first, it asks the same question and writes
the same file.

Hase does not work that order out for itself: it calls `komachi.data_root()`,
which is why `kamakuraquantlab-komachi` is a dependency. Hase reads the tree
Komachi downloads into, so Komachi is what says where the tree is. Your own
code can ask the same way — `komachi.data_root()` with nothing passed is the
settings file and nothing else, no environment, no default.

Only the data root comes across. The file also holds Komachi's purchase token,
and Hase has no use for one.

```
<root>/bronze/dataset=Trade/exchange=COINCHECK/symbol=BTC_SPOT/date=2025-07-01/data.parquet
```

## Dates are Tokyo days

A `date` partition holds the rows falling in `[00:00 JST, 24:00 JST)`, which is
`15:00` to `14:59` UTC. Timestamps inside the files are UTC epochs.

Plots are labelled in JST, matching the day they were cut in. This needs saying
because matplotlib converts datetimes to plain floats and forgets the zone: a
tz-aware series plots in the right place but is *labelled* in UTC unless the
formatter is told otherwise. A chart titled JST with a UTC axis is worse than
one with no timezone at all, so `plot/style.py` owns the zone and every axis
gets it explicitly.

## What the plots do

**`plot-trades`** — price across the day, with buy and sell volume beneath.
Volume is bucketed (`--bucket`, default `5min`) because a day is tens of
thousands of trades and a bar each is an unreadable smear. Buys and sells are
drawn apart rather than combined, since their balance is the reason to look.

**`plot-book`** — best bid and ask, with the spread beneath. Resampled to `1s`
by default: a day is around 230,000 snapshots, more points than the chart has
pixels. `--no-resample` keeps every one for a short window where the detail
matters. Resampling takes the last value in each interval rather than the mean,
because a mean of neighbouring quotes is a price that never existed and the
spread between two such means can come out negative.

The spread panel clips its view to the 99.5th percentile and labels how many
points fall above the cut. A few momentary wide spreads would otherwise set the
scale and flatten the rest of the day into a line, and hiding them silently
would be worse than saying how many there were.

## Not yet built

Lead-lag, InfluxDB and Grafana export. The lead-lag plot is the piece with no reference implementation.

## Tests

```bash
python -m pytest tests -q
```

Fixtures write real parquet to a temporary directory. No network, no
credentials, no display.
