<apidoc:module name="ClustererBuiltins" category="SearchBuiltins" subcategory="Search Clustering" lib="cts" xmlns:apidoc="http://marklogic.com/xdmp/apidoc"><apidoc:summary access="public">
<p xmlns="http://www.w3.org/1999/xhtml">The clusterer built-in functions perform dynamic clustering of nodes. 
The result clusters are represented in XML. The clusterer APIs and the XML output
from <code><a href="#cts:cluster">cts:cluster</a></code> conform to the 
<code>clusterer.xsd</code> schema, located in the Config directory 
under the directory in which MarkLogic Server is installed.</p>

</apidoc:summary><apidoc:function name="cluster" type="builtin" lib="cts" category="SearchBuiltins" subcategory="Search Clustering" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Produces a set of clusters from a sequence of nodes.  The nodes can be
  any set of nodes, and are typically the result of a <code xmlns="http://www.w3.org/1999/xhtml">cts:search</code>
  operation.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="nodes" type="node()*" optional="false">
    The sequence of nodes to cluster.
  </apidoc:param>
      <apidoc:param name="options" type="element()?" optional="true">
    An XML representation of the options for defining the clustering 
    parameters. The options node must be in the <code xmlns="http://www.w3.org/1999/xhtml">cts:cluster</code>
    namespace. The following is a sample options node:
    <pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
    &lt;options xmlns="cts:cluster"&gt;
      &lt;label-max-terms&gt;4&lt;/label-max-terms&gt;
      &lt;max-clusters&gt;6&lt;/max-clusters&gt;
      &lt;use-db-config&gt;true&lt;/use-db-config&gt;
    &lt;/options&gt; </pre>

    <!-- Not documented on purpose: 
         initialization, k-threshold, score -->
    <p xmlns="http://www.w3.org/1999/xhtml">The <code>cts:cluster</code> options include:</p>
    <pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
       &lt;xs:element ref="opt:overlapping"/&gt;
       &lt;xs:element ref="opt:max-terms"/&gt;
    </pre>
    <dl xmlns="http://www.w3.org/1999/xhtml">
    <dt><p>&lt;<code>hierarchical-levels</code>&gt;</p></dt>
    <dd>An integer specifying how many hierarchical cluster levels the clusterer
    should return. The default is <code>1</code>, which means no hierarchical
    clusters are returned.</dd>
    <dt><p>&lt;<code>label-max-terms</code>&gt;</p></dt>
    <dd>An integer specifying the maximum number of terms to use in constructing
    a cluster label.  The default is <code>3</code>.</dd>
    <dt><p>&lt;<code>label-ignore-words</code>&gt;</p></dt>
    <dd>A space-separated list of words that are to be excluded from cluster
    label.  The default is to not exclude any words.</dd>
    <dt><p>&lt;<code>details</code>&gt;</p></dt>
    <dd>A boolean that indicates whether additional details on the terms
    used in label generation are to be included in the output.  See the 
    documentation on cts:distinctive-terms for details on the format of the
    terms returned.  The default <code>false</code>, meaning no such details
    are given.</dd>
    <dt><p>&lt;<code>min-clusters</code>&gt;</p></dt>
    <dd>An integer specifying a minimum number of desired clusters returned
    (at any hierarchical level).
    However, if no satisfactory clustering can be produced at a given level, 
    only one cluster will be returned, regardless of this setting.  
    The default is <code>3</code>.
    </dd>
    <dt><p>&lt;<code>max-clusters</code>&gt;</p></dt>
    <dd>An integer specifying a maximum number of clusters that can be returned
    (at any hierarchical level). The default is <code>15</code>.
    </dd>
    <dt><p>&lt;<code>overlapping</code>&gt;</p></dt>
    <dd>A boolean indicating whether it is acceptable for nodes to be
    assigned to more than one cluster.  The default is <code>false</code>.
    </dd>
    <dt><p>&lt;<code>max-terms</code>&gt;</p></dt>
    <dd>An integer value specifying the maximum number of distinct terms to
    use in calculating the cluster. The default is <code>200</code>.  
    Increasing the value will increase the cost (in terms of both time 
    and memory) of calculating the clusters, but may improve the quality 
    of the clusters.</dd>
    <dt><p>&lt;<code>algorithm</code>&gt;</p></dt>
    <dd>A value indicating which clustering algorithm to use, either
    <code>k-means</code> or <code>lsi</code>. The default is 
    <code>k-means</code>.  The LSI algorithm is significantly more expensive
    to compute, both in terms of time and space.
    </dd>
    <dt><p>&lt;<code>num-tries</code>&gt;</p></dt>
    <dd>Specifies the number of times to run the clusterer against 
    the specified data. The default is 1. 
    Because of the way the algorithms work, running 
    the cluster multiple times will increase the number of terms, and 
    tends to improve the accuratacy of the clusters. It does so at the 
    cost of performance, as each time it runs, it has to do more work.
    </dd>
    <dt><p>&lt;<code>use-db-config</code>&gt;</p></dt>
    <dd>A boolean value indicating whether to use the current DB configuration 
    for determining which terms to use.  The default is <code>false</code>,
    which means that the default set of options, as well as any indexing 
    options you specify in the options node, will be 
    used for calculating the clusters and their labels. When set to 
    <code>true</code>, any indexing options set in the context database 
    configuration (including any field settings) are used, as well as any 
    default settings that you have not explicitly turned off in the options
    node.
    </dd>
    </dl>
    <p xmlns="http://www.w3.org/1999/xhtml">The options element also includes indexing options in the 
    <code>http://marklogic.com/xdmp/database</code> namespace.  
    These control which terms to use. Note that the use of certain 
    options, such as <code>fast-case-sensitive-searches</code>, will not 
    impact final results unless the term vector size is limited with 
    the <code>max-terms</code> option.  Other options, such as 
    <code>phrase-throughs</code>, will only generate terms if some 
    other option is also enabled (in this case 
    <code>fast-phrase-searches</code>). </p>
    <p xmlns="http://www.w3.org/1999/xhtml">The database options are the same as the database options shown for
    <a href="cts:distinctive-terms#db-term-options">
    <code>cts:distinctive-terms</code></a>.</p>

  </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(cts:clustering)</apidoc:return>
    <apidoc:example><a id="clusterEx1" xmlns="http://www.w3.org/1999/xhtml"></a><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">

