tame/core/aggregate.xml

<?xml version="1.0"?>
<!--
  Copyright (C) 2018 R-T Specialty, LLC.

  This file is part of tame-core.

  tame-core is free software: you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as
  published by the Free Software Foundation, either version 3 of the
  License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.
-->
<package xmlns="http://www.lovullo.com/rater"
         xmlns:c="http://www.lovullo.com/calc"
         xmlns:t="http://www.lovullo.com/rater/apply-template"
         core="true"
         desc="Aggregating Values">

  <import package="base"          export="true" />
  <import package="vector/cmatch" export="true" />


  Aggregate templates simplify aggregating values through various means.
  Unless otherwise specified,
    the default means of aggregation is summation.


  <section title="Symbol-Based Aggregation">
    For large numbers of values,
      the most convenient way to aggregate is by matching on symbol names.
    Note that symbols must be available for a match to occur.
    All imported symbols are immediately available,
      but \tt{expand-sequence} may need to be used for symbols produced by
      the same package.


    \ref{_aggregate-rate-each_} aggregates values of generators (usually
      referred to by \tt{rate-each}) through summation.
    A \tt{rate-each} block is generated to perform the summation.

    Since \tt{rate-each} multiplies its body by \tt{_CMATCH_},
      zero symbols would normally result in the summation of \tt{_CMATCH_}
      itself, which is not desirable;
        this template always includes \ref{ZERO} in the body to defend
          against this,
            causing a yield of~$0.00$ if there are no symbol matches.

    <template name="_aggregate-rate-each_"
              desc="Aggregate generator values by symbol prefix">
      <param name="@class@"  desc="Iterator class (omit for scalars)" />
      <param name="@prefix@" desc="Symbol prefix" />

      <param name="@yields@" desc="Scalar yield name (optional)">
        <text></text>
      </param>

      <param name="@generates@" desc="Generator name (optional)">
        <text></text>
      </param>


      <rate-each class="@class@" yields="@yields@"
                 generates="@generates@" index="k">
        <c:sum>
          <!-- prevent summing _CMATCH_ if there are no symbols (see above
               comments) -->
          <c:value-of name="ZERO"
                      label="Guard against zero symbol matches" />

          <inline-template>
            <for-each>
              <sym-set name-prefix="@prefix@" type="gen" />
            </for-each>

            <c:value-of name="@sym_name@" index="k" />
          </inline-template>
        </c:sum>
      </rate-each>
    </template>


    \ref{_aggregate-rate_} is analgous to \ref{_aggregate-rate-each_},
      handling only scalar~\tt{@yields@}.
    A \tt{rate} block is generated to aggregate by summation.

    To prevent an empty rate block from being generated if there are no
      symbol matches,
        \ref{ZERO} is always included as part of the summation.

    <template name="_aggregate-rate_"
              desc="Aggregate scalar results by symbol prefix">
      <param name="@prefix@" desc="Symbol prefix" />
      <param name="@yields@" desc="Scalar yield name" />


      <rate yields="@yields@">
        <c:sum>
          <!-- prevent completely empty rate block -->
          <c:value-of name="ZERO"
                      label="Guard against zero symbol matches" />

          <inline-template>
            <for-each>
              <sym-set name-prefix="@prefix@" type="rate" />
            </for-each>

            <c:value-of name="@sym_name@" />
          </inline-template>
        </c:sum>
      </rate>
    </template>


    \ref{_aggregate-classify_} aggregates classifications.
    Keep in mind that classifications act as universal quantifiers by default,
      meaning zero symbol matches will produce a match and a scalar~$1$;
        existential quantifiers (\tt{@any@} set to \tt{true}) will \emph{not}
          match and will produce the scalar~$0$.

    <template name="_aggregate-classify_"
              desc="Aggregate classification results by symbol prefix">
      <param name="@prefix@" desc="Symbol prefix" />
      <param name="@as@"     desc="Classification name" />
      <param name="@desc@"   desc="Generated classification description" />

      <param name="@yields@" desc="Vector yield name (optional)">
        <text></text>
      </param>

      <param name="@any@"
             desc="Existential classification (default false, universal)">
        <text></text>
      </param>


      <classify as="@as@" yields="@yields@" desc="@desc@" any="@any@">
        <inline-template>
          <for-each>
            <sym-set name-prefix="@prefix@" type="class" />
          </for-each>

          <t:match-class name="@sym_name@" />
        </inline-template>
      </classify>
    </template>
  </section>
</package>