# TLAB Stats — User Manual

*Stats by Target, live inside Bookmap.*

---

> ## ⚠️ MUST READ FIRST — [DISCLAIMER](DISCLAIMER.md)
>
> **TLAB Stats is NOT financial advice.** It is a software tool for
> informational and educational use only. The numbers it displays — every
> level, every probability, every banner, every stat — **may be wrong**.
> **You alone** are responsible for verifying every value, every session,
> and for every trading or financial decision you make. Past performance
> does not predict future results. Trading involves substantial risk of
> loss. **No warranty. No liability.** By downloading, installing, or using
> this addon you confirm that you have read and accepted the full
> **[DISCLAIMER](DISCLAIMER.md)**.

---

## 1. What it is

TLAB Stats is a Bookmap addon that opens its own window and shows Tom B.'s
**"Stats by Target"** touch-probability table for the current session:

- every reference level for the day, sorted by how near price is to it;
- each level's historical hit **probability** for today's open type;
- your **own** empirical hit rate for that level, tracked automatically;
- which levels price has already **hit**, and at what time.

It is self-contained — it needs no other software. All it asks of you is six
numbers a day (yesterday's RTH levels) in a small CSV.

---

## 2. Requirements

- **Bookmap** (the addon targets the Simplified API; built against Bookmap 7.x).
- The addon jar: `tlab-stats-v*.jar` (in this repo) — the filename carries the
  version.

---

## 3. Installing the addon

You need two files from the repo: **`tlab-stats-v1.01.jar`** (the addon) and
**`prior_day_levels.csv`** (the daily-levels template). Download both via
GitHub's "Download raw" button on each file, or use **Code → Download ZIP**
to grab everything at once.

1. **Save `prior_day_levels.csv` to your home folder.** On Windows this is
   `C:\Users\<your-name>\` — open File Explorer, type `%USERPROFILE%` in the
   address bar to get there. The addon looks here by default. If you prefer
   another location, save it anywhere and override the path in step 5.
2. **In Bookmap:** open **Settings → Configure add-ons** (the add-ons dialog).
3. Click **Add** and select **`tlab-stats-v1.01.jar`** from wherever you
   downloaded it.
4. Tick **`TLAB Stats - Stats by Target`** in the list to activate it.
5. *(Only if your CSV is NOT in your home folder.)* Click the **`TLAB Stats -
   Stats by Target`** entry to open its settings panel, and set **Daily levels
   CSV** to the full path of your file.
6. The TLAB Stats window opens on its own a moment later (once the first trade
   arrives). If you close it, reopen it with **Open TLAB Stats window** in the
   add-on's settings panel.

**Updating to a new version:** untick TLAB Stats → **Remove** → **Add** the new
`tlab-stats-v*.jar` → tick it again. Bookmap locks the old file while it is loaded,
so it must be removed first. The current version number is shown at the bottom
of the window.

---

## 4. First-time setup — the daily CSV

TLAB Stats self-generates almost everything, but it **cannot** know yesterday's
RTH levels — those must be supplied. Open the **`prior_day_levels.csv`** you
saved in your home folder (§3 step 1) and replace the six values with **today's**
prior-day numbers:

```
P High,7512.50
P Low,7488.25
P Close,7501.00
P VPOC,7499.50
P VAH,7505.75
P VAL,7494.00
```

- Names are case- and space-insensitive (`P High`, `pHI`, `phigh` all work).
- `P Mid` is derived automatically (midpoint of P High and P Low).
- Lines beginning with `#` are comments.
- **Edit it in Notepad, not Excel** — Excel reformats CSV files.
- The addon watches the file and reloads it the moment you save. There is also
  a **Reload CSV** button in the window.

The overnight levels and the Initial Balance are **self-generated** and do not
belong in the CSV. (The CSV has optional commented-out lines for them, used only
as a fallback if Bookmap's backfill cannot reach the overnight session.)

> ⚠️ If the prior-day rows in the window look wrong, it is almost always because
> the CSV still has the template's sample numbers. Replace them.

---

## 5. The window — a walkthrough

### Toolbar (top)

- **Day type** — `Auto-detect`, or force a column: HIR / LIR / HOR / LOR /
  In Range / Out of Range. This selects which probability column drives every
  number in the window.
- **Always on top** — keep the window above other windows.
- **Reload CSV** — re-read the daily CSV immediately.

### Header

```
TLAB Stats  -  ESM6.CME@TM.Lite
HOR  -  High Out of Range (gap up)   -   Gap +1.44%   -   Prior range 16.50
Price: 7506.75
```

The instrument, the classified **open type**, the **gap** from prior close, the
prior-day **range**, and the live **price**.

### 12:1 stat banner

A gold caution strip appears below the price line when the **"12:1 stat"**
triggers. It is **fully automatic** — the addon evaluates Tom B.'s rule itself.

The stat is **qualified** when **both** of these hold:

1. A new daily **high or low** is made during the 12-1 PM CST window
   (1:00–2:00 PM ET).
2. That new high/low prints **outside the prior day's range** — above
   `P High`, or below `P Low`.

When qualified, the stat gives roughly a **71%** chance of breaking the day's
high/low and an **86%** chance of coming within **1 point (4 ticks)** of it —
*do not fade it*.

The banner is an **observation, not a level** — it never appears in the table
below. It reads **forming** while the window is open, then resolves on its own
after 1 PM CST: **QUALIFIED — DO NOT FADE** if both conditions hold, or **not
qualified** if the new extreme stayed inside yesterday's range. It needs
`P High` / `P Low` in the daily CSV to judge condition 2 — if they're missing
it says so. The banner clears at the next session.

### LEVELS table

Every tracked level, **sorted nearest-to-price first**; levels already hit drop
to the bottom. Each row has five columns:

| Column | Meaning |
|---|---|
| `99%/63%` | **Dual stat** — Stat % / My % (see §6) |
| `●●●○○○○○` | **Proximity meter** — how close price is to the level (see §7) |
| `ONH` | Level name |
| `7507.75` | Level price |
| `▼1.42%` or `09:32:23` | Distance from price — **or**, if hit, the green hit time |

### NEXT UP

The five nearest un-hit levels — the levels price is most likely to reach next.

### HIT SEQUENCE

A numbered log of every level hit this RTH session, in order, with the time and
an up/down arrow.

### Footer

`4 / 17 levels hit · column: HOR · history: 12 sessions · 14:11:06 ET`
and, on the very bottom line, the **version number**.

---

## 6. The dual stat — `Stat % / My %`

Each level shows two numbers, e.g. `IBH  99%/63%`:

- **Stat % (first number)** — the historical "Stats by Target" probability for
  the current day type — Tom B.'s published number. For a **paired** level
  (IBH/IBL, ONH/ONL, pVAH/pVAL, pHigh/pLow, the IB 1.5× and 2.0× pairs) this is
  the *"either of the pair gets hit"* rate. Once the **sibling** level is
  tagged, it flips to the *"both hit"* rate — so the number updates as the
  session develops. Example: before either IB extreme is hit, IBH and IBL both
  show ~99%; once IBH is hit, IBL drops to the ~24% "both hit" rate.

- **My % (second number)** — your own empirical hit rate, tracked automatically
  (see §10). It shows `-` until enough sessions have been recorded.

Personal tracking is **optional**. Untick **Track my personal stats** and the
addon shows the **Stat % only** — the My % column is hidden and nothing is
written to disk. Tick it again to bring My % back. See §10 and §12.

---

## 7. The proximity meter

The 8-dot meter (`●●●○○○○○`) shows **how close price is to that level**:

- a **full** meter ≈ price is almost on the level;
- an **empty** meter ≈ the level is 40+ points away;
- each dot ≈ 5 points.

A hit level shows a full green meter.

---

## 8. Day-type classification

At the RTH open the addon classifies the day from the opening price against the
prior-day levels:

- open **above P High** → **HOR** (High Out of Range, gap up)
- open **below P Low** → **LOR** (Low Out of Range, gap down)
- open **in range, ≥ P Close** → **HIR** (High In Range)
- open **in range, < P Close** → **LIR** (Low In Range)

The result selects the probability column. Before the open (or with no CSV
loaded) the **All-days** column is used. You can override the classification
with the **Day type** toolbar control.

---

## 9. Backfill — attach any time

TLAB Stats uses Bookmap's Simplified API, which delivers a data clock and
**backfilled historical trades**. When you attach the addon — even at midday —
Bookmap replays the session through it with the **original timestamps**, so:

- a level hit at 10:00 is shown as hit and stamped 10:00;
- the **Initial Balance** (09:30–10:30) rebuilds itself;
- the **overnight levels** and today's open are reconstructed.

You do **not** have to run the addon all session.

> Backfill covers however much history Bookmap has loaded for that chart —
> normally the whole session. If an early stretch looks missing, scroll the
> chart back to load more history and it fills in.

---

## 10. The history file — your personal stats

When **Track my personal stats** is enabled (the default), the addon records
every **live** session it runs to a per-instrument file:

```
~/BmStats_history_<instrument>.csv
```

One row per session: `date, dayType, then 1/0 for each level`. This is what
powers the second number in the dual stat. The file defaults to your home
folder; the **History folder** setting (§12) can place it anywhere. The rate
shown is the **overall** rate until a day-type bucket has at least 10 sessions,
after which that bucket switches to its day-type-specific rate. Hover a level
for the sample size.

Backfilled past days are **not** recorded — only sessions you actually ran live
— so the personal stat is a true forward record. It is a plain CSV; you may
open or inspect it.

---

## 11. The tracked levels

| Group | Levels | Source |
|---|---|---|
| Overnight | ONH, ONL, ON VPOC, ON Mid | self-generated |
| Initial Balance | IBH, IBL, IBH 1.5, IBL 1.5, IBH 2.0, IBL 2.0 | self-generated |
| Prior day | P High, P Low, P Close, P VPOC, P VAH, P VAL, P Mid | the daily CSV (P Mid derived) |
| 30-min IB *(optional)* | IBH 30, IBL 30 | self-generated — see below |

IB extensions are projections of the IB range from the opposite IB extreme:
`IBH 1.5 = IBL + 1.5 × (IBH − IBL)`, and so on.

**The 60-minute Initial Balance always shows** — IBH, IBL and the four
extensions, each with its probability. IB levels are tracked for hits once the
hour-long IB window closes (one hour after the session open).

**The 30-minute IB is optional** — tick **Show the 30-minute IB** in the
settings panel and two extra reference lines appear, `IBH 30` and `IBL 30`
(the high/low of the first 30 minutes). They are a *nice-to-know* reference
only: no extensions, no probability, no tracked %, and never written to the
history file. The `—` in their stat column is intentional.

Overnight and prior-day levels are tracked from the session open. The session,
the IB and the 30-min IB are all measured from the configurable **Session
open** time (§12), default 09:30 ET.

---

## 12. Settings

In the add-on's settings panel (in Bookmap's Configure add-ons dialog):

| Setting | Default | Meaning |
|---|---|---|
| Daily levels CSV | `<your home>\prior_day_levels.csv` (e.g. `C:\Users\<name>\prior_day_levels.csv`) | full path to the CSV. Default is your home folder — change if you saved it elsewhere. |
| Track my personal stats | on | off = Stat % only (My % column hidden); no history file written or read |
| History folder | *(blank)* | folder for the session-history CSV — blank = your home folder |
| Hit tolerance (ticks) | `0` | slack added before a level counts as hit |
| Session open (ET) | `09:30` | RTH session start — the IB is measured from here |
| Session close (ET) | `16:00` | RTH session end |
| Show the 30-minute IB | off | adds `IBH 30` / `IBL 30` reference lines |
| Hit sound | Off | sound on each fresh hit — Beep / Ding / Chime / Bell / Buzz (live only); **Test** button previews it |

The day type, always-on-top and window settings also persist automatically
through Bookmap. Session times are best set before the session — changing them
mid-session does not retroactively rebuild the Initial Balance.

---

## 13. Troubleshooting

| Symptom | Cause / fix |
|---|---|
| Prior-day rows show odd prices | The CSV still has the template's sample numbers — replace them with today's. |
| Overnight / IB levels blank | Backfill did not reach that part of the session — scroll the chart back to load more history, or fill the optional CSV lines. |
| A second, blank window appeared | Should not happen from v1 onward — the window opens lazily and is single-instance. If it does, report it. |
| Window didn't open | It opens on the first trade. Use **Open TLAB Stats window** in the settings panel, or wait for a trade. |
| Numbers seem one day stale | Update the CSV; it is yesterday's data, not today's. |

---

## 14. Source code

Source code is **not** part of this distribution. TLAB Stats is proprietary
(see §17). The shipped jar is ProGuard-obfuscated. If you need to build from
source for a legitimate reason, contact the author.

---

## 15. Versioning

The current version is shown at the bottom of the TLAB Stats window and carried
in the jar filename (`tlab-stats-v<version>.jar`). See [CHANGELOG.md](CHANGELOG.md)
for release notes.

---

## 16. Support

TLAB Stats is a **free add-on**, provided as-is. If you find a bug, report it —
bugs are addressed when they are brought to the author's attention. Beyond bug
fixes there is **no support of any kind**, and none is implied: not from Sean
Etchason, not from TraderLab, not from Tom B., and not from Bookmap. You run the
add-on at your own discretion.

---

## 17. Licence

TLAB Stats is **proprietary** — free to use inside Bookmap, but not open source.
You may run it; you may **not** copy, redistribute, modify, decompile, reverse
engineer, or reuse the code or the jar, nor submit it to an AI or automated
system to reproduce or decompile it. See the `LICENSE` file for the full terms.

---

*Stats are for illustration only. Past performance is not indicative of future
results. Context supersedes statistics — no exceptions.*