[m-rev.] for review: slice and dice documentation

[Julien Fischer]

On Thu, 28 May 2026 at 09:06, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:

> Improve slicing/dicing documentation.
>
> doc/mercury_user_guide.texi:
>     Clarify the documentation of slices and dices, partly by
>     improving exposition, partly by including previously ignored info.
>
>     Link two near-duplicate blocks of text to each other.
>
> mdbcomp/slice_and_dice.m:
>     Replace stringly typed code with strongly typed code:
>     parsing instead of validating.
>
>     Clarify comments.
>
> slice/mslice.m:
>     Conform to the change in slice_and_dice.m.
>
> diff --git a/doc/mercury_user_guide.texi b/doc/mercury_user_guide.texi
> index fa6d4a6cf..b511a6358 100644
> --- a/doc/mercury_user_guide.texi
> +++ b/doc/mercury_user_guide.texi

...

> @@ -6826,69 +6830,91 @@ Six columns are displayed:
>  @item @samp{Procedure}:
>  The procedure in which the goal appears.
>  @item @samp{Path/Port}:
> -The goal path and/or port of the goal.  For atomic goals, statistics about the
> -CALL event and the corresponding EXIT, FAIL or EXCP event are displayed on
> -separate rows.  For other types of goals the goal path is displayed, except for
> -NEGE, NEGS and NEGF events where the goal path and port are displayed.
> +The goal path and/or port of the goal.
> +For atomic goals, statistics about the CALL event
> +and the corresponding EXIT, FAIL or EXCP event
> +are displayed on separate rows.
> +For other types of goals, the displayed text shows the goal path,
> +except for NEGE, NEGS and NEGF events,
> +where it contains both the goal path and the port.
>  @item @samp{File:Line}:
> -The file name and line number of the goal.  This can be used to set a
> -breakpoint on the goal.
> +The file name and line number of the goal.
> +This can be used to set a breakpoint on the goal.
>  @item @samp{Pass (total passing test runs)}:
>  The total number of times the goal was executed in all the passing test runs.
> -This is followed by a number in parentheses which indicates the number of test
> -runs the goal was executed in.  The heading of this column also has a number in
> -parentheses which is the total number of passing test cases.  In the example
> -above we can see that 3 passing tests were run.
> +This is followed by a number in parentheses,
> +which indicates the number of test runs the goal was executed in.
> +The heading of this column also has a number in parentheses,
> +which is the total number of passing test cases.
> +In the example above we can see that three passing tests were run.
>  @item @samp{Fail}:
>  The number of times the goal was executed in the failing test run.
>  @item @samp{Suspicion}:
> -A number between 0 and 1 which gives an indication of how likely a
> -particular goal is to be buggy.
> -This is calculated as Suspicion = F / (P + F) where F is the number of times
> -the goal was executed in the failing test run and P is the number of times the
> -goal was executed in passing test runs.
> +A number between 0 and 1 which gives an indication
> +of how likely a particular goal is to be buggy.
> +This is calculated as Suspicion = Fail / (Pass + Fail), where
> +Fail is the number of times the goal was executed in the failing test run,
> +and Pass is the number of times the goal was executed in passing test runs.
>  @end itemize
>  @sp 1
> -The name of the file containing the failing slice can be specified with the
> - at samp{-f} or @samp{--fail-trace-counts} option or with a separate
> - at samp{set fail_trace_counts @var{filename}} command.
> +The name of the file containing the failing slice
> +can be specified with the @samp{-f} or @samp{--fail-trace-counts} option
> +or with a separate @samp{set fail_trace_counts @var{filename}} command.
>  @sp 1
>  The name of the file containing the union of the passing slices
>  can be given with the @samp{-p} or @samp{--pass-trace-counts} option.
> -Alternatively a separate @samp{set pass_trace_counts @var{filename}} command
> -can be given.  See @ref{Trace counts} for more information about trace counts.
> +Alternatively, users can give
> +a separate @samp{set pass_trace_counts @var{filename}} command

