#### Previous topic

API reference for casimir.optim

#### Next topic

API reference for structured_prediction_experiment

# API reference for casimir.data¶

This page summarizes the API for various data related operations for tasking including binary classification, named entity recognition and object localization. Lastly, it talks about how to use the optimization algorithms to new tasks or datasets.

## Classification¶

class casimir.data.LogisticRegressionIfo(data, labels)

Create an incremental First Order Oracle for logistic regression.

The component function $$f_i$$ is the logistic loss defined on the $$i$$ th example for binary classficiation.

Parameters: data – matrix of size $$n \times d$$, where $$n$$ is the number of data points and $$d$$ is dimensionality of each data point labels – vector of size $$n$$, with entries 0 or 1
batch_function_value(model)

Return function value $$f(w)$$ where $$w$$ is model.

batch_gradient(model)

Return gradient $$\nabla f(w)$$ where $$w$$ is model.

evaluation_function(model)

Compute the classification error (0-1 loss).

function_value(model, idx)

Return function value $$f_i(w)$$ where $$w$$ is model and $$i$$ is idx.

gradient(model, idx)

Return gradient $$\nabla f_i(w)$$ where $$w$$ is model and $$i$$ is idx.

## Named Entity Recognition:¶

casimir.data.named_entity_recognition.create_ner_ifo_from_data(train_file, dev_file=None, test_file=None, smoothing_coefficient=None, num_highest_scores=5)

Create Smooth IFOs for train, development and test sets in CoNLL 2003 for the structural hinge loss.

Each component function $$f_i$$ is the structural hinge loss for the $$i$$ th datapoint $$x_i,y_i$$.

Parameters: train_file – Text file with training data. dev_file – Text file with development data. A value of None is taken to mean that there is no development set. test_file – Test file with test data. A value of None is taken to mean that there is no test set. smoothing_coefficient – Smoothing coefficient to initialize Smoothed IFOs. Default None (i.e., no smoothing). num_highest_scores – The parameter $$K$$ used by the top-K Viterbi algorithm for inference. Default 5. Train, development and test Smoothed IFOs. Dev (test) IFO is None if dev (test) file is None.
class casimir.data.named_entity_recognition.NamedEntityRecognitionIfo(ner_dataset, num_ner_tags, ner_to_idx, smoothing_coefficient=None, num_highest_scores=5)

Create a smoothed incremental first order oracle for structural hinge loss for the task of NER.

Supports both non-smooth and $$\ell_2$$ smoothed versions of the structural hinge loss but not entropy smoothing.

Parameters: ner_dataset – NerDataset object that supports __len__ and __getitem__ methods. num_ner_tags – Number of NER tags. NER tags are assumed to be 0, 1, … , num_ner_tags-1. ner_to_idx – dict mapping each NER tag to its integer ID. smoothing_coefficient – The amount of smoothing $$\mu$$. num_highest_scores – The value K for top-K inference.
evaluation_function(model)

Return the $$F_1$$ score on all tags excluding 'O'.

function_value(model, idx)

Return the pair $$\big( f_i(w), f_{i, \mu}(w) \big)$$. If smoothing_coefficient is None, i.e., no smoothing, simply return $$f_i(w)$$, where $$i$$ represents the index idx.

gradient(model, idx)

Return that gradient $$\nabla f_{i, \mu}(w)$$ if smoothing_coefficient is not None or $$\nabla f_i(w)$$ if smoothing_coefficient is None.

class casimir.data.named_entity_recognition.NerDataset(lines, word_to_idx, pos_to_idx, chunk_to_idx, ner_to_idx)

Class to parse CoNLL-2003 data and allow random access into dataset.

Requires output of generate_counts_and_feature_map.

casimir.data.named_entity_recognition.viterbi_decode()

Viterbi decoding to find maximum scoring label sequence

Parameters: words – sequence of words, as a part of input pos_tags – sequence of part of speech tags, as a part of input chunk_tags – sequence of chunk tags, as a part of input ner_tags – output sequence of NER tags num_tags – total number of possible NER tags model – Ndarray of weights use_loss – use loss-augmented inference with Hamming loss if true highest score, best scoring label sequence
casimir.data.named_entity_recognition.viterbi_decode_top_k()

