001    /*
002     * Copyright (c) 1998-2014 ChemAxon Ltd. All Rights Reserved.
003     *
004     * This software is the confidential and proprietary information of
005     * ChemAxon. You shall not disclose such Confidential Information
006     * and shall use it only in accordance with the terms of the agreements
007     * you entered into with ChemAxon.
008     *
009     */
010    package com.chemaxon.clustering.common;
011    
012    import com.chemaxon.common.annotations.PublicAPI;
013    import com.google.common.annotations.Beta;
014    import com.google.common.base.Optional;
015    import java.util.List;
016    
017    /**
018     * A grouping of structures into disjunct hierarchical groups.
019     *
020     * <p>Instances of this interface represent unbalanced multifurcating trees.</p>
021     *
022     * @param <C> Type of clusters represented
023     * @param <T> Type of items contained by the clusters
024     *
025     * <p>Please note that this interface is marked with @Beta annotation, so it can be subject of incompatible changes or
026     * removal in later releases.</p>
027     *
028     * @author Gabor Imre
029     */
030    @Beta
031    @PublicAPI
032    public interface HierarchicClustering<T, C extends HierarchicCluster<T>> {
033        /**
034         * Highest level cluster(s).
035         *
036         * @return   List of highest level clusters. The returned list contains at least one element.
037         */
038        List<C> roots();
039    
040        /**
041         * Identify the lowest level cluster containing the given item.
042         *
043         * @param item  Item to look up.
044         * @return      The lowest level cluster containing the given element. This cluster contains the given item as a
045         *              leaf.
046         */
047        Optional<C> clusterOf(T item);
048    
049        /**
050         * Preferred alignment of the represented clustering.
051         *
052         * @return      Preferred alignment
053         */
054        Alignment preferredAlignment();
055    
056        /**
057         * Assigner which consider parent-child edges as unit length.
058         *
059         * @return  The unit path assigner.
060         */
061        LevelAssigner<T, C> unitPathAssigner();
062    
063        /**
064         * Preferred assigner.
065         *
066         * <p>Some clustering algorithms may assign meaningful levels for clusters/leaves. If no such assignment s done the
067         * implementations should fall back the unit path assigner.</p>
068         *
069         * @return  The preferred assigner
070         */
071        LevelAssigner<T, C> getPreferredAssigner();
072    
073        /**
074         * Level interpretation.
075         */
076        @Beta
077        enum Alignment {
078            /**
079             * Roots are aligned to level 0, level increases towards leaves.
080             */
081            ROOT_ALIGNED,
082    
083            /**
084             * Leaves are aligned to level 0, level increases towards roots.
085             */
086            LEAF_ALIGNED;
087        }
088    }