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    
011    package com.chemaxon.descriptors.metrics;
012    
013    import com.chemaxon.common.annotations.PublicAPI;
014    import com.google.common.annotations.Beta;
015    import java.io.Serializable;
016    
017    /**
018     * Basic functionality for finite binary vector based calculations.
019     *
020     * <p>Please note that this interface is marked with @Beta annotation, so it can be subject of incompatible changes or
021     * removal in later releases.</p>
022     *
023     * @author Gabor Imre
024     */
025    @Beta
026    @PublicAPI
027    public interface BinaryVectorComparator extends MetricMetadata, Serializable {
028    
029        /**
030         * Calculate represented dissimilarity score from binary vector parameters.
031         *
032         * @param bitCount      Length of binary vectors in bits
033         * @param targetOnly    Number of bit positions where only target contains set bits
034         * @param queryOnly     Number of bit positions where only query contains set bits
035         * @param common        Number of bit positions where both query and target contains set bits
036         * @return              Dissimilarity score
037         */
038        double calculateBinaryVectorDissimilarity(int bitCount, int targetOnly, int queryOnly, int common);
039    
040        /**
041         * Calculate represented similarity score from binary vector parameters.
042         *
043         * @param bitCount      Length of binary vectors in bits
044         * @param targetOnly    Number of bit positions where only target contains set bits
045         * @param queryOnly     Number of bit positions where only query contains set bits
046         * @param common        Number of bit positions where both query and target contains set bits
047         * @return              Ssimilarity score
048         */
049        double calculateBinaryVectorSimilarity(int bitCount, int targetOnly, int queryOnly, int common);
050    
051        /**
052         * Possible lowest value of similarity/dissimilarity scores.
053         * @param bitCount  Length of binary vectors in bits
054         * @return          Possible lowest value of similarity/dissimilarity scores
055         */
056        double getLowerBoundForBinaryVectors(int bitCount);
057    
058        /**
059         * Possible highest value of similarity/dissimilarity scores.
060         * @param bitCount  Length of binary vectors in bits
061         * @return          Possible highest value of similarity/dissimilarity scores
062         */
063        double getUpperBoundForBinaryVectors(int bitCount);
064    
065        /**
066         * Simple consistency check utility.
067         */
068        @Beta
069        public static class Util {
070            /**
071             * Check that descriptor comparison parameters are consistent.
072             *
073             * @param bitCount      Descriptor size
074             * @param targetOnly    Count of positions set in the target side only
075             * @param queryOnly     Count of positions set in the query side only
076             * @param common        Count of positions set both in the query and target side
077             * @throws IllegalArgumentException  When the four given counts are inconsistent or invalid
078             */
079            public static void checkBitCounts(int bitCount, int targetOnly, int queryOnly, int common)
080                throws IllegalArgumentException {
081                if (bitCount <= 0) {
082                    throw new IllegalArgumentException("size (" + bitCount + ") must be positive");
083                }
084                if (targetOnly < 0) {
085                    throw new IllegalArgumentException("targetOnly (" + targetOnly + ") must be nonnegative");
086                }
087                if (queryOnly < 0) {
088                    throw new IllegalArgumentException("queryOnly (" + queryOnly + ") must be nonnegative");
089                }
090                if (common < 0) {
091                    throw new IllegalArgumentException("common (" + common + ") must be nonnegative");
092                }
093                if (bitCount < targetOnly + queryOnly + common) {
094                    throw new IllegalArgumentException(
095                            "bitCount (" + bitCount + ") must be greater or equal than the sum of "
096                            + "targetOnly (" + targetOnly + "), "
097                            + "queryOnly (" + queryOnly + ") and "
098                            + "common (" + common + ")");
099                }
100            }
101        }
102    }