Top-K Viterbi decoding to find $$K$$ maximum scoring label sequences

Parameters: num_highest_scores – the parameter $$K$$ in top-K inference words – sequence of words, as a part of input pos_tags – sequence of part of speech tags, as a part of input chunk_tags – sequence of chunk tags, as a part of input ner_tags – output sequence of NER tags num_tags – total number of possible NER tags model – numpy.ndarray of weights use_loss (boolean) – use loss-augmented inference with Hamming loss if True $$K$$ highest scores and the corresponding label sequences

## Visual Object Localization¶

casimir.data.localization.create_loc_ifo_from_data(obj_class, label_file, features_dir, dimension=2304, smoothing_coefficient=None, num_highest_scores=5)

Create a smoothed incremental first order oracle for train and validation sets for Pascal VOC 2007 given candidate bounding boxes and features.

Parameters: obj_class – Name of object class. label_file – Pickled file with candidate bounding boxes and their IoUs with ground truth. features_dir – Directory with feature representation of candidate bounding boxes. Each file is stored as {image-ID}_{obj-class}.npy, where image-ID is the six digit image ID number. dimension – Dimension of feature representation. Default is 2304, a hard-coded value. smoothing_coefficient – Smoothing coefficient to initialize Smoothed IFOs. Default None. num_highest_scores – The parameter $$K$$ used by the top-K inference algorithm. Default 5. Train, dev and test Smoothed IFOs. Dev (test) IFO is None if dev (test) file is None.
class casimir.data.localization.LocalizationIfo(voc_dataset, smoothing_coefficient=None, num_highest_scores=10)

Create the smoothed IFO object for the structural hinge loss object localization with Pascal VOC.

Supports both non-smooth and $$\ell_2$$ smoothed versions of the structural hinge loss but not entropy smoothing.

Parameters: voc_dataset – reader.VocDataset object that supports __len__ and __getitem__ methods. smoothing_coefficient – The amount of smoothing, $$\mu$$. num_highest_scores – The value $$K$$ for top-$$K$$ inference.
evaluation_function(model)

Return average IoU, localization accuracy and average precision.

function_value(model, idx)

Return the pair $$\big( f_i(w), f_{i, \mu}(w) \big)$$. If smoothing_coefficient is None, i.e., no smoothing, simply return $$f_i(w)$$, where $$i$$ represents the index idx.

gradient(model, idx)

Return that gradient $$\nabla f_{i, \mu}(w)$$ if smoothing_coefficient is not None or $$\nabla f_i(w)$$ if smoothing_coefficient is None.

class casimir.data.localization.VocDataset(obj_class, label_file, feature_dir, data_type, num_bboxes_per_image=1000, dim=2304)

Store a set of images of Pascal VOC 2007 for image localization. Supports __len__ and __getitem__.

Each image is assumed to contain only one object of the class of interest (it may contain other classes).

Apart from the images and labels of Pascal VOC 2007, this class also requires a set of candidate bounding boxes to contain this class (e.g., from the output of selective search) and the IoU (intersection over union) of each candidate bounding box with the true bounding box, as well as features of the bounding box.

The candidate boxes and their feature representation are directly loaded from disk.

Parameters: obj_class – Name of object class. label_file – Path to the pickle file with labels and bounding boxes. feature_dir – Directory with features. Each file is stored as {image-ID}_{obj-class}.npy, where image-ID is the six digit image ID number. data_type – 'train' or 'val' num_bboxes_per_image – Number of bounding boxes loaded per image. Default 1000. dim – Dimensionality of features. Default is 2304.

## Extending to new tasks and datasets¶

The framework of IFOs decouples the optimization from the data and loss function used, as captured by the figure below.

In order to define a new incremental first order oracle, one must override the class casimir.optim.IncrementalFirstOrderOracle or the class casimir.optim.SmoothedIncrementalFirstOrderOracle. See the documentation of these classes for more details.

See IFOs for classification or for structural support vector machines for named entity recognition and visual object localization for reference on how this is done.