gate.plugin.learningframework.features.FeatureExtractionDense Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of learningframework Show documentation
Show all versions of learningframework Show documentation
A GATE plugin that provides many different machine learning
algorithms for a wide range of NLP-related machine learning tasks like
text classification, tagging, or chunking.
/*
* Copyright (c) 2015-2016 The University Of Sheffield.
*
* This file is part of gateplugin-LearningFramework
* (see https://github.com/GateNLP/gateplugin-LearningFramework).
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation, either version 2.1 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 Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this software. If not, see annlistforward = withinSet.getContained(end, rangeTo).get(annType4Getting).inDocumentOrder();
List annlistbackward = withinSet.getContained(rangeFrom, start).get(annType4Getting).inDocumentOrder();
//System.err.println("rangeFrom=" + rangeFrom + ", rangeTo=" + rangeTo + ",START=" + start + ", END=" + end + ", forwardsize=" + annlistforward.size() + ", backwardsize=" + annlistbackward.size());
// go through each of the members in the attribute list and get the annotation
// then process each annotation just like a simple annotation, only that the name of
// featureName gets derived from this list attribute plus the location in the list.
// TODO: this does not work if the annotations are overlapping!!!
// TODO: this could also create n-grams of consecutive elements, based on an AttributeList
// parameter N. Instead of creating the feature from a single source annotation, the
// features of N successive elements would get combined to form an ngram feature.
// The identifier for such a feature would have to include the starting list element and N
// e.g. "L"+i+"N"+n
// First loop: go from index -1 to the smallest from index to the left
int albsize = annlistbackward.size();
for (int i = -1; i >= from; i--) {
// -1 corresponds to element (size-1) in the list,
// -2 corresponds to element (size-2) in the list etc.
// in general we want element (size+i) if that is > 0
if (albsize + i >= 0) {
Annotation ann = annlistbackward.get(albsize + i);
inst = extractFeatureWorker(al, featureName(al,i), inst, ann, doc, annType4Feature,
featureName, dt, listsep);
} else {
// generate a missing value feature here
inst = inst.setFeature(featureName(al,i), al.missingValue());
}
}
// if we have index 0 in the range, process for that one
if (from <= 0 && to >= 0) {
inst = extractFeatureWorker(al, featureName(al,0), inst, sourceAnnotation, doc, annType4Feature,
featureName, dt, listsep);
}
// do the ones to the right
int alfsize = annlistforward.size();
for (int i = 1; i <= to; i++) {
// for i=1 we get element 0, in general we get element i-1
// if i <= size
if (i <= alfsize) {
Annotation ann = annlistforward.get(i - 1);
inst = extractFeatureWorker(al, featureName(al,i), inst, ann, doc, annType4Feature,
featureName, dt, listsep);
} else {
// generate a missing value feature here
inst = inst.setFeature(featureName(al,i), al.missingValue());
}
}
return inst;
} // extractFeature (AttributeList)
/*
*
*/
// TODO: NOTE: this currently returns a single string which represents all N-grams
// If there are at least n annotations inputAS speficied by the Ngam TYPE contained in the span of
// the instance annotation, then those annotations are arranged in document order and
// - starting with the second index, up to the last
// -
// CHECK: if we get the same ngram multiple times, we should have a count!!! e.g. unigram "fred" three
// times we should have 3.0
// TODO: check what to do if the contained annotations are not in non-overlapping order: should we
// create an ngram if the second annotations starts before the end of the first or even at the same
// offset inputAS the first? If that is the case, what should the order of the annotations then be?
// NOTE: if the featureName is missing, i.e. it is null or the empty string, then the whole annotation gets ignored
private static InstanceRepresentation extractFeatureHelper(
InstanceRepresentation inst,
FeatureSpecNgram ng,
AnnotationSet inputAS,
Annotation instanceAnnotation
) {
Document doc = inputAS.getDocument();
int number = ng.number;
String annType = ng.annType;
String featureName = ng.feature;
String featureName4Value = ng.featureName4Value;
// TODO: this we rely on the ngram only having allowed field values, e.g. annType
// has to be non-null and non-empty and number has to be > 0.
// If featureName is null, then for ngrams, the string comes from the covered document
// TODO: we had the following unsued variable in here previously, check why?
// String[] gram = new String[number];
List al = Utils.getContainedAnnotations(inputAS, instanceAnnotation, annType).inDocumentOrder();
// If we have less annotations than our n for n-gram, there is certainly nothing to do,
// leave the featureName vector untouched.
if (al.size() < number) {
// return an empty list, we alway need the feature to be there!
inst = inst.setFeature(featureName(ng,0), new ArrayList<>());
return inst;
}
// this will hold the actual token strings to use for creating the n-grams
List strings = new ArrayList<>();
// this will hold the score to use for each string we extract, but only of the
// featureName4Value was specified and exists.
List scores = new ArrayList<>();
for (Annotation ann : al) {
// for ngrams we either have a featureName name
if (featureName != null) {
// NOTE: if the featureName is not a string, we convert it to string
Object obj = ann.getFeatures().get(featureName);
// if there is no value at all, then the annotation is ignored
if (obj != null) {
String tmp = obj.toString().trim();
// if the resulting string is empty, it is also ignored
if (!tmp.isEmpty()) {
strings.add(tmp);
double score = 1.0;
if (!featureName4Value.isEmpty()) {
score = gate.plugin.learningframework.LFUtils.anyToDoubleOrElse(ann.getFeatures().get(featureName4Value), 1.0);
}
scores.add(score);
}
}
} else {
// if the featureName is null, we get the string from the cleaned document text
String tmp = gate.Utils.cleanStringFor(doc, ann).trim();
if (!tmp.isEmpty()) {
strings.add(tmp);
double score = 1.0;
if (!featureName4Value.isEmpty()) {
score = gate.plugin.learningframework.LFUtils.anyToDoubleOrElse(ann.getFeatures().get(featureName4Value), 1.0);
}
scores.add(score);
}
}
} // for Annotation ann : al
// Now construct the actual ngrams and add them to the augmentable featureName vector.
// In the process, check first if such a featureName is already there, and if yes, just
// increment the value.
// To avoid overhead, we only create the ngrams on the fly// Now construct the actual ngrams and add them to the augmentable feature vector.
// In the process, check first if such a feature is already there, and if yes, just
// increment the value.
// To avoid overhead, we only create the ngrams on the fly
// now create the ngrams inputAS follows: starting with the first element in strings, go
// through all the elements up to the (size-n)ths and concatenate with the subsequent
// n stings using the pre-defined separator character.
// Add all the ngrams into a list
List ngramlist = new ArrayList<>();
// first check if our strings array is actually big enough so we can create at least one n-gram
if (strings.size() < number) {
// ok, no, for dense representations we return an empty list here
inst = inst.setFeature(featureName(ng,0), ngramlist);
return inst;
}
StringBuilder sb = new StringBuilder();
for (int i = 0; i < (strings.size() - number + 1); i++) {
sb.setLength(0);
// NOTE: the score for an ngram is calculated by multiplying the scores
// for each part of the ngram. If there is no featureName4Value, then all those
// scores are 1.0 at this point as well, so the final score is also 1.0.
// If we have a featureName4Value and it is a 1-gram, then we get the value of that
// feature. If it is an n-gram with n>1, then we get the product of all the scores
// of each gram.
double score = 1.0;
for (int j = 0; j < number; j++) {
if (j != 0) {
sb.append(NGRAMSEP);
}
sb.append(strings.get(i + j));
score *= scores.get(i + j);
}
String ngram = sb.toString();
ngramlist.add(ngram);
}
inst = inst.setFeature(featureName(ng,0), ngramlist);
//System.err.println("DEBUG: Vector after adding feature "+ng+" is now "+fv);
return inst;
} // extractFeature(NGram)
/**
* Do the actual hard work of extracting a feature and adding it to the Mallet feature vector.
* This is used to do the actual extraction for simple attributes and attribute lists.
*
*/
private static InstanceRepresentation extractFeatureWorker(
FeatureSpecAttribute attr,
String fname,
InstanceRepresentation inst,
Annotation sourceAnnotation,
Document doc,
String annType,
String featureName,
Datatype dt,
String listsep) {
String name = attr.name;
//String fname = featureNamePrefix(attr) + internalFeatureIndicator;
if (featureName.isEmpty()) {
// construct the featureName name and set to 1.0
// however, only add the featureName if the featureName alphabet is allowed to grow.
inst = inst.setFeature(fname, true);
} else {
// First get the value inputAS an Object, if there is no value, we have an Object that is null
// If the sourceAnnotation is null, we already did not find the source at all,
// so the value is always missing.
Object valObj = null;
if (sourceAnnotation != null) {
valObj = sourceAnnotation.getFeatures().get(featureName);
}
// no matter what the datatype is, a null is always a missing value, so we set the
// property that indicates the existence of a missing valuein the instance right here
if (valObj == null) {
inst = inst.setHasMissing(true);
inst = inst.setFeature(fname, attr.missingValue());
} else {
inst = inst.setHasMissing(false);
// we almost always just set this to the original value
// so far the only exception is if we have a listsep, in which case we
// convert the string to a list of strings.
// Otherwise, convert the value to either string, Double or Boolean,
// depending on the type of the Attribute.
if(attr.listsep != null && !attr.listsep.isEmpty()) {
String[] els = valObj.toString().split(attr.listsep);
inst = inst.setFeature(fname, Arrays.asList(els));
} else {
Object finalValue = attr.toValue(valObj);
//System.err.println("DEBUG: final value for "+valObj+" of type "+valObj.getClass()+" is "+finalValue);
inst = inst.setFeature(fname, finalValue);
}
} // no missing value
} // non-empty feature name
return inst;
} // extractFeatureWorker
// *****************************************************************************
// Extract the target stuff
// *****************************************************************************
/**
* Extract a numeric target and update instance representation.
* @param inst instance representation
* @param targetFeature target feature
* @param instanceAnnotation instance annotation
* @param inputAS input annotation set
* @return updated instance representation
*/
public static InstanceRepresentation extractNumericTarget(InstanceRepresentation inst, String targetFeature, Annotation instanceAnnotation, AnnotationSet inputAS) {
Document doc = inputAS.getDocument();
Object obj = instanceAnnotation.getFeatures().get(targetFeature);
// Brilliant, we have a missing target, WTF? Throw an exception
if (obj == null) {
throw new GateRuntimeException("No target value for feature " + targetFeature
+ " for instance at offset " + gate.Utils.start(instanceAnnotation) + " in document " + doc.getName());
}
double value = Double.NaN;
if (obj instanceof Number) {
value = ((Number) obj).doubleValue();
} else {
String asString = obj.toString();
try {
value = Double.parseDouble(asString);
} catch (NumberFormatException ex) {
throw new GateRuntimeException("Could not convert target value to a double for feature " + targetFeature
+ " for instance at offset " + gate.Utils.start(instanceAnnotation) + " in document " + doc.getName());
}
}
return inst.setTargetValue(value);
}
/**
* Extract the class label for the given instance annotation.
*
* Only handles scalar targets so far.
*
* TODO: handle array of costs
*
* @param inst instance representation
* @param targetFeature target feature
* @param instanceAnnotation instance annotation
* @param inputAS input annotation set
* @return instance representation
*/
public static InstanceRepresentation extractClassTarget(InstanceRepresentation inst, String targetFeature, Annotation instanceAnnotation, AnnotationSet inputAS) {
Document doc = inputAS.getDocument();
Object obj = instanceAnnotation.getFeatures().get(targetFeature);
// Brilliant, we have a missing target, WTF? Throw an exception
if (obj == null) {
throw new GateRuntimeException("No target value for feature " + targetFeature
+ " for instance at offset " + gate.Utils.start(instanceAnnotation) + " in document " + doc.getName());
} else if (obj instanceof List) {
throw new GateRuntimeException("Array of costs not yet implemented for dense instances");
} else if (obj instanceof double[]) {
throw new GateRuntimeException("Array of costs not yet implemented for dense instances");
} else {
// all other things are treated as a string
String value = obj.toString();
inst = inst.setTargetValue(value);
}
return inst;
}
/**
* Extract the class for an instance for sequence tagging.
*
* In the case of sequence tagging, we construct the class based on the instance's position
* relative to the class annotation annType. If it occurs at the beginning of the class
* annotation, it's a "beginning". In the middle or at the end, it's an "inside". Instances that
* don't occur in the span of a class annotation are an "outside".
*
* @param inst instance representation
* @param classAS class annotation set
* @param instanceAnnotation instance annotation
* @param seqEncoder sequence encoder
* @return instance representation
*/
public static InstanceRepresentation extractClassForSeqTagging(InstanceRepresentation inst, AnnotationSet classAS, Annotation instanceAnnotation, SeqEncoder seqEncoder) {
String target;
AnnotationSet overlappingClassAnns = Utils.getOverlappingAnnotations(classAS, instanceAnnotation);
Document doc = classAS.getDocument();
// NOTE: previously we only allowed at most one class annotation, but now we are as flexible
// as possible here: any number of class annotations of any number of types can overlap.
// The class label for each instance is generated from the complete list of what overlaps,
// e.g. beginning of T1, beginning of another T1, continuation of T2 and end of T3
// The class labels for such combinations only get generated if an overlap actually occurs,
// so if we only ever see nicely separated annotations, then we will never see the combined labels.
// Labels are dynamically generated as a string of pipe-separated type names, with the flag
// (beginning=B, inside=I) appended, or class "O" if outside of all types.
// The ordering of types in the class label name must be consistent: TODO!!
// NOTE: this should be one of several possible ways to do it, implemented in several
// methods/classes and choosable through e.g. the "algorithmParameter" settings.
// Then we could use approaches like BIO, BMEWO, BMEWO+ (see
// https://lingpipe-blog.com/2009/10/14/coding-chunkers-as-taggers-io-bio-bmewo-and-bmewo/)
// or the ones listed in http://cs229.stanford.edu/proj2005/KrishnanGanapathy-NamedEntityRecognition.pdf
// Whenever we choose a strategy here, the strategy needs to get stored in the
// model info file and re-used at application time!
// NOTE: need to see if the label alphabet growing setting is handled correctly!
// if there is at least one overlapping class annotation
if (overlappingClassAnns.size() > 0) {
// convert the set of annotation types to a list of type|code names
// this should eventually be parametrizable so we can choose one of several methods
// ideally we implement this as a method of one of an instance of several Seq2Class
// subclasses. If it is an instance we could maybe also implement methods where we
// need to remember something about the last instance for which we did it!
target = seqEncoder.seqAnns2ClassLabel(overlappingClassAnns, instanceAnnotation, doc);
} else {
//No overlapping mentions so it's an outside
target = SeqEncoder.CODE_OUTSIDE;
}
// if debugging is enabled, we put the
// the target class on the instance annotation
if (DEBUG_SEQUENCE_CLASS) {
instanceAnnotation.getFeatures().put("LF_sequenceClass", target);
}
inst = inst.setTargetValue(target);
return inst;
}
/**
* Return the attribute name part of a ML feature.
*
* @param mlFeature the feature name
* @return the attribute name
*/
public static String attrName4MlFeature(String mlFeature) {
// first get the attribute name part
String parts[] = mlFeature.split(NAMESEP, -1);
if (parts.length < 2) {
throw new RuntimeException("Odd ML feature name, does not contain a NAMESEP: " + mlFeature);
}
return parts[0];
}
/**
* Try and find the attribute that corresponds to the ML featureName.
*
* This requires the instance annotation type because the way how the ML feature is generated
* depends on the instance annotation type.
*
* @param attributes the attributes
* @param mlFeatureName ML feature name
* @param instanceType instance type
* @return the attribute
*/
public static FeatureSpecAttribute lookupAttributeForFeatureName(List attributes,
String mlFeatureName, String instanceType) {
FeatureSpecAttribute ret = null;
// these features are created by the LF and will not be present in the list of specifications.
// We create a new specification on the fly for those.
// Following code commented out to avoid FindBug warning because so far the if is useless
/*
if(mlFeatureName.endsWith(START_SYMBOL) || mlFeatureName.endsWith(STOP_SYMBOL)) {
// TODO!!!
// return a newly constructed dummy feature spec attribute
// NOTE: for now we handle the case that this method does not find anything and returns
// null if we get a START/STOP indicator feature directly where this method is called!
}
*/
String attrName = attrName4MlFeature(mlFeatureName);
// now if the attrName contains a TYPESEP, we have to find the attribute by
// type and feature name, otherwise we simply find it by name
if (attrName.contains(TYPESEP)) {
String parts[] = attrName.split(TYPESEP, -1);
if (parts.length != 2) {
throw new RuntimeException("ODD ATTRIBUTE NAME"); // should never happen
}
String featType = parts[0];
String featName = parts[1];
for (FeatureSpecAttribute attr : attributes) {
if (featName.equals(attr.feature)) {
// the types should also match but we have to consider that the
// type in the attribute specification can be empty in which case we
// have a match if the type from the mlFeature is also empty or matches
// the instanceType. The same is true vice-versa: if the type from the
// mlFeature is empty than the type from the attr spec must be empty
// or match the instanceType
if (featType.equals(attr.annType)) {
ret = attr;
break;
} else if (featType.isEmpty()) {
if (attr.annType.isEmpty() || attr.annType.equals(instanceType)) {
ret = attr;
break;
}
} else if (attr.annType.isEmpty()) {
if (featType.isEmpty() || featType.equals(instanceType)) {
ret = attr;
break;
}
}
}
}
} else {
for (FeatureSpecAttribute attr : attributes) {
if (attr.name != null && attr.name.equals(attrName)) {
ret = attr;
break;
}
}
}
return ret;
}
}