Sample Annotations Panel

Sample Annotations Panel

The Sample Annotations panel allows users to create, manage, and apply custom annotations to selected samples. Annotations can be used to organize samples into biologically meaningful groups, label experimental conditions, identify clusters of interest, or capture observations made during exploratory data analysis.

This functionality becomes available after adding Custom Annotations from the Enrich modifier in the Sample Selection panel. Annotations may be assigned manually or generated automatically using clustering algorithms.

Sample Annotations panel

Overview

The panel displays the number of currently selected samples and provides tools for creating, editing, duplicating, and saving annotation sets.

  1. Selected samples: The banner at the top of the panel indicates how many samples are currently selected out of the total number of loaded samples. Refer to Cluster plot navigation in the Plot Navigation Panel documentation for a detailed explanation on how to navigate the plot such as selecting the samples, etc.

    Sample Annotations: Sample count

    Note:Any annotation action performed in the panel applies only to the currently selected samples.

  2. Existing annotation key: The Existing annotation key dropdown lists all annotation categories currently available for the loaded samples.

    Examples include:

    • Replicate_Treatment
    • CellType
    • Mode_of_action
    • Batch

    Selecting an existing annotation key loads its current annotations for review or modification.

    Existing annotation key

    Two management options are available here:

    • Delete Removes the selected annotation key. Changes become permanent only after saving.
    • Duplicate Creates a copy of the selected annotation key, allowing modification without altering the original annotations.

    Note:Changes made to annotation keys are stored permanently only after clicking Save annotation permanently

  3. Creating a new annotation key: The Annotation key field is used to create a new annotation category.

    Creating a new annotation key

    Examples:

    • Treatment_group
    • Cell_type
    • Response_status
    • Disease_stage

    Please note that Annotation keys must follow standard naming conventions:

    • No spaces
    • No special characters
    • No leading digits
    • No leading or trailing underscores (_) or hyphens (-)
    • Reserved characters such as ', ", [, ], (, ) and similar symbols are not allowed

    Valid examples include:

    • TreatmentGroup
    • CellType
    • DrugResponse

    Invalid examples are:

    • 1Treatment
    • _Treatment
    • Treatment-
    • Cell Type

  4. PanHunter allows users to apply annotations in two ways:

    • Manual annotation: When Automated clustering is disabled, annotations are assigned manually. The Annotation value field specifies the label that will be applied to all currently selected samples.

      Manual annotation

      Examples:

      • MTOR_inhibitor
      • Responder
      • Cluster_A
      • Disease

      After entering a value:

      1. Select the desired samples.
      2. Enter the annotation value.
      3. Click Set current annotation.

    • Automated clustering: The Automated clustering option can automatically generate annotation labels based on sample similarity.

      Automated clustering

      When enabled, samples are grouped into clusters using the selected clustering method and clustering space.

      This is particularly useful for:

      • Exploratory data analysis
      • Identifying sample subgroups
      • Detecting hidden sample structure
      • Generating preliminary sample classifications

      • Clustering space: The Clustering space defines which coordinates or features are used for clustering.

        Available options include:

        • Current 2D plot: Uses coordinates from the currently displayed dimensionality reduction plot.
        • Selected top features: Uses only the selected high-variance features.
        • Complete feature set: Uses all available features for clustering.

        Note: The choice of clustering space can substantially influence the resulting cluster assignments.

      • Clustering method: The Clustering method specifies the algorithm used to group samples.

        Currently available methods include:

        • K-means: Partitions samples into a predefined number of clusters by minimizing within-cluster variance.

          Suitable for:

          • Compact sample groups
          • Exploratory analyses
          • Fast clustering of large datasets

        • Hierarchical clustering: Builds a hierarchical relationship between samples using distance metrics and linkage criteria.

          Suitable for:

          • Identifying nested sample relationships
          • Visualizing sample similarity structures
          • Smaller datasets

      • Number of clusters: The Number of clusters parameter determines how many clusters will be generated.

        Requirements:

        • Integer value
        • Minimum: 2
        • Maximum: approximately half of the total number of samples

  5. Saving annotations

    Saving annotations

    • Set current annotation Applies the current manual or clustering-based annotation to the selected samples.
    • Save annotation permanently Stores annotation changes in the project database so they remain available after reloading the session.