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

Ideally, we would be at a point where prediction and label can be removed from the example object by the time the API is ready. However, in case we don't get there let's flesh out how things are right now.

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

Features

vw_status example_get_feature_space_indices(const vw_example*, const unsigned char** indices, int* length);
// invalidates pointers
vw_status example_push_feature_space_index(vw_example*, int value);
// invalidates pointers
vw_status example_remove_feature_space_index(vw_example*, int index);

vw_status example_get_feature_space_copy(const vw_example*, int index, vw_feature_space*);
vw_status example_assign_feature_space(vw_example*, int index, const vw_feature_space*);

vw_status feature_space_copy(const vw_feature_space*, vw_feature_space*);

vw_status allocate_feature_space(vw_feature_space**);
vw_status deallocate_feature_space(vw_feature_space*);

vw_status feature_space_get_features(vw_feature_space*, uint64_t** ft_indices, float** ft_values, int* length);
// invalidates pointers
vw_status feature_space_push_feature(vw_feature_space*, uint64_t ft_index, float ft_value);
// invalidates pointers
vw_status feature_space_remove_feature(vw_feature_space*, int index);

Prediction

NOTE: Further higher level objects are required here.

vw_status label_scalar(void* label, float*);
vw_status label_prob(void* label, float*);
vw_status label_scalars(void* scalars, float*, int* length);
vw_status label_action_scores(void* label, const c_action_score**, int length);
vw_status label_action_probs(void* label, const c_action_score**, int length);
vw_status label_multiclass(void* label, uint32_t*);
vw_status label_multilabels(void* label, const uint32_t**, int length);
vw_status label_decision_scores(void* label, const vw_decision_scores**);

vw_status decion_scores_length(const vw_decision_scores* label, int* length);
vw_status decion_scores_get(vw_decision_scores* label, int index, const c_action_score**, int length);

Label

