package jsat.parameters;
import java.io.Serializable;
import java.lang.annotation.*;
import java.lang.reflect.Field;
import java.lang.reflect.Method;
import java.util.*;
import java.util.logging.Level;
import java.util.logging.Logger;
import jsat.DataSet;
import jsat.distributions.Distribution;
import jsat.distributions.empirical.kernelfunc.KernelFunction;
import jsat.linear.distancemetrics.DistanceMetric;
import jsat.math.decayrates.DecayRate;
/**
* This interface provides a programmable manner in which the parameters of an
* algorithm may be altered and adjusted.
*
* @author Edward Raff
*/
public abstract class Parameter implements Serializable
{
private static final long serialVersionUID = -6903844587637472657L;
/**
* Adding this annotation to a field tells the
* {@link #getParamsFromMethods(java.lang.Object)} method to search this
* object recursively for more parameter get/set
* pairs.
* Placing this annotation on a {@link Collection} will cause the search to
* be done recursively over each item in the collection.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public static @interface ParameterHolder
{
boolean skipSelfNamePrefix() default false;
}
/**
* Adding this annotation to a method tells the {@link #getParamsFromMethods(java.lang.Object)
* } method to consider the Parameter object generated for that method a
* preferred parameter for warm starting.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public static @interface WarmParameter
{
/**
* Indicates the ordering that would be preferred by the algorithm when
* training.
*
* It may be the case that the model has no preference for models to be
* trained from low to high or high to low, in which case any arbitrary
* value may be returned - so long as it consistently returns the same
* value.
*
* @return {@code true} if it is preferred to train from low values of
* the parameter to high values of the parameter. {@code false} is
* returned if it is preferred to go from high to low values.
*/
boolean prefLowToHigh();
}
/**
* Some variables of a learning method may be adjustable without having to
* re-train the whole data set. false is returned if this is such a
* parameter, true if the learning method will need to be
* retrained after the parameter has changed.
* By default, this method returns true unless overwritten, as it
* is always safe to retrain the classifier if a parameter was changed.
* @return true if changing this parameter requires a re-training
* of the algorithm, or false if no-retraining is needed to take
* effect.
*/
public boolean requiresRetrain(){
return true;
};
/**
* If {@code true}, that means this parameter is the preferred parameter to
* be altered when warm starting from a previous version of the same class.
* Being the preferred parameter means that using warms started training on
* a sequence of changes to this parameter should be faster than simply
* training normally for every combination of values.
*
* If more than one parameter would have this impact on training, the one
* that has the largest and most consistent impact should be selected.
*
* By default, this method will return {@code false}.
*
* @return {@code true} if warm starting on changes in this parameter has a
* significant impact on training speed, {@code false} otherwise.
*/
public boolean isWarmParameter(){
return false;
};
/**
* This value is meaningless if {@link #isWarmParameter() } is {@code false}
* , and by default returns {@code false}.
*
* This should return the preferred order of warm start value training in
* the progression of the warm parameter, either from low values to high
* values (ie: the model being trained has a higher value for this parameter
* than the warm model being trained from).
*
* @return {@code true} if warm starting on this parameter should occur from
* low values to high values, and {@code false} if it should go from high
* values to low.
*/
public boolean preferredLowToHigh() {
return false;
}
/**
* Returns the name of this parameter using only valid ACII characters.
* @return the ACII name
*/
abstract public String getASCIIName();
/**
* Returns the display name of this parameter. By default, this returns the
* {@link #getASCIIName() ASCII name} of the parameter. If one exists, a
* name using Unicode characters may be returned instead.
*
* @return the name of this parameter
*/
public String getName()
{
return getASCIIName();
}
@Override
public String toString()
{
return getName();
}
@Override
public int hashCode()
{
return getName().hashCode();
}
/**
* Returns a string indicating the value currently held by the Parameter
*
* @return a string representation of the parameter's value
*/
abstract public String getValueString();
@Override
public boolean equals(Object obj)
{
if (obj == null)
return false;
if (getClass() != obj.getClass())
return false;
final Parameter other = (Parameter) obj;
return this.getName().equals(other.getName());
}
/**
* Creates a map of all possible parameter names to their corresponding object. No two parameters may have the same name.
* @param params the list of parameters to create a map for
* @return a map of string names to their parameters
* @throws RuntimeException if two parameters have the same name
*/
public static Map toParameterMap(List params)
{
Map map = new HashMap(params.size());
for(Parameter param : params)
{
if(map.put(param.getASCIIName(), param) != null)
throw new RuntimeException("Name collision, two parameters use the name '" + param.getASCIIName() + "'");
if(!param.getName().equals(param.getASCIIName()))//Dont put it in again
if(map.put(param.getName(), param) != null)
throw new RuntimeException("Name collision, two parameters use the name '" + param.getName() + "'");
}
return map;
}
/**
* Given an object, this method will use reflection to automatically find
* getter and setter method pairs, and create Parameter object for each
* getter setter pair.
* Getters are found by searching for no argument methods that start with
* "get" or "is". Setters are found by searching for one argument methods
* that start with "set".
* A getter and setter are a pair only if everything after the prefix is the
* same in the method's name, and the return type of the getter is the same
* class as the argument for the setter.
* Current types supported are:
*
* - integer
* - doubles
* - booleans
* - {@link KernelFunction Kernel Functions}
* - {@link DistanceMetric Distance Metrics}
* - {@link Enum Enums}
*
*
* @param obj
* @return a list of parameter objects generated from the given object
*/
public static List getParamsFromMethods(final Object obj)
{
return getParamsFromMethods(obj, "");
}
private static List getParamsFromMethods(final Object obj, String prefix)
{
Map getMethods = new HashMap();
Map setMethods = new HashMap();
//Collect potential get/set method pairs
for(Method method : obj.getClass().getMethods())
{
int paramCount = method.getParameterTypes().length;
if(method.isVarArgs() || paramCount > 1)
continue;
String name = method.getName();
if(name.startsWith("get") && paramCount == 0)
getMethods.put(name.substring(3), method);
else if(name.startsWith("is") && paramCount == 0)
getMethods.put(name.substring(2), method);
else if(name.startsWith("set") && paramCount == 1)
setMethods.put(name.substring(3), method);
}
//Find pairings and add to list
List params = new ArrayList(Math.min(getMethods.size(), setMethods.size()));
for(Map.Entry entry : setMethods.entrySet())
{
final Method setMethod = entry.getValue();
final Method getMethod = getMethods.get(entry.getKey());
if(getMethod == null)
continue;
final Class retClass = getMethod.getReturnType();
final Class argClass = entry.getValue().getParameterTypes()[0];
if(!retClass.equals(argClass))
continue;
final String name = spaceCamelCase(entry.getKey());
//Found a match do we know how to handle it?
Parameter param = getParam(obj, argClass, getMethod, setMethod, prefix + name);
if(param != null)
params.add(param);
}
//Find params from field objects
//first get all fields of this object
List fields = new ArrayList();
Class curClassLevel = obj.getClass();
while(curClassLevel != null)
{
fields.addAll(Arrays.asList(curClassLevel.getDeclaredFields()));
curClassLevel = curClassLevel.getSuperclass();
}
final String simpleObjName = obj.getClass().getSimpleName();
//For each field, check if it has our magic annotation
for(Field field : fields)
{
Annotation[] annotations = field.getAnnotations();
for(Annotation annotation : annotations)
{
if(annotation.annotationType().equals(ParameterHolder.class))
{
ParameterHolder annotationPH = (ParameterHolder) annotation;
//get the field value fromt he object passed in
try
{
//If its private/protected we are not int he same object chain
field.setAccessible(true);
Object paramHolder = field.get(obj);
if(paramHolder instanceof Collection)//serach for each item in the collection
{
Collection toSearch = (Collection) paramHolder;
for(Object paramHolderSub : toSearch)
{
String subPreFix = paramHolderSub.getClass().getSimpleName() + "_";
if(annotationPH.skipSelfNamePrefix())
subPreFix = prefix.replace(simpleObjName+"_", "") + subPreFix;
else
subPreFix = prefix + subPreFix;
params.addAll(Parameter.getParamsFromMethods(paramHolderSub, subPreFix));
}
}
else if(paramHolder != null)//search the item directly
{
String subPreFix = paramHolder.getClass().getSimpleName() + "_";
if (annotationPH.skipSelfNamePrefix())
subPreFix = prefix.replace(simpleObjName + "_", "") + subPreFix;
else
subPreFix = prefix + subPreFix;
params.addAll(Parameter.getParamsFromMethods(paramHolder, subPreFix));
}
}
catch (IllegalArgumentException ex)
{
Logger.getLogger(Parameter.class.getName()).log(Level.SEVERE, null, ex);
}
catch (IllegalAccessException ex)
{
Logger.getLogger(Parameter.class.getName()).log(Level.SEVERE, null, ex);
}
}
}
}
return params;
}
private static Parameter getParam(final Object targetObject, final Class varClass, final Method getMethod, final Method setMethod, final String asciiName)
{
return getParam(targetObject, varClass, getMethod, setMethod, asciiName, null);
}
private static Parameter getParam(final Object targetObject, final Class varClass, final Method getMethod, final Method setMethod, final String asciiName, final String uniName)
{
final boolean warm;
final boolean lowToHigh;
//lets find out if this paramter is a "warm" parameter
Parameter.WarmParameter warmAna = null;
warmAna = setMethod.getAnnotation(Parameter.WarmParameter.class);
if(warmAna == null)
warmAna = getMethod.getAnnotation(Parameter.WarmParameter.class);
if(warmAna != null)
{
warm = true;
lowToHigh = warmAna.prefLowToHigh();
}
else
{
warm = false;
lowToHigh = false;
}
//lets see if we can find a method that corresponds to "guess" for this parameter
final Method guessMethod;
Method tmp = null;
try
{
tmp = targetObject.getClass().getMethod("guess" + setMethod.getName().replaceFirst("set", ""), DataSet.class);
}
catch (NoSuchMethodException ex)
{
}
catch (SecurityException ex)
{
}
guessMethod = tmp;//ugly hack so that I can reference a final guess method in anon class below
//ok, now lets go create the correct object type
Parameter param = null;
if (varClass.equals(double.class) || varClass.equals(Double.class))
{
param = new DoubleParameter()
{
private static final long serialVersionUID = -4741218633343565521L;
@Override
public double getValue()
{
try
{
return (Double) getMethod.invoke(targetObject);
}
catch (Exception ex)
{
}
return Double.NaN;
}
@Override
public boolean setValue(double val)
{
try
{
setMethod.invoke(targetObject, val);
return true;
}
catch (Exception ex)
{
}
return false;
}
@Override
public boolean isWarmParameter()
{
return warm;
}
@Override
public boolean preferredLowToHigh()
{
return lowToHigh;
}
@Override
public String getASCIIName()
{
return asciiName;
}
@Override
public String getName()
{
if (uniName == null)
return super.getName();
else
return uniName;
}
@Override
public Distribution getGuess(DataSet data)
{
if (guessMethod == null)
return null;
try
{
return (Distribution) guessMethod.invoke(targetObject, data);
}
catch (Exception ex)
{
}
return null;
}
};
}
else if (varClass.equals(int.class) || varClass.equals(Integer.class))
{
param = new IntParameter()
{
private static final long serialVersionUID = 693593136858174197L;
@Override
public int getValue()
{
try
{
return (Integer) getMethod.invoke(targetObject);
}
catch (Exception ex)
{
}
return -1;
}
@Override
public boolean setValue(int val)
{
try
{
setMethod.invoke(targetObject, val);
return true;
}
catch (Exception ex)
{
}
return false;
}
@Override
public Distribution getGuess(DataSet data)
{
if (guessMethod == null)
return null;
try
{
return (Distribution) guessMethod.invoke(targetObject, data);
}
catch (Exception ex)
{
}
return null;
}
@Override
public boolean isWarmParameter()
{
return warm;
}
@Override
public boolean preferredLowToHigh()
{
return lowToHigh;
}
@Override
public String getASCIIName()
{
return asciiName;
}
@Override
public String getName()
{
if (uniName == null)
return super.getName();
else
return uniName;
}
};
}
else if (varClass.equals(boolean.class) || varClass.equals(Boolean.class))
{
param = new BooleanParameter()
{
private static final long serialVersionUID = 8356074301252766754L;
@Override
public boolean getValue()
{
try
{
return (Boolean) getMethod.invoke(targetObject);
}
catch (Exception ex)
{
}
return false;
}
@Override
public boolean setValue(boolean val)
{
try
{
setMethod.invoke(targetObject, val);
return true;
}
catch (Exception ex)
{
}
return false;
}
@Override
public String getASCIIName()
{
return asciiName;
}
@Override
public String getName()
{
if (uniName == null)
return super.getName();
else
return uniName;
}
};
}
else if (varClass.equals(KernelFunction.class))
{
param = new KernelFunctionParameter()
{
private static final long serialVersionUID = -482809259476649959L;
@Override
public KernelFunction getObject()
{
try
{
return (KernelFunction) getMethod.invoke(targetObject);
}
catch (Exception ex)
{
}
return null;
}
@Override
public boolean setObject(KernelFunction val)
{
try
{
setMethod.invoke(targetObject, val);
return true;
}
catch (Exception ex)
{
}
return false;
}
};
}
else if (varClass.equals(DistanceMetric.class))
{
param = new MetricParameter()
{
private static final long serialVersionUID = -2823576782267398656L;
@Override
public DistanceMetric getMetric()
{
try
{
return (DistanceMetric) getMethod.invoke(targetObject);
}
catch (Exception ex)
{
}
return null;
}
@Override
public boolean setMetric(DistanceMetric val)
{
try
{
setMethod.invoke(targetObject, val);
return true;
}
catch (Exception ex)
{
}
return false;
}
};
}
else if (varClass.equals(DecayRate.class))
{
param = new DecayRateParameter()
{
private static final long serialVersionUID = 5348280386363008701L;
@Override
public DecayRate getObject()
{
try
{
return (DecayRate) getMethod.invoke(targetObject);
}
catch (Exception ex)
{
}
return null;
}
@Override
public boolean setObject(DecayRate obj)
{
try
{
setMethod.invoke(targetObject, obj);
return true;
}
catch (Exception ex)
{
}
return false;
}
@Override
public String getASCIIName()
{
return asciiName;
}
@Override
public String getName()
{
if (uniName == null)
return super.getName();
else
return uniName;
}
};
}
else if (varClass.isEnum())//We can create an ObjectParameter for enums
{
param = new ObjectParameter()
{
private static final long serialVersionUID = -6245401198404522216L;
@Override
public Object getObject()
{
try
{
return getMethod.invoke(targetObject);
}
catch (Exception ex)
{
}
return null;
}
@Override
public boolean setObject(Object val)
{
try
{
setMethod.invoke(targetObject, val);
return true;
}
catch (Exception ex)
{
}
return false;
}
@Override
public List parameterOptions()
{
return Collections.unmodifiableList(Arrays.asList(varClass.getEnumConstants()));
}
@Override
public String getASCIIName()
{
return asciiName;
}
@Override
public String getName()
{
if (uniName == null)
return super.getName();
else
return uniName;
}
};
}
return param;
}
/**
* Returns a version of the same string that has spaced inserted before each
* capital letter
* @param in the CamelCase string
* @return the spaced Camel Case string
*/
private static String spaceCamelCase(String in)
{
StringBuilder sb = new StringBuilder(in.length()+5);
for(int i = 0; i < in.length(); i++)
{
char c = in.charAt(i);
if(Character.isUpperCase(c))
sb.append(' ');
sb.append(c);
}
return sb.toString().trim();
}
}
Ads help maintain this website.