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

ErrorCode get_example_feature_space_indices(const example*, int** indices);
ErrorCode get_example_feature_space_indices_length(const example*, int* length);
ErrorCode set_example_feature_space_index(example*, int index, int value);
ErrorCode push_example_feature_space_index(example*, int value);
ErrorCode remove_example_feature_space_index(example*, int index);

typedef feature_space void;
ErrorCode get_example_feature_space(const example*, int index, feature_space**);
ErrorCode set_example_feature_space(example*, int index, feature_space*);
ErrorCode allocate_example_feature_space(feature_space**);
ErrorCode deallocate_example_feature_space(feature_space*);

ErrorCode get_example_feature_space_values(const feature_space*, float** values);
ErrorCode get_example_feature_space_values_length(const feature_space*, int* length);
ErrorCode set_example_feature_space_values_index(feature_space*, int index, float value);
ErrorCode push_example_feature_space_values_index(feature_space*, float value);
ErrorCode remove_example_feature_space_values_index(feature_space*, int index);

ErrorCode get_example_feature_space_indices(const feature_space*, int** values);
ErrorCode get_example_feature_space_indices_length(const feature_space*, int* length);
ErrorCode set_example_feature_space_indices_index(feature_space*, int index, int value);
ErrorCode push_example_feature_space_indices_index(feature_space*, int value);
ErrorCode remove_example_feature_space_indices_index(feature_space*, int index);

Prediction

NOTE: Further higher level objects are required here.

enum prediction_type
{
    scalar,
    scalars,
    a_s,
    decision_scores,
    multiclass,
    multilabels,
    prob
}

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

Label

NOTE: Further higher level objects are required here.

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

ErrorCode get_label(example*, label_type type, void** out_label);
ErrorCode set_label(example*, label_type type, void* label);

Interactions

typedef void interactions;

ErrorCode get_interactions(const example*, interactions** out_interactions);
ErrorCode set_interactions(example*, interactions* interactions);

ErrorCode get_interactions_length(const interactions*, int* out_length);
ErrorCode get_interaction(const interactions*, char** interaction);
ErrorCode set_interaction(interactions*, const char* interaction);
ErrorCode push_interaction(interactions*, const char* interaction);

Other Metadata

ErrorCode get_example_feature_offset(const example*, int* feature_offset);
ErrorCode set_example_feature_offset(example*, int feature_offset );

ErrorCode get_example_tag(const example*, const char** tag);
ErrorCode set_example_tag(example*, const char* tag);

ErrorCode get_example_weight(const example*, float* tag);
ErrorCode set_example_weight(example*, float tag);