🐛 fixed broken links

README.md

@@ -1,27 +1,31 @@
 # microstructure-plotter
 
-**For those of you in the trenches, I offer ye this tool ⚔️.** 
+**For those of you in the trenches, I offer ye this tool ⚔️** 
 
 This is a plotting tool designed to help visualize financial market data 📈 and trading system behavior 🤖 on the smallest timescales 🔎. 
 
-As all things in life, when it comes to microstructure & HFT: _the devil is in the details_. 
+As all things in life, when it comes to financial microstructure: _the devil 😈 is in the details_ 
 
-Built using [Chaco](https://docs.enthought.com/chaco/index.html) 🌮.
+Built using [Chaco](https://docs.enthought.com/chaco/index.html) 🌮
+
+See the [illustrated example](#illustrated-example) for a deep dive into what this plotting tool can uncover 🔎.
 
 ![zoooooom](/assets/plotter_video.gif)
 
+![orders](/assets/erratic_valuation_3.png)
+
 ## Contents
 
-- [⚠️Disclaimer](#⚠️disclaimer)
-- [🧪Test It Out Right Now](#🧪test-it-right-out-now)
-- [✨Features](#✨features)
-- [🧠Illustrated Example](#🧠illustrated-example)
-- [🗺️Plots Legend](#🗺️plots-legend)
-- [💸Free Advice](#💸free-advice)
-- [✏️Data Schema](#✏️data-schema)
-- [🤔What is "Market Microstructure"?](#🤔what-is-market-microstructure)
-- [🛞Installation](#🛞installation)
-- [	📜Reqs](#📜reqs)
+- [⚠️Disclaimer](#%EF%B8%8Fdisclaimer)
+- [✨Features](#features)
+- [🧠Illustrated Example](#illustrated-example)
+- [🧪Test It Out Right Now](#test-it-out-right-now)
+- [🗺️Plots Legend](#%EF%B8%8Fplots-legend)
+- [💸Free Advice](#free-advice)
+- [✏️Data Schema](#%EF%B8%8Fdata-schema)
+- [🤔What is "Market Microstructure"?](#what-is-market-microstructure)
+- [🛞Installation]#installation)
+- [	📜Reqs](#reqs)
 - [𓊍To Do](#𓊍to-do)
 - [Citation](#citation)
 - [License](#license)
@@ -30,55 +34,55 @@ Built using [Chaco](https://docs.enthought.com/chaco/index.html) 🌮.
 
 There is no α here. This is just a fancy wrapper on top of an open-source plotting package. 
 
-You should _Bring Your Own Alpha_ (**B.Y.O.A.**). 
+You should **B.Y.O.A** (_Bring Your Own Alpha_). 
 
-**HOWEVER**...for the trained eye, this simple type of visualization can be immensely helpful.
+**However**...for the trained eye 👁️, this simple type of visualization can be immensely helpful.
 
-## 🧪Test It Right Out Now
+## ✨Features
 
-After installing the package either via [pip](#🛞installation) or via [setup.py](#📜reqs), run this quick line to see this in action right now:
+Here are some useful features to take note of 🥁: 
 
-``` bash examples/example_1/plot_example.sh ``` 
+1. ✨Plot **multiple** 🤹, asynchronous (unsampled) microstructure elements together on **the sample plot**: <ins>order book quotes</ins>, <ins>trades</ins>, <ins>orders</ins>, <ins>order acks</ins>, <ins>fills</ins> etc etc
+2. ✨Analyze events on seconds, milliseconds, microseconds, _nanoseconds_ 🕳️ ➡️ zoom 🔎 in on the **most granular time unit** available to microstructure behavior.
+3. ✨All axes are 🔗**linked** ➡️ <ins>zoom 🔎 in on one product, see what's happening in all others at that same timestamp</ins>
 
-or 
+## 🧠Illustrated Example
 
-``` python examples/example_1/plot_example.py ``` 
+To show why a tool like this might be useful, [here](/examples/README.md) is an example motivated from things seen in the wild.
 
-**Right-click** 🖱️ to zoom in on different parts of the plot to see what is happening on **smaller** and **_smaller_** timescales 🔎. You may want to consult the [legend](#🗺️plots-legend) 👇 or [illustrated example](#🧠illustrated-example) 👇.
+<ins>Note</ins>: This data was painstakingly created _by hand_ 🤌 to appear quasi-realistic. I am not an artist 🧑‍🎨 nor is this real 🌎 data. 
 
-## ✨Features
+See the [legend](#plots-legend) 👇 to understand the plots further.
 
-Here are some useful features to take note of 🥁: 
+## 🧪Test It Out Right Now
 
-1. ✨Plot multiple 🤹, asynchronous (unsampled!) microstructure elements together on the sample plot: <ins>order book quotes</ins>, <ins>trades</ins>, <ins>orders</ins>, <ins>order acks</ins>, <ins>fills<ins> etc.
-2. ✨Analyze events on seconds, milliseconds, microseconds, nanoseconds 🕳️ - Zoom in on the most granular time unit available using **Right-click zoom**.
-3. ✨All products axes are 🔗linked - zoom in on one product, see what's happening in all others at that same timestamp
+After installing the package either via [pip](#installation) or via [setup.py](#reqs), run this quick line to see this in action right now:
 
-## 🧠Illustrated Example
+``` bash examples/example_1/plot_example.sh ``` 
 
-To show why a tool like this might be useful, [here](/examples/README.md) is an example motivated from things seen in the wild.
+or 
 
-<ins>Note</ins>: This data was painstakingly created _by hand_ 🤌 to appear quasi-realistic. I am not an artist 🧑‍🎨 nor is this real 🌎 data. 
+``` python examples/example_1/plot_example.py ``` 
 
-See the [legend](#🗺️plots-legend) 👇 to understand the plot further.
+**Right-click** 🖱️ to zoom in on different parts of the plot to see what is happening on **smaller** and **_smaller_** timescales 🔎. Consult the [legend](#plots-legend) or [illustrated example](#illustrated-example) for more clarity on how to interpret the plots.
 
 ## 🗺️Plots Legend
 
 [Here](/docs/legend/README.md) is a complete legend of everything the plotter can visualize.
 
 ## 💸Free Advice
 
-1. <ins>_Don't log ✏️ in prod_</ins> (unless logging isn't occuring on the hot path). 
+1. <ins>_Don't log in prod_</ins> ✏️ (unless logging isn't occuring on the hot path). 
 2. Make sure the timestamps are from ⏰ <ins>_synchronized clocks_</ins> ⏰ (better if geosync'd/GPS) with enough precision, otherwise these plots will be uninformative or misleading. If you don't trust others' timestamps, do your own capture. 
 3. This plotter is _memory intensive_ 🧠. Don't try to plot too much at once. 
 
 ## ✏️Data Schema
 
-This plotting module expects a specific data schema that is described [here](/docs/schema/README.md).
+This plotting module expects a specific [data schema](/docs/schema/README.md).
 
 ## 🤔What is "Market Microstructure"?
 
-_For the uninitiated, here is a ⏰ 30 second primer ⏰ on market microstructure [here](/docs/micro_primer/README.md)_.
+_For the uninitiated, here is a [⏰ 30 second primer ⏰ on market microstructure](/docs/micro_primer/README.md)_.
 
 ## 🛞Installation
 

docs/micro_primer/README.md

@@ -1,39 +1,49 @@
 
 # Microstructure Primer
 
-Markets can be decomposed into exchanges and the participants that trade on those exchanges: 
+Markets can be decomposed into exchanges and the participants that trade on those exchanges
 
-1. **"market makers" or "scalpers" or "liquidity providers":** those offering to provide a quantity needed for a theoretical premium over what they think the security is worth.  
+![order book](/assets/order_book.png)
 
-2. **"takers"**, those who want a certain amount of a security and are willing to "take" the market makers' price. They could want to get into that position for a number of reasons: 
+## Market Makers:
 
-- they think the <ins>market is mispriced</ins> (relative to their own view on whatever horizon they think) 
-- they are trying to <ins>hedge a risk</ins> in their portfolio 
-- they are executing for behalf of a client 
+**"market makers" or "scalpers" or "liquidity providers":** those offering to provide a quantity needed for a theoretical premium over what they think the security is worth.  
+
+The market makers compete with one another either by providing **better prices**, or **offering more size**, or having **waited around in a queue longer** (time priority), or **paying for the right to match first** (think "free" brokerage companies selling your orders). Their price and quantities are **aggregated** by the exchange to form a **"central limit order book"** (CLOB), which reflect the current overall "best market price" to buy or sell a security at any time. 
+
+## Takers:
+
+**"takers"**: those who want a certain amount of a security and are willing to "take" the market makers' price. They could want to get into that position for a number of reasons: 
+
+- they think the _market is mispriced_ (relative to their own view on their longer time horizon) 
+- they are trying to _hedge a risk_ in their portfolio 
+- they are executing on behalf of a client 
 
 Of course, most sophisticated players <ins>don't fall cleanly</ins> into either of these categories. 
 
 Generally, there are _more market makers_ than _takers_ at any given time. 
 
-The market makers compete with one another either by providing **better prices**, or **offering more size**, or having **waited around in a queue longer** (time priority), or **paying for the right to match first** (think "free" brokerage companies selling your orders). Their price and quantities are **aggregated** by the exchange to form a **"central limit order book"** (CLOB), which reflect the current overall "best market price" to buy or sell a security at any time. 
+## Exchange Software
 
 The exchange provides the platform (i.e. software) for the makers and takers to meet and trade. In the event that a taker wants to initiate a trade  (be the "aggressor"), the exchange has a **matching engine** with a series of rules to determine how much of the taker's order to allocate to each of the market makers' orders (the "passive parties"). _Different matching engines rules incentivize different types of competition among market makers._
 
-[order book](/assets/order_book.png)
-
 The exchange software has a number of connected nodes, chief among them: 
 
 - **an order book**: a data structure aggregating the market makers' orders into "the market" for a given security 
 - **a matching engine**: adds orders to the order book and executes trades between parties, allocating a given taker's order among the market makers  
 - **a pricefeed**: disseminates quotes, trades, etc - changes in public market state (unless it's a dark pool!) 
 - **an order gateway**: an API for participants to communicate their price and quantity preferences to the exchange - depending on the exchange, there might be a multitude of order types (particularly if there are restrictions like REG NMS) 
 
-How these participants interact, their impact on market prices, and the way exchange software behave are <ins>**market microstructure**</ins>.
+How these participants interact, their impact on market prices, and the way exchange software behave are ✨<ins>**market microstructure**</ins>✨.
+
+## Latency
 
 Since most of these participants are actually **trading algos** 🤖, the timescales at which all these interactions occur is _quite small_. In many web-based AI applications, **25 milliseconds (ms)** is considered a bleeding edge response time (also accounting for the fact that internet is a very unpredictable and slow medium). For most of these market participants to compete, they need response times of **<1 microsecond (us)** ⏰.
 
-The pace at which market prices change depends on the regime: if it's 7pm on a Thursday, there may be barely any updates within an hour. If it's [**non-farm payrolls**](https://www.cnbc.com/nonfarm-payrolls/), then there is likely a _ton_ of activity and the exchange is likely overloaded/queuing. 
+The pace at which market prices change depends on the regime. If it's 7pm on a Thursday, there may be barely any updates within an hour. If it's [**non-farm payrolls**](https://www.cnbc.com/nonfarm-payrolls/), then there is likely a _ton_ of activity and the exchange is likely overloaded/queuing. 
+
+This means that raw market data is fundamentally **_asynchronous_, _non-uniform_, _event-level_ time series**📈. 
 
-This means that raw market data is fundamentally **_asynchronous_, _non-uniform_, _event-level_ time series**. 
+## Resources
 
 For a very confusing, vague explanation, read the Wikipedia article [here](https://en.wikipedia.org/wiki/Market_microstructure).

docs/schema/README.md

@@ -1,6 +1,6 @@
 # Schema
 
-Here are the fields and data types expected for each data input. Only quote data is a required input; all others are optional. 
+Here are the fields and data types expected for each data input. Only the quote data is a required input. All others are optional. 
 
 ## Quote Data
 
@@ -42,4 +42,4 @@ Here are the fields and data types expected for each data input. Only quote data
 
 ## Code 
 
-Reference [microplot::schema](microplot/schema.py).
+Reference [microplot::schema](/microplot/schema.py).

examples/README.md

@@ -6,19 +6,18 @@ Here is a gallery of hand-crafted examples to illustrate the value of such a too
 
 You may want to first check out [the legend](docs/legend/README.md) and perhaps [the 30 second primer on microstructure](/docs/micro_primer/README.md) prior.
 
-## Example_1
+## Example
 
-The data as well as plotting scripts can be found in `examples/example_1`. 
+This example contains 3 different "events" of interest commonly found in the wild: 
 
-<ins>This example contains 3 different "events" of interest commonly found in the wild</ins>: 
+1. <ins>Event 1:</ins> [💸 Erratic valuation](#event-1-erratic-valuation)
+2. <ins>Event 2:</ins> [😔 Didn't send order](#event-2-didnt-send-order)
+3. <ins>Event 3:</ins> [🚀 Trade-through-the-stack event](#event-3-trade-through-the-stack-event)
 
 ![examples](/assets/zoomed_out_events.png)
 
-1. <ins>Event 1:</ins> [💸 Erratic valuation](#💸-erratic-valuation)
-2. <ins>Event 2:</ins> [😔 Didn't send order](#😔-didnt-send-order)
-3. <ins>Event 3:</ins> [🚀 Trade-through-the-stack event](#🚀-trade-through-the-stack-event)
 
-### 💸 Erratic valuation
+### Event 1: 💸 Erratic valuation
 
 Here is an example of a valuation gone amuck and leading to bad trades.
 
@@ -42,17 +41,17 @@ On the ⏰ _microsecond_ ⏰ timescale, we can start to appreciate what happened
 
 1. Our  🤖 trading algo's theoretical value spiked through the offer 3 ticks/levels, causing the algo to send cancels for those 3 levels. 
 
-2. There clearly is also logic related to sending aggressive/taking orders related to this theoretical value. The system sent such a new order and got immediately filled. (Note again it's pratically impossible to get filled at that level and you would have bought a level below.) 
+2. There clearly is also logic for aggressive/taking orders based on this theoretical price. The system sent such a new order and got immediately filled. (Note again it's pratically impossible to get filled at that level and you would have bought a level below.) 
 
 3. The exchange acks from these requests came back serially, probably due to being sent to the same exchange order router or having an order gateway priority queue internally (this varies by exchange architecture). 
 
 Now looking at the other blip, we see that the same thing happened where the trading algo sold due to a spike down in valuation.  
 
 ![erratic valuation 4](/assets/erratic_valuation_4.png)
 
-For a refresher on plot items, check out [the legend](docs/legend/README.md).
+For a refresher on plot items, check out [the legend](/docs/legend/README.md).
 
-### 😔 Didn't send order
+### Event 2: 😔 Didn't send order
 
 ![didn't send 1](/assets/didnt_send_1.png)
 
@@ -64,9 +63,7 @@ Zoom in further via right clicking 🖱️ to see further details 🔎.
 
 ![didn't send 2](/assets/didnt_send_2.png)
 
-Here we can start to appreciate that the 🤖 trading algo's theoretical valuation for Coin B is responding to _something_ and seems informative (most likely Coin A's pricepoint changes).
-
-Also note the "flickering" markets after this event. 
+We can also see that the 🤖 trading algo's theoretical valuation for Coin B is responding to _something_ and seems informative (most likely Coin A's pricepoint changes).
 
 Zoom in further via right clicking 🖱️ to see further details 🔎.
 
@@ -76,7 +73,7 @@ Finally, the picture becomes a little clearer. Coin A's market ticked down ("bid
 
 This is suspicious, and needs to be investigated further to see if it is a bug 🐛. 
 
-### 🚀 Trade-through-the-stack event
+### Event 3: 🚀 Trade-through-the-stack event
 
 Finally, we examine the 3rd event, where a very large trade occurs in the market. The trade is so large, it exhausts multiple levels in the order book. This is known as a "trade through the stack" or "sweep" depending on who you ask. 
 
@@ -86,4 +83,4 @@ We see that the TTS was first reported in Coin A. The 🤖 trading algo's valuat
 
 Responding to this change in valuation, the system attempts to cancel it's offer at the Best Offer and send a New Order several levels through the book (likely, an aggressive order). Notice that the exchange rejected both of these requests and later showed that the system was filled in Coin B. We can see later that a TTS also happened in Coin B, likely by the same aggressor as Coin A. 
 
-Reporting of events can sometimes come in odd orders depending on the exchange behavior. However, it looks like the trading algo's behavior was optimal in this situation - it just wasn't able to successfully act. This is just the cost of doing business. 
+Reporting of events can sometimes come in an on odd order depending on the exchange design. However, it looks like the trading algo's behavior was optimal in this situation - it just wasn't able to successfully act. This is just the cost of doing business.