C API Example Manipulation

Current

float get_topic_prediction(example* ec, size_t i);  // i=0 to max topic -1 
float get_label(example* ec); 
float get_importance(example* ec); 
float get_initial(example* ec); 
float get_prediction(example* ec); 
float get_cost_sensitive_prediction(example* ec); 
v_array<float>& get_cost_sensitive_prediction_confidence_scores(example* ec); 
uint32_t* get_multilabel_predictions(example* ec, size_t& len); 
float get_action_score(example* ec, size_t i); 
size_t get_action_score_length(example* ec); 
size_t get_tag_length(example* ec); 
const char* get_tag(example* ec); 
size_t get_feature_number(example* ec); 
float get_confidence(example* ec); 
feature* get_features(vw& all, example* ec, size_t& feature_number); 
void return_features(feature* f); 
void add_constant_feature(vw& all, example* ec); 
void add_label(example* ec, float label, float weight = 1, float base = 0); 

void copy_example_data(bool audit, example*, example*, size_t, void (*copy_label)(void*, void*)); 
void copy_example_metadata(bool audit, example*, example*); 
void copy_example_data(bool audit, example*, example*);  // metadata + features, don't copy the label 
void clear_example_data(example&);                       // don't clear the label 
void move_feature_namespace(example* dst, example* src, namespace_index c); 

Deprecate

TBD

Proposed

TBD

Prediction

enum prediction_type
{
  empty,
  simple,
  multi,
  cs,
  cb,
  ccb,
  slates,
  cb_eval,
  multilabels,
}

ErrorCode get_prediction(prediction_type type, void** out_prediction);
ErrorCode set_prediction(prediction_type type, void* prediction);

Label

enum prediction_type
{
  empty,
  simple,
  multi,
  cs,
  cb,
  ccb,
  slates,
  cb_eval,
  multilabels,
}

ErrorCode get_prediction(prediction_type type, void** out_param);

An example is composed of:

• Features -> map<namespace_index, feature_space>
  • Where feature_space -> hash[], value[]
• Prediction
  • prediction_type
  • prediction_data
• Label
  • label_type
  • label_data
• Metadata:
  • Interactions - required
  • ft_offset - required
  • tag - required
  • Weight - required
  • num_features - maybe expose?
  • total_sum_feat_sq - maybe expose?
  • partial_prediction - maybe expose?
  • loss - maybe expose?
  • example_counter - internal
  • updated_prediction - internal
  • confidence - internal
  • test_only - internal
  • end_pass - internal
  • sorted - internal

Sections: prediction, label, features, interactions, other metadata