Package qupath.lib.objects.classes

Class PathClass

java.lang.Object
qupath.lib.objects.classes.PathClass
All Implemented Interfaces:
Serializable, Comparable<PathClass>
public final class PathClass extends Object implements Comparable<PathClass>, Serializable
Representation of an object's classification - which can be defined using any unique string identifier (e.g. tumour, lymphocyte, gland, benign, malignant).

The constructors in this class should never be called directly, because there should only ever be one instance of each classification - shared among all objects with that classification. This is important for checking if classifications are identical, and also assigning colors to them for display.

To achieve this, be sure to use one of the getInstance() or fromXXX() methods each time you want to access or create a new PathClass instance.

This class has been with QuPath since the beginning, but was thoroughly revised for v0.4.0 to simplify the code, improve the validation, and make it easier to use.

See Also:

  • Field Details

    • NAME_POSITIVE

      public static final String NAME_POSITIVE
      Default name for a class representing "Positive" staining intensity
      See Also:

    • NAME_NEGATIVE

      public static final String NAME_NEGATIVE
      Default name for a class representing "Negative" staining intensity
      See Also:

    • NAME_ONE_PLUS

      public static final String NAME_ONE_PLUS
      Default name for a class representing "1+" staining intensity (i.e. weakly positive)
      See Also:

    • NAME_TWO_PLUS

      public static final String NAME_TWO_PLUS
      Default name for a class representing "2+" staining intensity (i.e. moderately positive)
      See Also:

    • NAME_THREE_PLUS

      public static final String NAME_THREE_PLUS
      Default name for a class representing "3+" staining intensity (i.e. strongly positive)
      See Also:

    • DELIMITER

      public static final String DELIMITER
      Get the delimiter to use between names of the PathClass when converting to a string.

    • NULL_CLASS

      public static final PathClass NULL_CLASS
      Default PathClass that represents no classification. Usually no classification is represented by null, so this is not normally needed; however, sometimes it is required in contexts where a null is not permitted (e.g. some collections).

  • Method Details

    • getParentClass

      public PathClass getParentClass()
      Get the parent classification, or null if this classification has no parent.
      Returns:

    • isDerivedClass

      public boolean isDerivedClass()
      Returns true if #getParentClass() != null.
      Returns:

    • isDerivedFrom

      public boolean isDerivedFrom(PathClass parentClass)
      Returns true if this class, or any ancestor class, is equal to the specified parent class.
      Parameters:
      parentClass -
      Returns:

    • isAncestorOf

      public boolean isAncestorOf(PathClass childClass)
      Returns true if this class is equal to the specified child class, or an ancestor of that class.
      Parameters:
      childClass -
      Returns:

    • getBaseClass

      public PathClass getBaseClass()
      Get the 'base' class, i.e. trace back through getParentClass() until no parent is available.

      For a PathClass with no parent, this just returns itself.

      Returns:

    • setColor

      public void setColor(Integer colorRGB)
      Set the color that should be used to display objects with this classification.
      Parameters:
      colorRGB - color, as a packed (A)RGB value

    • setColor

      public void setColor(int red, int green, int blue)
      Set the color as 8-bit RGB values
      Parameters:
      red -
      green -
      blue -
      Since:
      v0.4.0

    • getColor

      public Integer getColor()
      Get the color that should be used to display objects with this classification.
      Returns:
      packed (A)RGB value representing the classification color.

    • getName

      public String getName()
      Get the name of this classification. Note that this does not incorporate information from any parent classifications; to access this, use toString() instead.
      Returns:

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toString

      public String toString(String delimiter)
      Create a string representation, using the specified delimiter between elements of derived PathClasses.
      Parameters:
      delimiter -
      Returns:

    • isValid

      public boolean isValid()
      A PathClass is valid if its name is not null.

      This should generally the case, but a single (invalid) PathClass with a null name can be used to indicate the absence of a classification; however, it should not be assigned to any object. Rather, objects should be assigned either a valid PathClass or null to indicate that they have no classification.

      Returns:

    • toSet

      public Set<String> toSet()
      Return a view of this path class as an unmodifiable set, with each element representing the name of a path class component names.

      Important! If any path class component names are duplicates, these will (necessarily) be removed from the set. Therefore it is not guaranteed that calling fromCollection(Collection) on the output will return the same PathClass object. 

      
 var pathClass = ...;
 var pathClass2 = PathClass.getInstance(pathClass.toSet());
 assert pathClass == pathClass2; // This may or may not be true!

      However the PathClass objects should be the same if the name components are all valid and there are no duplicates (which should normally be the case).

      Returns:

    • compareTo

      public int compareTo(PathClass o)
      This is now equivalent to this.toString().compareTo(o.toString()).

      Note that in previous versions (< 0.1.2), the comparison was made based on the name only.

      This could result in unexpected behavior whenever comparing with equality and using derived PathClass objects, because only the (final) name part was being compared and this could potentially result in classifications (wrongly) being considered equal (e.g. "Tumor: Positive" and "Stroma: Positive").

      This was most significant when working with Groovy, where == is replaced by compareTo.

      Specified by:
      compareTo in interface Comparable<PathClass>

    • getNullClass

      public static PathClass getNullClass()
      Get the value of NULL_CLASS, used to represent no classification. In most cases, null should be used instead; this exists only as a representation in cases where null is not permitted (e.g. in some collection implementations).
      Returns:

    • fromString

      public static PathClass fromString(String string)
      Get a PathClass instance from a string representation, without specifying a default color.

      This calls fromString(String, Integer) with the second argument as null.

      Parameters:
      string -
      Returns:

    • fromString

      public static PathClass fromString(String string, Integer color)
      Get a PathClass instance from a string representation, optionally providing a default color if a new instance needs to be created.

      This ultimately calls getInstance(PathClass, String, Integer) but differs in that it accepts a string representation that may include the DELIMITER. If so, this is used to split the string into different name components that are passed to fromCollection(Collection, Integer).

      Parameters:
      string - a string representation containing one or more name elements, separated by DELIMITER
      color - a default color (optional, may be null)
      Returns:

    • fromCollection

      public static PathClass fromCollection(Collection<String> names)
      Get a PathClass using all the name elements specified in the collection, without providing a default color.
      Parameters:
      names -
      Returns:
      See Also:

    • fromCollection

      public static PathClass fromCollection(Collection<String> names, Integer color)
      Get a PathClass instance using all the name elements specified in the collection, with optional default color if a new instance is created. The rules are:
      • If the collection is empty, NULL_CLASS is returned
      • If the collection has one element, this is equivalent to calling getInstance(String, Integer)
      • If the collection has multiple element, this is equivalent to creating a base class from the first element and deriving subclassifications by calling getInstance(PathClass, String, Integer) for each element, in the order returned by the collection's iterator
      Parameters:
      names -
      color -
      Returns:
      See Also:

    • getInstance

      public static PathClass getInstance(String name)

    • getInstance

      public static PathClass getInstance(String name, Integer color)
      Get a base PathClass instance, without any parent PathClass.

      This is equivalent to calling getInstance(PathClass, String, Integer) with the first argument as null.

      Parameters:
      name -
      color -
      Returns:
      See Also:

    • getInstance

      public static PathClass getInstance(PathClass parent, String name, Integer color)
      Get a derived PathClass instance with the specified parent.

      This will be derived from the parent PathClass (if provided) and have the specified name, stripped to remove any leading or training whitespace.

      Note that the name should generally be an alphanumeric string, optionally including punctuation symbols but not including DELIMITER.

      The delimiter is currently a colon ":" but it is advised not to rely upon this and to avoid punctuation where possible, because the delimiter may possibly change in a future release - primarily because the choice of colon can be problematic in some cases, e.g. when using ontologies.

      Parameters:
      parent - parent class (optional, may be null)
      name - name of the PathClass
      color - color to use if a new instance is created (may be null to use the default)
      Returns:
      a PathClass instance; the same instance will be returned given the same parent and name
      See Also:
      Implementation Requirements
      the color is only used if a new PathClass instance needs to be created. If a suitable instance has already been created, then that will be returned instead and the color will not be created.

    • getOnePlus

      public static PathClass getOnePlus(PathClass parentClass)
      Get a standalone or derived 1+ classification, indicating weak positivity
      Parameters:
      parentClass - parent classification (may be null)
      Returns:

    • getTwoPlus

      public static PathClass getTwoPlus(PathClass parentClass)
      Get a standalone or derived 2+ classification, indicating moderate positivity
      Parameters:
      parentClass - parent classification (may be null)
      Returns:

    • getThreePlus

      public static PathClass getThreePlus(PathClass parentClass)
      Get a standalone or derived 3+ classification, indicating strong positivity
      Parameters:
      parentClass - parent classification (may be null)
      Returns:

    • getNegative

      public static PathClass getNegative(PathClass parentClass)
      Get a standalone or derived Negative classification
      Parameters:
      parentClass - parent classification (may be null)
      Returns:

    • getPositive

      public static PathClass getPositive(PathClass parentClass)
      Get a standalone or derived Positive classification
      Parameters:
      parentClass - parent classification (may be null)
      Returns:

    • getSingleton

      public static PathClass getSingleton(PathClass pathClass)
      Get the singleton PathClass that is equivalent to the PathClass provided.

      This is important because there should only ever be one PathClass instance for any classification - and accessing PathClasses only via the getInstance() methods here should ensure that.

      However, if receiving a PathClass from some other source then it is possible that the PathClass was created some other way and duplicates could emerge. Calling this method returns resolves that problem by returning the single instance that should be used.

      This is significant if the PathClass has been created via Java deserialization, which skips the required use of getInstance() by default.

      Parameters:
      pathClass -
      Returns:
      either the input PathClass, or an equivalent that should be used

    • fromArray

      public static PathClass fromArray(String... names)
      Get a PathClass from an array of individual names.
      Parameters:
      names -
      Returns:
      See Also:

    • readResolve

      protected Object readResolve() throws ObjectStreamException
      Called during deserialization to ensure that only a single instance of each PathClass exists. Partly addresses https://github.com/qupath/qupath/issues/1306 (during standard deserialation, but not from JSON)
      Returns:
      Throws:
      ObjectStreamException