de.citec.tcs.alignment.AlignmentAlgorithm Maven / Gradle / Ivy

Go to download
/* 
 * TCS Alignment Toolbox Version 3
 * 
 * Copyright (C) 2016
 * Benjamin Paaßen
 * AG Theoretical Computer Science
 * Centre of Excellence Cognitive Interaction Technology (CITEC)
 * University of Bielefeld
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 * 
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see .
 */

package de.citec.tcs.alignment;

import de.citec.tcs.alignment.comparators.Comparator;
import de.citec.tcs.alignment.comparators.OperationType;
import java.util.List;
import lombok.NonNull;

/**
 * This is the most generic AlignmentAlgorithm interface for all algorithms that provide some sort
 * of alignment between two input sequences.
 *
 * In general, it is assumed that, given a Comparator d, an AlignmentAlgorithm computes a proper
 * dissimilarity on the input sequences. Formally speaking, this means the following.
 *
 * Let X and Y be sets, corresponding to the generic type parameters of this interface, and let
 * x ∈ X* and y ∈ Y*, where * is the Kleene-Star. Then we expect that this
 * AlignmentAlgorithm computes a dissimilarity D on X* x Y*, defined as:
 * 
 * D(x,y) ≥ 0 (non-negativity)
 * x = y ⇒ D(x, y) = 0 (equality)
 * 
 * Further, this AlignmentAlgorithm should guarantee metric properties under the condition
 * that the given Comparator d fulfills them. In detail the following properties should carry over:
 * 
 * D(x,y) = D(y,x) (symmetry)
 * x ≠ y ⇒ D(x,y) > 0
 * D(x, z) ≤ D(x, y) + D(y, z) (triangular inequality)
 * 
 *
 * Further, we require that a normalization constraint holds as well:
 * D(x, y) ≤ 1
 * This is the case because we want AlignmentAlgorithms to be comparable. If one exchanges a
 * AlignmentAlgorithm with another, the distances should stay in the same range. This normalization
 * constraint can typically be achieved by dividing the raw cost returned by the AlignmentAlgorithm
 * by the maximum of the two input sequence lengths.
 *
 * Some example implementations of this interface can be found in the algorithms-lib module.
 * It is recommended to use the adp module, if you want to devise your own implementations, as it
 * provides a robust theoretical framework on AlignmentAlgorithms.
 *
 * Note that the result of an AlignmentAlgorithm does not have to be a pure Double, but it may be
 * any object. Per convention, however, we expect the resulting object to provide the actual
 * alignment dissimilarity D(x,y) as well.
 *
 * @author Benjamin Paassen - [email protected]
 * @param  the class of the elements in the left input sequence.
 * @param  the class of the elements in the right input sequence.
 * @param  the result class that represents the alignment in some way.
 */
public interface AlignmentAlgorithm {

	/**
	 * This should return the Comparator used to compute local distances for this algorithm.
	 *
	 * @return the comparator that is used to compute local distances for this Algorithm.
	 */
	public Comparator getComparator();

	/**
	 * This should set the Comparator used to compute local distances for this algorithm.
	 *
	 * @param comparator the comparator that is used to compute local distances for this Algorithm.
	 */
	public void setComparator(@NonNull final Comparator comparator);

	/**
	 * This calculates the alignment dissimilarity D between the Sequences x ∈ X* and y ∈
	 * Y* and returns it as an instance of the result class for this algorithm.
	 *
	 * Specific parameters should be set either in the Comparator or in the implementation itself.
	 *
	 * Furthermore, the implementation should guarantee that
	 * 
	 * D(x,y) ≥ 0 (non-negativity)
	 * x = y ⇒ D(x, y) = 0 (equality)
	 * D(x, y) ≤ 1
	 * D(x,y) = D(y,x) (symmetry) if the given Comparator d fulfills this property
	 * x ≠ y ⇒ D(x,y) > 0 if the given Comparator d fulfills this property
	 * D(x, z) ≤ D(x, y) + D(y, z) (triangular inequality) if the given Comparator d
	 * fulfills this property
	 * 
	 *
	 * @param x The left input sequence.
	 * @param y The right input sequence.
	 *
	 * @return An alignment of a and b in terms of the given result class.
	 */
	public R calculateAlignment(@NonNull final List x, @NonNull final List y);

	/**
	 * This method shall return the class of the alignment result.
	 *
	 * @return the class of the alignment result.
	 */
	public Class getResultClass();

	/**
	 * This method should return true if and only if this AlignmentAlgorithm uses the given
	 * operation.
	 *
	 * @param type an OperationType.
	 *
	 * @return true if and only if this AlignmentAlgorithm uses the given operation.
	 */
	public boolean requires(@NonNull OperationType type);

}