NOTE: Further higher level objects are required here.

 vw_status allocate_simple_label(vw_simple_label**);
  vw_status deallocate_simple_label(vw_simple_label*);

  vw_status simple_label_get_label(vw_simple_label*, float*);
  vw_status simple_label_set_label(vw_simple_label*, float);
  vw_status simple_label_get_weight(vw_simple_label*, float*);
  vw_status simple_label_set_weight(vw_simple_label*, float);
  vw_status simple_label_get_initial(vw_simple_label*, float*);
  vw_status simple_label_set_initial(vw_simple_label*, float);

  vw_status allocate_multiclass_label(vw_multiclass_label**);
  vw_status deallocate_multiclass_label(vw_multiclass_label*);
  vw_status multiclass_label_get_label(vw_multiclass_label*, uint32_t*);
  vw_status multiclass_label_set_label(vw_multiclass_label*, uint32_t);
  vw_status multiclass_label_get_weight(vw_multiclass_label*, float*);
  vw_status multiclass_label_set_weight(vw_multiclass_label*, float);

  vw_status allocate_cs_label(vw_cs_label**);
  vw_status deallocate_cs_label(vw_cs_label*);
  vw_status cs_label_get_length(vw_cs_label*, int*);
  vw_status cs_label_get_item(
      vw_cs_label*, int index, float* x, uint32_t* class_index, float* partial_prediction, float* wap_value);
  vw_status cs_label_set_item(
      vw_cs_label*, int index, float x, uint32_t class_index, float partial_prediction, float wap_value);
  vw_status cs_label_push_item(vw_cs_label*, float x, uint32_t class_index, float partial_prediction, float wap_value);
  vw_status cs_label_remove_item(vw_cs_label*, int index);

  vw_status allocate_cb_label(vw_cb_label**);
  vw_status deallocate_cb_label(vw_cb_label*);
  vw_status cb_label_get_length(vw_cb_label*, int*);
  vw_status cb_label_get_weight(vw_cb_label*, float*);
  vw_status cb_label_set_weight(vw_cb_label*, float);
  vw_status cb_label_get_item(
      vw_cb_label*, int index, float* cost, uint32_t* action, float* probability, float* partial_prediction);
  vw_status cb_label_set_item(
      vw_cb_label*, int index, float cost, uint32_t action, float probability, float partial_prediction);
  vw_status cb_label_push_item(vw_cb_label*, float cost, uint32_t action, float probability, float partial_prediction);
  vw_status cb_label_remove_item(vw_cb_label*, int index);

  vw_status allocate_ccb_label(vw_ccb_label**);
  vw_status deallocate_ccb_label(vw_ccb_label*);
  vw_status ccb_label_get_type(vw_ccb_label*, uint8_t* type);
  vw_status ccb_label_set_type(vw_ccb_label*, uint8_t type);
  vw_status ccb_label_get_weight(vw_ccb_label*, float* weight);
  vw_status ccb_label_set_weight(vw_ccb_label*, float weight);
  vw_status ccb_label_get_explicit_included_actions(const vw_ccb_label*, uint32_t** indices, int* length);
  vw_status ccb_label_push_explicit_included_actions(vw_example*, uint32_t value);
  vw_status ccb_label_remove_explicit_included_actions(vw_example*, int index);

  vw_status allocate_ccb_outcome(vw_ccb_outcome**);
  vw_status deallocate_ccb_outcome(vw_ccb_outcome*);
  // may be nullptr
  vw_status ccb_label_get_outcome(vw_ccb_label*, vw_ccb_outcome** outcome);
  // may be nullptr
  vw_status ccb_label_set_outcome(vw_ccb_label*, vw_ccb_outcome* outcome);
  vw_status ccb_outcome_get_cost(vw_ccb_outcome*, float* cost);
  vw_status ccb_outcome_set_cost(vw_ccb_outcome*, float cost);
  vw_status ccb_outcome_get_length(vw_ccb_outcome*, int*);
  vw_status ccb_outcome_get_item(vw_ccb_outcome*, int index, uint32_t* action, float* score);
  vw_status ccb_outcome_set_item(vw_ccb_outcome*, int index, uint32_t action, float score);
  vw_status ccb_outcome_push_item(vw_ccb_outcome*, uint32_t action, float score);
  vw_status ccb_outcome_remove_item(vw_ccb_outcome*, int index);

  vw_status allocate_slates_label(vw_slates_label**);
  vw_status deallocate_slates_label(vw_slates_label*);
  vw_status slates_label_get_type(vw_slates_label*, uint8_t* type);
  vw_status slates_label_set_type(vw_slates_label*, uint8_t type);
  vw_status slates_label_get_weight(vw_slates_label*, float* weight);
  vw_status slates_label_set_weight(vw_slates_label*, float weight);
  vw_status slates_label_get_cost(vw_slates_label*, float* cost);
  vw_status slates_label_set_cost(vw_slates_label*, float cost);
  vw_status slates_label_get_labeled(vw_slates_label*, bool* labeled);
  vw_status slates_label_set_labeled(vw_slates_label*, bool labeled);
  vw_status slates_label_get_slot_id(vw_slates_label*, uint32_t* slot_id);
  vw_status slates_label_set_slot_id(vw_slates_label*, uint32_t slot_id);
  vw_status slates_label_get_length(vw_slates_label*, int*);
  vw_status slates_label_get_item(vw_slates_label*, int index, uint32_t* action, float* score);
  vw_status slates_label_set_item(vw_slates_label*, int index, uint32_t action, float score);
  vw_status slates_label_push_item(vw_slates_label*, uint32_t action, float score);
  vw_status slates_label_remove_item(vw_slates_label*, int index);

  vw_status allocate_cb_eval_label(vw_cb_eval_label**);
  vw_status deallocate_cb_eval_label(vw_cb_eval_label*);
  vw_status cb_eval_label_get_cb_label(vw_cb_eval_label*, vw_cb_label* cb_label);
  vw_status cb_eval_label_set_cb_label(vw_cb_eval_label*, vw_cb_label cb_label);
  vw_status cb_eval_label_get_action(vw_cb_eval_label*, uint32_t* action);
  vw_status cb_eval_label_set_action(vw_cb_eval_label*, uint32_t action);

  vw_status allocate_multilabels_label(vw_multilabels_label**);
  vw_status deallocate_multilabels_label(vw_multilabels_label*);
  vw_status multilabels_label_get(vw_multilabels_label*, uint32_t** multilabels, int* length);
  vw_status multilabels_label_push(vw_multilabels_label*, uint32_t value);
  vw_status multilabels_label_remove(vw_multilabels_label*, int index);

Interactions Cut from API v1

Other Metadata

vw_status example_get_feature_offset(const vw_example*, int* feature_offset);
vw_status example_set_feature_offset(vw_example*, int feature_offset );

vw_status example_get_tag(const vw_example*, const char** tag);
vw_status example_set_tag(vw_example*, const char* tag, int length);

vw_status example_get_weight(const vw_example*, float* weight);
vw_status example_set_weight(vw_example*, float weight);
ErrorCode set_example_weight(example*, float tag);