Merge pull request #94 from vgreg/address-review-code-feedback

Address JOSS reviewer code feedback: __version__, lockfile, sample data

Author: vgreg

.github/workflows/draft-pdf.yml

@@ -0,0 +1,27 @@
+name: Draft PDF
+on:
+  push:
+    paths:
+      - paper/**
+      - .github/workflows/draft-pdf.yml
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: paper/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: paper/paper.pdf

.gitignore

@@ -211,3 +211,7 @@ poetry.lock
 
 docs/guide/data/
 samples/*/data/
+
+
+paper/jats
+paper/paper.pdf

docs/guide/getting-started.md

@@ -2,6 +2,21 @@
 
 This guide will help you get started with MeatPy for processing financial market data.
 
+## Try it without downloading anything
+
+The repository ships a tiny synthetic ITCH 5.0 sample at
+`samples/data/sample.itch50` (590 bytes, two fictional symbols **MEAT** and
+**PYTH**) so you can exercise the parser, processor, and recorders end-to-end
+without a Nasdaq subscription. From a clone of the repo:
+
+```bash
+uv run python samples/itch50/00_quickstart.py
+```
+
+The quickstart counts messages by type and prints the top of book for each
+symbol after replaying every message through `ITCH50MarketProcessor`. See
+`samples/data/README.md` for what the file contains and how to regenerate it.
+
 ## Basic Concepts
 
 ### Core Components
@@ -77,10 +92,12 @@ with ITCH50MessageReader("market_data.txt.gz") as reader:
     for message in reader:
         processor.process_message(message)
 
