Correct localize coordinates, validation, charts, and regional errors

book/src/advanced_usage.md

@@ -1493,10 +1493,14 @@ Options:
           centered
 
   -w, --window <EXPAND_WINDOW>
-          Number of base pairs to search around, for example if your BED region
-          records are single positions, a window of 500 will look 500 base pairs
-          upstream and downstream of that position. If your region BED records
-          are larger regions, this will expand from the midpoint of that region
+          Number of base pairs to search around. The original BED feature
+          midpoint remains offset zero. Output offsets are the bedMethyl
+          position minus that midpoint: negative is toward lower reference
+          coordinates and positive toward higher reference coordinates,
+          independent of feature strand. Profiles produced by affected earlier
+          releases must be regenerated because both queried membership and
+          offset bins can differ. For example, a window of 500 searches 500 bases
+          on each side
 
           [default: 2000]
 

book/src/intro_localize.md

@@ -20,12 +20,16 @@ modkit localise ${bedmethyl} --regions ${ctcf} --genome-sizes ${sizes}
 
 The output table has the following schema:
 
-| column | Name             | Description                                                                                                         | type  |
-|--------|------------------|---------------------------------------------------------------------------------------------------------------------|-------|
-| 1      | mod code         | modification code as present in the bedmethyl                                                                       | str   |
-| 2      | offset           | distance in base pairs from the center of the genome features, negative values reflect towards the 5' of the genome | int   |
-| 3      | n_valid          | number of valid calls at this offset for this modification code                                                     | int   |
-| 4      | n_mod            | number of calls for this modification code at this offset                                                           | int   |
-| 5      | percent_modified | `n_mod` / `n_valid`  * 100                                                                                          | float |
+| column | Name             | Description                                                                                                                                                                               | type  |
+|--------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------|
+| 1      | mod code         | modification code as present in the bedmethyl                                                                                                                                             | str   |
+| 2      | offset           | bedMethyl position minus the original feature midpoint; negative is toward lower reference coordinates and positive toward higher coordinates, independent of the BED feature strand      | int   |
+| 3      | n_valid          | number of valid calls at this offset for this modification code                                                                                                                           | int   |
+| 4      | n_mod            | number of calls for this modification code at this offset                                                                                                                                 | int   |
+| 5      | percent_modified | `n_mod` / `n_valid`  * 100                                                                                                                                                                | float |
+
+Profiles produced by affected earlier modkit releases must be regenerated before
+comparison because both queried membership and offset bins can differ. The
+reference-coordinate axis is not reversed for negative-strand features.
 
 Optionally the `--chart` argument can be used to create HTML charts of the modification patterns.