Missing a full stop there.

> +See @ref{Trace counts} for more information about trace counts.
>  @sp 1
> -The table can be sorted on the Pass, Fail or Suspicion columns, or a
> -combination of these.  This can be done with the @samp{-s} or @samp{--sort}
> -option.  The argument of this option is a string made up of any combination of
> -the letters @samp{pPfFsS}.  The letters in the string indicate how the table
> -should be sorted:
> +The table is normally sorted on the identification of the event,
> +meaning it is sorted
> + at itemize @bullet
> + at item first on the identification of the procedure containing the event
> +(consisting of a pred/func indication,
> +the name of the predicate or function, its arity, and its mode number),
> + at item then on the port (if any),
> + at item then on the path (if any),
> + at item then on the file name, and
> + at item then on the line number.
> + at end itemize
> + at sp 1
> +However, users can also ask for it to be sorted
> +on the Pass, Fail and/or Suspicion columns, or on a combination of these.
> +This can be done with the @samp{-s} or @samp{--sort} option.
> +The argument of this option is a nonempty string
> +consisting of any combination of the letters @samp{pPfFdDsS}.
> +The letters in the string indicate how the table should be sorted:
>  @sp 1
>  @itemize @bullet
>  @item @samp{p}: Pass ascending
>  @item @samp{P}: Pass descending
>  @item @samp{f}: Fail ascending
>  @item @samp{F}: Fail descending
> + at item @samp{d}: Difference (Pass minus Fail) ascending
> + at item @samp{D}: Difference (Pass minus Fail) descending
>  @item @samp{s}: Suspicion ascending
>  @item @samp{S}: Suspicion descending
>  @end itemize
>  @sp 1
> -For example, the string "SF" means sort the table by suspicion, descending, and
> -if any two suspicions are the same, then by number of executions in the failing
> -test case, descending.
> - at sp 1
> -The option @samp{-n} or @samp{--top} can be used to limit the number lines
> -displayed.  Only the top @var{num} lines, with respect to
> -the ordering specified by the @samp{-s} option, will be displayed.
> -By default the table is limited to 50 lines.
> - at sp 1
> -If the @samp{-o} or @samp{--output-to-file} option is given then the output
> -will be written to the specified file instead of being displayed on the
> -screen.  Note that the file will be overwritten without warning if it
> -already exists.
> - at sp 1
> -The @samp{-m} or @samp{--module} option limits the output to the given module
> -and its submodules, if any.
> +For example, the string "SF" means sort the table by suspicion, descending,
> +and if any two suspicions are the same,
> +then by number of executions in the failing test case, descending.
> + at sp 1
> +To limit the number sorted lines displayed,

*of* sorted lines

> +users can specify the @samp{-n} option or its @samp{--top} synonym,
> +which take an integer argument;

s/take/takes/

> +this will cause only specified number

*the* specified number

....

> @@ -7991,6 +8018,10 @@ If the argument is zero, there is no maximum width.
> @@ -7999,8 +8030,10 @@ one must first generate a set of trace count files for passing runs
>  and a set of trace count files for failing runs
>  using the @samp{mtc} tool (@ref{Generating trace counts}).
>  Once this has been done,
> -and the union of each set computed using @samp{mtc_union},
> - at samp{mdice} can be used to display a table of statistics
> +and the union of each set
> +(the set of passing runs and the set of failing runs)
> +has been computed using @samp{mtc_union},
> +invoking g at samp{mdice} will display a table of statistics

There's a stray 'g' there.

>  that compares the passing runs to the failing runs.
>  @sp 1
>  Here is an example of the output of the @samp{mdice} tool:

...

> @@ -8043,9 +8077,9 @@ the goal was executed in the failing test run(s).
>  @item @samp{Suspicion}:
>  This columns displays a number between 0 and 1

s/columns/column/

