Package org.anchoranalysis.feature.bean

Class Feature<T extends FeatureInput>

Object

org.anchoranalysis.bean.AnchorBean<B>

org.anchoranalysis.bean.initializable.InitializableBean<Feature<T>,FeatureInitialization>

org.anchoranalysis.feature.bean.Feature<T>

Type Parameters:

T - input-type from which a measurement is calculated.

Direct Known Subclasses:

FeatureBinary, FeatureFromList, FeatureGeneric, FeatureResults, FeatureUnary

public abstract class Feature<T extends FeatureInput>
extends InitializableBean<Feature<T>,FeatureInitialization>

Base class for a measurement that calculates a result (double) given input parameters.

This is a key base class in the Anchor framework, and many algorithms and procedures use a Feature on particular input-types to calculate measurements in a flexible way, and often to use these measurements in a machine-learning algorithm.

See Feature (Machine learning) on Wikipedia for general background on the concept of a feature in Machine Learning.

Author:

Owen Feehan

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Feature()	Creates with the default initializer.
protected	Feature(BeanInitializer<FeatureInitialization> propertyInitializer)	Creates with a custom initializer.

Method Summary

Modifier and Type	Method	Description
protected void	assignTo(Feature<FeatureInput> target)	Copies fields in this (base) class to target.
protected void	beforeCalc(FeatureInitialization initialization)	Dummy method, that children can optionally override.
protected abstract double	calculate(FeatureCalculationInput<T> input)	Calculates a value for some input.
double	calculateCheckInitialized(FeatureCalculationInput<T> input)	Calculates the result of a feature and throws an exception if the feature has not been initialized.
<S extends T> Feature<S>	castAs()	Casts the feature to having a different input-type.
FeatureList<FeatureInput>	createListChildFeatures()	Returns a list of Features that exist as bean-properties of this feature, either directly or in lists.
String	describeBean()
String	describeParameters()	A human-readable description of the parameterization of the bean.
String	descriptionLong()	A long human-readable description of the feature and some or all of its parameterization.
Feature<T>	duplicateChangeName(String customName)	Duplicates the feature as per AnchorBean.duplicateBean() but sets a particular custom-name.
String	getCustomName()	An optional additional name that be associated with the feature (defaults to an empty string).
String	getFriendlyName()	A user-friendly human-readable name for the Feature.
abstract Class<? extends FeatureInput>	inputType()	The class corresponding to feature input-type.
void	onInitialization(FeatureInitialization initialization)	Called after initialization.
void	setCustomName(String customName)	An optional additional name that be associated with the feature (defaults to an empty string).
String	toString()

Methods inherited from class org.anchoranalysis.bean.initializable.InitializableBean

getInitialization, getLogger, getPropertyInitializer, initialize, initializeRecursive, initRecursiveWithInitializer, isInitialized

Methods inherited from class org.anchoranalysis.bean.AnchorBean

checkMisconfigured, describeChildren, duplicateBean, fields, findFieldsOfClass, getBeanName, getLocalPath, localise

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

Feature

protected Feature()

Creates with the default initializer.

Feature

protected Feature(BeanInitializer<FeatureInitialization> propertyInitializer)

Creates with a custom initializer.

Parameters:

propertyInitializer - the custom initializer.

Method Details

onInitialization

public void onInitialization(FeatureInitialization initialization) throws InitializeException

Called after initialization.

An empty implementation is provided, to be overridden as needed in the sub-classes.

Overrides:

onInitialization in class InitializableBean<Feature<T extends FeatureInput>,FeatureInitialization>

Throws:

InitializeException

inputType

public abstract Class<? extends FeatureInput> inputType()

The class corresponding to feature input-type.

i.e. corresponding to the T template parameter.

Returns:

the class.

describeBean

public final String describeBean()

Overrides:

describeBean in class AnchorBean<Feature<T extends FeatureInput>>

descriptionLong

public String descriptionLong()

A long human-readable description of the feature and some or all of its parameterization.

This can be overwritten to create an alternative description for features. By default string returned by describeBean() is used.

Returns:

the description.

duplicateChangeName

public Feature<T> duplicateChangeName(String customName)

Duplicates the feature as per AnchorBean.duplicateBean() but sets a particular custom-name.

Parameters:

customName - the custom-name to set.

Returns:

a duplicated (deep copy of bean attributes) feature, identical to current feature, but with the specified custom-name.

getFriendlyName

public String getFriendlyName()

A user-friendly human-readable name for the Feature.

If a custom-name has been assigned, this is returned, otherwise the descriptionLong().

Returns:

the user-friendly human-readable name.

createListChildFeatures

public final FeatureList<FeatureInput> createListChildFeatures() throws BeanMisconfiguredException

Returns a list of Features that exist as bean-properties of this feature, either directly or in lists.

It does not recurse.

It ignores features that are referenced from elsewhere.

Returns:

the list of features.

Throws:

BeanMisconfiguredException - if the feature-beans are not structured as expected.

describeParameters

public String describeParameters()

A human-readable description of the parameterization of the bean.

Returns:

the description.

toString

public String toString()

Overrides:

toString in class AnchorBean<Feature<T extends FeatureInput>>

castAs

public <S extends T> Feature<S> castAs()

Casts the feature to having a different input-type.

Note that no active compile-type check occurs, so be careful that this is used appropriately.

Type Parameters:

S - the type to cast to, which should be a sub-type of the existing-type.

Returns:

the same instance, cast as having a different input-type.

calculateCheckInitialized

public double calculateCheckInitialized(FeatureCalculationInput<T> input) throws FeatureCalculationException

Calculates the result of a feature and throws an exception if the feature has not been initialized.

It is not recommended to directly use this method to calculate a feature's value, but rather to:

• Externally, for code outside a Feature's implementation, please use the feature-session classes, who will perform the calculation using caching to reduce redundant computation.
• Internally, for code inside a Feature's implementation, please call FeatureCalculationInput.calculate(Feature) and similar methods, who will back-reference the session above, to take advantage of the caching.

Parameters:

input - the input to the calculation.

Returns:

the feature-value corresponding to input for this feature.

Throws:

FeatureCalculationException - if the feature has not been initialized.

beforeCalc

protected void beforeCalc(FeatureInitialization initialization) throws InitializeException

Dummy method, that children can optionally override.

Parameters:

initialization - initialization parameters.

Throws:

InitializeException - if initialization cannot complete successfully.

calculate

protected abstract double calculate(FeatureCalculationInput<T> input) throws FeatureCalculationException

Calculates a value for some input.

Parameters:

input - the input to the calculation.

Returns:

the result of the calculation.

Throws:

FeatureCalculationException - if the calculation cannot successfully complete.

assignTo

protected void assignTo(Feature<FeatureInput> target)

Copies fields in this (base) class to target.

This is intended to be called by sub-classes to help when duplicating.

Parameters:

target - the object fields are assigned to.

getCustomName

public String getCustomName()

An optional additional name that be associated with the feature (defaults to an empty string).

setCustomName

public void setCustomName(String customName)

An optional additional name that be associated with the feature (defaults to an empty string).