Merge pull request #497 from lubitelpospat/documentation/dmr-output-clarification

DMR documentation enhancement

Author: ArtRand

book/src/intro_dmr.md

@@ -174,9 +174,9 @@ The output from `modkit dmr pair` (and for each pairwise comparison with `modkit
 | 5      | score                                | difference score, more positive values have increased difference                                           | float |
 | 6      | strand                               | strand for the region or single-base position                                                              | str   |
 | 7      | sample<sub>a</sub> counts            | counts of each base modification in the region, comma-separated, for sample A                              | str   |
-| 8      | sample<sub>a</sub> total             | total number of base modification calls in the region, including unmodified, for sample A                  | str   |
+| 8      | sample<sub>a</sub> total             | total number of base modification calls in the region, including unmodified, for sample A                  | int   |
 | 9      | sample<sub>b</sub> counts            | counts of each base modification in the region, comma-separated, for sample B                              | str   |
-| 10     | sample<sub>b</sub> total             | total number of base modification calls in the region, including unmodified, for sample B                  | str   |
+| 10     | sample<sub>b</sub> total             | total number of base modification calls in the region, including unmodified, for sample B                  | int   |
 | 11     | sample<sub>a</sub> percents          | percent of calls for each base modification in the region, comma-separated, for sample A                   | str   |
 | 12     | sample<sub>b</sub> percents          | percent of calls for each base modification in the region, comma-separated, for sample B                   | str   |
 | 13     | sample<sub>a</sub> fraction modified | fraction modification (of any kind) in sample A                                                            | float |
@@ -247,6 +247,28 @@ modkit dmr pair \
 ```
 these columns will not be present.
 
+The full table when performing single-site analysis with equal numbers of samples in groups, when running `modkit dmr pair`, will have the following schema:
+
+| column | name                                 | description                                                                                                | type  |
+|--------|--------------------------------------|------------------------------------------------------------------------------------------------------------|-------|
+| 1      | chrom                                | name of reference sequence from bedMethyl input samples                                                    | str   |
+| 2      | start position                       | 0-based start position, from `--regions` argument                                                          | int   |
+| 3      | end position                         | 0-based exclusive end position, from `--regions` argument                                                  | int   |
+| 4      | name                                 | `name` column from `--regions` BED, or `chr:start-stop` if absent, "." for single sites                    | str   |
+| 5      | score                                | difference score, more positive values have increased difference                                           | float |
+| 6      | strand                               | strand for the region or single-base position                                                              | str   |
+| 7      | sample<sub>a</sub> counts            | counts of each base modification in the region, comma-separated, for sample A                              | str   |
+| 8      | sample<sub>a</sub> total             | total number of base modification calls in the region, including unmodified, for sample A                  | int   |
+| 9      | sample<sub>b</sub> counts            | counts of each base modification in the region, comma-separated, for sample B                              | str   |
+| 10     | sample<sub>b</sub> total             | total number of base modification calls in the region, including unmodified, for sample B                  | int   |
+| 11     | sample<sub>a</sub> percents          | percent of calls for each base modification in the region, comma-separated, for sample A                   | str   |
+| 12     | sample<sub>b</sub> percents          | percent of calls for each base modification in the region, comma-separated, for sample B                   | str   |
+| 13     | sample<sub>a</sub> fraction modified | fraction modification (of any kind) in sample A                                                            | float |
+| 14     | sample<sub>b</sub> fraction modified | fraction modification (of any kind) in sample B                                                            | float |
+| 15     | MAP-based p-value          | ratio of the posterior probability of observing the effect size over zero effect size                 | float |
+| 16     | effect size                | percent modified in sample A (col 12) minus percent modified in sample B (col 13)                     | float |
+| 17     | balanced MAP-based p-value | MAP-based p-value when all replicates are balanced                                                    | float |
+| 18     | balanced effect size       | effect size when all replicates are balanced                                                          | float |
 
 ## Segmenting on differential methylation