-# Access the limit order book
-if processor.lob:
-    print(f"Best bid: ${processor.lob.best_bid / 10000:.2f}")
-    print(f"Best ask: ${processor.lob.best_ask / 10000:.2f}")
+# Access the limit order book. `best_bid` / `best_ask` return a `Decimal`
+# already scaled to dollars.
+lob = processor.current_lob
+if lob is not None and lob.bid_levels and lob.ask_levels:
+    print(f"Best bid: ${lob.best_bid:.2f}")
+    print(f"Best ask: ${lob.best_ask:.2f}")
 ```
 
 ## Reading IEX DEEP Data

docs/index.md

@@ -34,6 +34,7 @@ MeatPy is built around several core components:
 ## What's Next?
 
 - Check out the [Installation Guide](installation.md) to get started
+- Run the bundled end-to-end quickstart (`uv run python samples/itch50/00_quickstart.py`) against the synthetic ITCH 5.0 sample shipped at `samples/data/sample.itch50` — no Nasdaq subscription required
 - Read the [User Guide](guide/getting-started.md) for usage instructions
 - See [Contributing](contributing.md) if you want to contribute to the project
 

paper/images/diagram.pdf

@@ -0,0 +1,115 @@
+@article{clarkmcgeheeObjectOrientedLibraryRealTime2013,
+  author    = {Clark McGehee, Laurens E Howle},
+  doi       = {10.4172/2324-9307.1000101},
+  issn      = {2324-9307},
+  journal   = {Journal of Computer Engineering \& Information Technology},
+  langid    = {english},
+  number    = {01},
+  publisher = {OMICS Publishing Group},
+  title     = {An {{Object-Oriented Library}} for {{Real-Time Processing}} of {{NASDAQ Order Book Data}}},
+  urldate   = {2025-07-25},
+  volume    = {02},
+  year      = {2013}
+}
+
+@article{comerton2019inverted,
+  author    = {Comerton-Forde, Carole and Gr{\'e}goire, Vincent and Zhong, Zhuo},
+  doi       = {10.1016/j.jfineco.2019.03.005},
+  journal   = {Journal of Financial Economics},
+  number    = {1},
+  pages     = {141--164},
+  publisher = {Elsevier},
+  title     = {Inverted fee structures, tick size, and market quality},
+  volume    = {134},
+  year      = {2019}
+}
+
+@inproceedings{gaiFastConstructionNanosecond2013,
+  address   = {San Diego California USA},
+  author    = {Gai, Jiading and Choi, Dong Ju and O'Neal, David and Ye, Mao and Sinkovits, Robert S.},
+  booktitle = {Proceedings of the {{Conference}} on {{Extreme Science}} and {{Engineering Discovery Environment}}: {{Gateway}} to {{Discovery}}},
+  copyright = {https://www.acm.org/publications/policies/copyright\_policy\#Background},
+  doi       = {10.1145/2484762.2484825},
+  langid    = {english},
+  month     = jul,
+  pages     = {1--4},
+  publisher = {ACM},
+  title     = {Fast Construction of Nanosecond Level Snapshots of Financial Markets},
+  urldate   = {2025-07-25},
+  year      = {2013}
+}
+
+@article{gregoire2022earnings,
+  author    = {Gr{\'e}goire, Vincent and Martineau, Charles},
+  doi       = {10.1111/1475-679X.12394},
+  journal   = {Journal of Accounting Research},
+  number    = {1},
+  pages     = {261--297},
+  publisher = {Wiley Online Library},
+  title     = {How is earnings news transmitted to stock prices?},
+  volume    = {60},
+  year      = {2022}
+}
+
+@article{huangLOBSTERLimitOrder2011,
+  author     = {Huang, Ruihong and Polak, Tomas},
+  doi        = {10.2139/ssrn.1977207},
+  issn       = {1556-5068},
+  journal    = {SSRN Electronic Journal},
+  langid     = {english},
+  publisher  = {Elsevier BV},
+  shorttitle = {{{LOBSTER}}},
+  title      = {{{LOBSTER}}: {{Limit Order Book Reconstruction System}}},
+  urldate    = {2025-07-25},
+  year       = {2011}
+}
+
+@article{oharaWhatsNotThere2014,
+  abstract   = {We investigate odd-lot trades in equity markets. Odd lots are increasingly used in algorithmic and high-frequency trading, but are not reported to the consolidated tape or in databases such as TAQ. In our sample, the median number of odd-lot trades is 24\% but in some stocks odd lots are 60\% or more of trading. Odd-lot trades contribute 35\% of price discovery, consistent with informed traders using odd lots to avoid detection. Omitting odd-lot trades leads to inaccuracies in order imbalance measures and makes sentiment measures unreliable. Excluding odd lots from the consolidated tape raises important regulatory issues.},
+  author     = {O'Hara, Maureen and Yao, Chen and Ye, Mao},
+  copyright  = {http://onlinelibrary.wiley.com/termsAndConditions\#vor},
+  doi        = {10.1111/jofi.12185},
+  issn       = {0022-1082, 1540-6261},
+  journal    = {The Journal of Finance},
+  langid     = {english},
+  month      = oct,
+  number     = {5},
+  pages      = {2199--2236},
+  publisher  = {Wiley},
+  shorttitle = {What's {{Not There}}},
+  title      = {What's {{Not There}}: {{Odd Lots}} and {{Market Data}}},
+  urldate    = {2025-07-25},
+  volume     = {69},
+  year       = {2014}
+}
+
+@article{shkilkoEveryCloudHas2020,
+  abstract   = {Modern markets are characterized by speed differentials, with some traders being fractions of a second faster than others. Theoretical models suggest that such differentials may have both positive and negative effects on liquidity and gains from trade. We examine these effects by studying a series of exogenous weather episodes that temporarily remove the speed advantages of the fastest traders by disrupting their microwave networks. The disruptions are associated with lower adverse selection and lower trading costs. In additional analysis, we show that the long-term removal of speed differentials results in similar effects and also increases gains from trade.},
+  author     = {Shkilko, Andriy and Sokolov, Konstantin},
+  copyright  = {http://onlinelibrary.wiley.com/termsAndConditions\#vor},
+  doi        = {10.1111/jofi.12969},
+  issn       = {0022-1082, 1540-6261},
+  journal    = {The Journal of Finance},
+  langid     = {english},
+  month      = dec,
+  number     = {6},
+  pages      = {2899--2927},
+  publisher  = {Wiley},
+  shorttitle = {Every {{Cloud Has}} a {{Silver Lining}}},
+  title      = {Every {{Cloud Has}} a {{Silver Lining}}: {{Fast Trading}}, {{Microwave Connectivity}}, and {{Trading Costs}}},
+  urldate    = {2025-07-25},
+  volume     = {75},
+  year       = {2020}
+}
+
+@article{yaali2022hftviz,
+  author    = {Yaali, Javad and Gr{\'e}goire, Vincent and Hurtut, Thomas},
+  doi       = {10.1177/14738716211064921},
+  journal   = {Information Visualization},
+  number    = {2},
+  pages     = {182--193},
+  publisher = {SAGE Publications Sage UK: London, England},
+  title     = {HFTViz: Visualization for the exploration of high frequency trading data},
+  volume    = {21},
+  year      = {2022}
+}