# ClusterCluster

Allows you to analyze clusters in a snapshot that you have taken by using the ClusterSnapshot action. Depending on which parameters you combine the action with, you can:

- generate cluster `WhatsHot` information from a snapshot.

- generate a 2-D or 3-D map of `WhatsHot` cluster information.

- generate `WhatsNew` information by comparing two snapshots of the same name.

- generate `WhatsNew` information by comparing two snapshots that have different names (one of them can be a profile snapshot).

NOTE: This is an administrative action that can be sent only by users that belong to an authorization role that allows the `Admin` standard role, or which enables the action explicitly. See Authorization Roles Configuration Parameters.

When you send the `ClusterCluster` action, it is queued. After it finishes, the results are saved in .CFG files in the `IDOL\category\cluster\CLUSTERS` directory in your IDOL Server installation directory. You can retrieve the results in XML format by using the ClusterResults action.

NOTE: You can select whether to generate `WhatsHot` or `WhatsNew` cluster information by setting the WhatsNew parameter for this action.

If you generate `WhatsHot` cluster information, the `ClusterCluster` action analyzes the clusters in the most recent snapshot that is available within the time span defined by one or more of the StartDate, EndDate, and Interval parameters.

If you generate `WhatsNew` cluster information, the `ClusterCluster` action compares the oldest and the most recent snapshots that are available within the time span defined by one or more of the StartDate, EndDate, and Interval parameters.

## Example

    http://12.3.4.56:9000/action=ClusterCluster&SourceJobName=Job1&TargetJobName=Job1a&StartDate=1000290000

This action analyzes clusters in a snapshot called `Job1` that was generated on `September 12 2001` at `11:20:00` (or before if no snapshot is available for this date).

    http://12.3.4.56:9000/action=ClusterCluster&SourceJobName=Job1&TargetJobName=Job1a&WhatsNew=True&StartDate=1000290000&EndDate=1000300000

This action compares clusters in a snapshot called `Job1` that was generated on `September 12 2001` at `11:20:00` with a snapshot called `Job1` that was generated on `September 12 2001` at `14:06:40` (if no snapshots are available for the specified dates, IDOL Server uses the snapshots that were generated before the specified dates).

## Required Parameters

The following action parameters are required.

Parameter | Description
--- | ---
SourceJobName | The snapshot to generate cluster information from.
TargetJobName | The name of the cluster to generate.

NOTE: Additional parameters are required when you want to create a `WhatsNew` cluster. See Comments

## Optional Parameters

This action accepts the following optional parameters.

Parameter | Description
--- | ---
BindLevel | The conceptual similarity of clusters.
Cluster | The IDs of one or more clusters that you want to re-cluster, when you set FocusJobName.
Cluster3D | Used in conjunction with DoMapping, generates a 3-D cluster map.
Cycles | The number of times to run the action.
Dependencies | A list of classification schedules that must be complete before the `ClusterCluster` action can run.
DoMapping | Whether to generate a 2-D map of the clusters that the action produces.
EndDate | The time span for which to generate `WhatsHot` or `WhatsNew` information.
FocusJobName | The name of a clustering job that contains one or more clusters that you want to re-cluster.
FocusStrength | The strength of focusing, when you set FocusJobName.
IncludeTerms | Whether term information returns with a cluster.
Interval | The time span for which to generate `WhatsHot` or `WhatsNew` information.
MapPalette | The color scheme to use for the 2-D map.
MapSize | The pixel height and width of the 2-D map to generate.
NegativeClusters | One or more existing clusters to bias the new clustering away from, when you set RefineJobName.
NegativeTerms | One or more terms to bias the new clustering away from, when you set RefineJobName.
NumClusters | The maximum number of clusters to identify.
PositiveClusters | One or more existing clusters to bias the new clustering toward, when you set RefineJobName.
PositiveTerms | One or more terms to bias the new clustering toward, when you set RefineJobName.
ProfileSourceJobName | A profile snapshot used to generate `WhatsNew` cluster information.
RefineJobName | The name of a clustering job that you want to re-cluster, biasing toward or against certain terms or clusters.
RefineStrength | How strongly or weakly to apply the refinement, when you set RefineJobName.
Repeat | The time to elapse between runs of the action.
Retries | The number of times to retry a failed action.
RetryInterval | The number of seconds to wait before retrying a failed action.
SourceJobName2 | The second snapshot to use to generate `WhatsNew` cluster information.
StartDate | The time span for which to generate `WhatsHot` or `WhatsNew` information.
StartTime | The time to run the first action.
SummaryField | The field that contains a result summary.
Username | The name of the user performing the action.
WhatsNew | Whether to perform a `WhatsNew` comparison of snapshots.
XMLEncoding | Overrides the default XML encoding.

This action accepts the following standard ACI action parameters.

Parameter | Description
--- | ---
ActionID | A string to use to identify an ACI action.
EncryptResponse | Encrypt the output.
FileName | The file to write output to.
ForceTemplateRefresh | Forces the server to load the template from disk.
Output | Writes output to a file.
ResponseFormat | The format of the action output.
Template | The template to use for the action output.
TemplateParamCSVs | A list of variables to use for the specified template.

## Comments

The following table describes the parameters that are required and optional when you want to create a `WhatsHot` or `WhatsNew` cluster.

| WhatsHot | WhatsNew
Required | SourceJobName TargetJobName | SourceJobName StartDate TargetJobName WhatsNew
Optional | BindLevel Cluster3D DoMapping IncludeTerms Interval NumClusters RankSections StartDate XMLEncoding | BindLevel IncludeTerms NumClusters RankSections SourceJobName2 XMLEncoding

_FT_HTML5_bannerTitle.htm