cts:cluster(
  cts:search(//MILITARY, cts:word-query("apache"))[1 to 100],
  &lt;options xmlns="cts:cluster" xmlns:db="http://marklogic.com/xdmp/database"&gt;
    &lt;hierarchical-levels&gt;2&lt;/hierarchical-levels&gt;
    &lt;overlapping&gt;false&lt;/overlapping&gt;
    &lt;label-max-terms&gt;3&lt;/label-max-terms&gt;
    &lt;max-clusters&gt;100&lt;/max-clusters&gt;
    &lt;label-ignore-words&gt;of the on in at a an for from by and&lt;/label-ignore-words&gt;
    &lt;db:stemmed-searches&gt;advanced&lt;/db:stemmed-searches&gt;
    &lt;db:fast-phrase-searches&gt;true&lt;/db:fast-phrase-searches&gt;
    &lt;db:fast-element-word-searches&gt;true&lt;/db:fast-element-word-searches&gt;
    &lt;db:fast-element-phrase-searches&gt;true&lt;/db:fast-element-phrase-searches&gt;
  &lt;/options&gt;)
==&gt;
 &lt;clustering xmlns="http://marklogic.com/cts"&gt;
  &lt;cluster id="123456" label="apache helicopters" count="7" nodes="3 34 31 98 34 23 39"/&gt;
  &lt;cluster id="374632" label="apache linux" count="6" nodes="1 378 56 23 93 6"/&gt;
  &lt;cluster id="3452231" label="navajo codetalkers" count="8" nodes="44 87 32 77 50 12 13 15"/&gt;
  ...
  &lt;cluster id="2234" parent="123456" label="AH-64" count="2" nodes="3 39"/&gt;
  &lt;cluster id="34321" parent="123456" label="air force" count="5" nodes="34 31 98 34 23"/&gt;
  &lt;cluster id="34523" parent="374632" label="HTTP" count="3" nodes="1 56 23"/&gt;
  &lt;cluster id="968" parent="374632" label="LAMP" count="3" nodes="378 93 6"/&gt;
  &lt;options xmlns="cts:cluster" xmlns:db="http://marklogic.com/xdmp/database"&gt;
    &lt;algorithm&gt;k-means&lt;/algorithm&gt;
    &lt;db:stemmed-searches&gt;advanced&lt;/db:stemmed-searches&gt;
    &lt;db:fast-element-word-searches&gt;true&lt;/db:fast-element-word-searches&gt;
    &lt;db:fast-element-phrase-searches&gt;true&lt;/db:fast-element-phrase-searches&gt;
    &lt;db:language&gt;en&lt;/db:language&gt;
    &lt;max-clusters&gt;100&lt;/max-clusters&gt;
    &lt;min-clusters&gt;2&lt;/min-clusters&gt;
    &lt;hierarchical-levels&gt;2&lt;/hierarchical-levels&gt;
    &lt;initialization&gt;smart&lt;/initialization&gt;
    &lt;label-max-terms&gt;3&lt;/label-max-terms&gt;
    &lt;num-tries&gt;1&lt;/num-tries&gt;
    &lt;score&gt;logtfidf&lt;/score&gt;
    &lt;use-db-config&gt;false&lt;/use-db-config&gt;
  &lt;/options&gt;
&lt;/clustering&gt;

</pre></apidoc:example>
    <apidoc:example><a id="clusterEx2" xmlns="http://www.w3.org/1999/xhtml"></a><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
cts:cluster(
   cts:search(//function, "foo"),
   &lt;options xmlns="cts:cluster"&gt;
     &lt;use-db-config&gt;true&lt;/use-db-config&gt;
   &lt;/options&gt;)
=&gt; The cts:clustering element

</pre></apidoc:example>
  </apidoc:function></apidoc:module>