>  which gives an indication of how likely a particular goal is to contain a bug.
> -The suspicion is calculated as Suspicion = F / (P + F)
> -where F is the number of times the goal was executed in failing runs
> -and P is the number of times the goal was executed in passing runs.
> +This number is calculated as Suspicion = Fail / (Pass + Fail)
> +where Fail is the number of times the goal was executed in failing runs
> +and Pass is the number of times the goal was executed in passing runs.
>  @end itemize
>  @sp 1
>  The @samp{mdice} tool is invoked with a command of the form:

...

> diff --git a/mdbcomp/slice_and_dice.m b/mdbcomp/slice_and_dice.m
> index c21160ba8..dc050d6ad 100644
> --- a/mdbcomp/slice_and_dice.m
> +++ b/mdbcomp/slice_and_dice.m
> @@ -56,7 +56,11 @@
>      %
>  :- pred read_slice(string::in, maybe_error(slice)::out, io::di, io::uo) is det.
>
> -    % read_slice_to_string(File, SortStr, MaxRows, MaybeMaxPredColumns,
> +:- type maybe_filter_zero
> +    --->    do_not_filter_zero
> +    ;       do_filter_zero.
> +
> +    % read_slice_to_string(File, Zero, SortStr, MaxRows, MaybeMaxPredColumns,
>      %   MaybeMaxPredColumns, MaybeMaxPathColumns, MaybeMaxFileColumns,
>      %   Module, SliceStr, Problem, !IO):
>      %
> @@ -79,8 +83,8 @@
>      % contain a string describing the problem encountered and SliceStr
>      % will be the empty string, otherwise Problem will be the empty string.
>      %
> -:- pred read_slice_to_string(string::in, string::in, int::in,
> -    maybe(int)::in, maybe(int)::in, maybe(int)::in,
> +:- pred read_slice_to_string(string::in, maybe_filter_zero::in, string::in,
> +    int::in, maybe(int)::in, maybe(int)::in, maybe(int)::in,
>      string::in, string::out, string::out, io::di, io::uo) is det.
>
>  %---------------------------------------------------------------------------%
> @@ -156,25 +160,29 @@
>      maybe(int)::in, maybe(int)::in, maybe(int)::in,
>      string::in, string::out, string::out, io::di, io::uo) is det.
>
> -    % suspicion_ratio(PassCount, FailCount) = Suspicion.
> -    % suspicion_ratio gives an indication of how likely a label is to
> -    % be buggy based on how many times it was executed in passing and
> -    % failing test runs.
> +    % suspicion_ratio(PassCount, FailCount) = Suspicion:
> +    %
> +    % This function gives an indication of how likely a label is to
> +    % be buggy, by considering how many times it was executed in passing
> +    % and in failing test runs.
>      %
>  :- func suspicion_ratio(int, int) = float.
>
>      % suspicion_ratio_normalised(PassCount, PassTests, FailCount, FailTests)
> -    %   = Suspicion.
> -    % suspicion_ratio_normalised gives an indication of how likely a label is
> -    % to be buggy based on how many times it was executed in passing and
> -    % failing test runs and on how many passing and failing test runs there
> -    % were.
> +    %   = Suspicion:
> +    %
> +    % This function return an indication of how likely a label is

s/return/returns/

> +    % to be buggy. It does this by considering how many times it was executed
> +    % in passing and in failing test runs, and how many passing and failing
> +    % test runs there were.
>      %
>  :- func suspicion_ratio_normalised(int, int, int, int) = float.

...


> @@ -754,103 +786,140 @@ dice_label_count_compare(SortStr, LabelCountA, LabelCountB, Result) :-

...

> +dice_exec_count_compare(HeadCmp, TailCmps, ExecCountsA, ExecCountsB, Result) :-
> +    % NOTE: counts compare as integers, while rations compare as floats.

s/rations/ratios/

> +    % Both the counts and ratios are compared in separate ascending and
> +    % descending blocks, which are identical except for the direction
> +    % of the comparison.

That looks fine otherwise.

Julien.