Commit a67b3634 authored by Thomas Purcell's avatar Thomas Purcell
Browse files

Update docstrings for feature creation step for the python API

parent f1d1fc42
......@@ -74,27 +74,27 @@ public:
const bool set_val=true
);
#ifdef PY_BINDINGS
// DocString: feat_node_init_list
// DocString: feat_node_init_arr
/**
* @brief Constructs a feature node using numpy arrays (cpp definition in "python/feature_creation/FeatureNode.cpp)
* @brief Constructs a feature node using numpy arrays (cpp definition in python/feature_creation/FeatureNode.cpp)
*
* @param feat_ind index of the feature
* @param expr Expression for the feature
* @param value Value of the feature for each sample
* @param test_value Value of the feature for each test sample
* @param unit Unit of the feature
* @param feat_ind (int) index of the feature
* @param expr (str) Expression for the feature
* @param value (np.ndarray) Value of the feature for each sample
* @param test_value (np.ndarray) Value of the feature for each test sample
* @param unit (Unit) Unit of the feature
*/
FeatureNode(unsigned long int feat_ind, std::string expr, np::ndarray value, np::ndarray test_value, Unit unit);
// DocString: feat_node_init_arr
// DocString: feat_node_init_list
/**
* @brief Constructs a feature node using Python lists (cpp definition in "python/feature_creation/FeatureNode.cpp)
* @brief Constructs a feature node using Python lists (cpp definition in python/feature_creation/FeatureNode.cpp)
*
* @param feat_ind index of the feature
* @param expr Expression for the feature
* @param value Value of the feature for each sample
* @param test_value Value of the feature for each test sample
* @param unit Unit of the feature
* @param feat_ind (int) index of the feature
* @param expr (str) Expression for the feature
* @param value (list) Value of the feature for each sample
* @param test_value (list) Value of the feature for each test sample
* @param unit (Unit) Unit of the feature
*/
FeatureNode(unsigned long int feat_ind, std::string expr, py::list value, py::list test_value, Unit unit);
#endif
......@@ -147,17 +147,13 @@ public:
// DocString: feat_node_x_in_expr
/**
* @brief Get the list of feature expressions
* @return vector storing the expressions for all primary features that show up in feature in the order they appear in the postfix notation
* @brief A vector storing the expressions for all primary features in the order they appear in the postfix expression
*/
virtual inline std::vector<std::string> get_x_in_expr_list() const {return std::vector<std::string>(1, _expr);}
// DocString: feat_node_n_leaves
/**
* @brief return the number of leaves in the feature
*
* @param cur_n_leaves The current number of primary features that are inside the feature
* @return total number of leaves of the binary expression tree
* @brief Get the number of primary features (non-unique) this feature contains (The number of leaves of the Binary Expression Tree)
*/
virtual inline int n_leaves(int cur_n_leaves = 0) const {return cur_n_leaves + 1;}
......@@ -171,13 +167,13 @@ public:
// DocString: feat_node_expr_const
/**
* @brief Get the string expression used to represent the primary feature
* @brief Get the expression for the feature (From root node down)
*/
inline std::string expr()const{return _expr;}
// DocString: feat_node_latex_expr
/**
* @brief Get the latexified expression for the overall feature (From root node down)
* @brief Get the valid LaTeX expression that represents the feature
*/
inline std::string get_latex_expr() const {return str_utils::latexify(_expr);}
......@@ -188,21 +184,23 @@ public:
inline Unit unit() const {return _unit;}
/**
* @brief Get the training data of the feature
* @brief An array containing the values of the training set samples for the feature
*/
inline std::vector<double> value() const {return _value;}
/**
* @brief Get the test data for the feature
* @brief An array containing the values of the test set samples for the feature
*/
inline std::vector<double> test_value() const {return _test_value;}
// DocString: feat_node_set_value
/**
* @brief Set the values of the training data for the feature inside of the value storage arrays
* @brief Set the value of all training samples for the feature inside the central data storage array
*
* @param offset(int) Key to determine which part of the temporary storage array to look into
* @param for_comp(bool) If true then the evaluation is for comparing features
* @param offset (int) Where the current node is in the binary expression tree relative to other nodes at the same depth
* @param for_comp(bool) If true then the evaluation is used for comparing features
*/
inline void set_value(int offset=-1, const bool for_comp=false) const
{
......@@ -211,10 +209,10 @@ public:
// DocString: feat_node_set_test_value
/**
* @brief Set the values of the test data for the feature inside of the value storage arrays
* @brief Set the value of all test samples for the feature inside the central data storage array
*
* @param offset(int) Key to determine which part of the temporary storage array to look into
* @param for_comp(bool) If true then the evaluation is for comparing features
* @param offset (int) Where the current node is in the binary expression tree relative to other nodes at the same depth
* @param for_comp(bool) If true then the evaluation is used for comparing features
*/
inline void set_test_value(int offset=-1, const bool for_comp=false) const
{
......@@ -226,7 +224,9 @@ public:
// DocString: feat_node_is_nan
/**
* @brief Check if the feature contains NaN
* @brief Check if the feature has a NaN value in it
*
* @return True if one of the values of the feature is a NaN
*/
inline bool is_nan() const
{
......@@ -235,7 +235,9 @@ public:
// DocString: feat_node_is_const
/**
* @brief Check if feature is constant
* @brief Check if feature is constant for one of the tasks
*
* @return True if the feature is constant for all samples in any task
*/
bool is_const() const;
......@@ -247,8 +249,8 @@ public:
/**
* @brief The pointer to where the feature's training data is stored
*
* @param offset(int) Key to determine which part of the temporary storage array to look into
* @param for_comp(bool) If true then the evaluation is for comparing features
* @param offset (int) Where the current node is in the binary expression tree relative to other nodes at the same depth
* @param for_comp (bool) If true then the evaluation is used for comparing features
*/
virtual inline double* value_ptr(int offset=-1, const bool for_comp=false) const
{
......@@ -258,8 +260,8 @@ public:
/**
* @brief The pointer to where the feature's test data is stored
*
* @param offset(int) Key to determine which part of the temporary storage array to look into
* @param for_comp(bool) If true then the evaluation is for comparing features
* @param offset (int) Where the current node is in the binary expression tree relative to other nodes at the same depth
* @param for_comp (bool) If true then the evaluation is used for comparing features
*/
virtual inline double* test_value_ptr(int offset=-1, const bool for_comp=false) const
{
......@@ -268,9 +270,8 @@ public:
// DocString: feat_node_rung
/**
* @brief return the rung of the feature
* @brief return the rung of the feature (Height of the binary expression tree + 1)
*
* @param cur_rung The rung current rung of the feature tree (used to recursively calculate rung)
*/
inline int rung(int cur_rung = 0) const {return cur_rung;}
......@@ -318,18 +319,17 @@ public:
return str_utils::matlabify(_expr);
}
//DocString: feat_node_nfeats
// DocString: feat_node_nfeats
/**
* @brief Number of features used for an operator node
* @return the number of features for an operator node
*/
inline int n_feats() const {return 0;}
//DocString: feat_node_feat
// DocString: feat_node_feat
/**
* @brief Return the ind node_ptr in the operator node's feat list
*
* @param ind the index of the node to access
* @param ind (int) the index of the node to access
* @return the ind feature in feature_list
*/
inline node_ptr feat(const int ind) const
......@@ -379,7 +379,7 @@ public:
*/
inline void set_parameters(const double* params){};
//DocString: feat_node_get_params
// DocString: feat_node_get_params
/**
* @brief Solve the non-linear optimization to set the parameters
* @details Fits the data points from _feats->value_ptr and prop to get the parameters for the feature
......@@ -392,49 +392,49 @@ public:
* @brief returns the number of parameters for this feature
*
* @param n_cur the current number of parameters for the feature
* @param depth the current depth of the node on the Binary expression tree
* @param depth the current depth of the node on the binary expression tree
* @return the number of parameters (_params.size())
*/
inline int n_params(int n_cur=0, int depth = 1) const {return n_cur;};
/**
* @brief Set the values of the training data for the feature inside of the value storage arrays
* @brief Set the value of all test samples for the feature inside the central data storage array
*
* @param offset(int) Key to determine which part of the temporary storage array to look into
* @param params pointer to the parameter values
* @param for_comp(bool) If true then the evaluation is for comparing features
* @param depth the current depth of the node on the Binary expression tree
* @param offset (int) Where the current node is in the binary expression tree relative to other nodes at the same depth
* @param params pointer to the non-linear parameter values
* @param for_comp(bool) If true then the evaluation is used for comparing features
* @param depth the current depth of the node on the binary expression tree
*/
inline void set_value(const double* params, int offset=-1, const bool for_comp=false, const int depth=1) const {set_value(offset);};
/**
* @brief The pointer to where the feature's training data is stored
*
* @param offset(int) Key to determine which part of the temporary storage array to look into
* @param params pointer to the parameter values
* @param for_comp(bool) If true then the evaluation is for comparing features
* @param depth the current depth of the node on the Binary expression tree
* @param offset (int) Where the current node is in the binary expression tree relative to other nodes at the same depth
* @param params pointer to the non-linear parameter values
* @param for_comp (bool) If true then the evaluation is used for comparing features
* @param depth the current depth of the node on the binary expression tree
* @returns the pointer to the feature's data
*/
inline double* value_ptr(const double* params, int offset=-1, const bool for_comp=false, const int depth=1) const {return value_ptr(offset);};
/**
* @brief Set the values of the test data for the feature inside of the value storage arrays
* @brief Set the value of all test samples for the feature inside the central data storage array
*
* @param offset(int) Key to determine which part of the temporary storage array to look into
* @param params pointer to the parameter values
* @param for_comp(bool) If true then the evaluation is for comparing features
* @param depth the current depth of the node on the Binary expression tree
* @param offset (int) Where the current node is in the binary expression tree relative to other nodes at the same depth
* @param params pointer to the non-linear parameter values
* @param for_comp (bool) If true then the evaluation is used for comparing features
* @param depth the current depth of the node on the binary expression tree
*/
inline void set_test_value(const double* params, int offset=-1, const bool for_comp=false, const int depth=1) const {set_test_value(offset);};
/**
* @brief The pointer to where the feature's test data is stored
*
* @param offset(int) Key to determine which part of the temporary storage array to look into
* @param params pointer to the parameter values
* @param for_comp(bool) If true then the evaluation is for comparing features
* @param depth the current depth of the node on the Binary expression tree
* @param offset (int) Where the current node is in the binary expression tree relative to other nodes at the same depth
* @param params pointer to the non-linear parameter values
* @param for_comp (bool) If true then the evaluation is used for comparing features
* @param depth the current depth of the node on the binary expression tree
* @returns the pointer to the feature's data
*/
inline double* test_value_ptr(const double* params, int offset=-1, const bool for_comp=false, const int depth=1) const {return test_value_ptr(offset);};
......@@ -443,16 +443,16 @@ public:
* @brief The expression of the feature
*
* @param params parameter values for non-linear operations
* @param depth the current depth of the node on the Binary expression tree
* @param depth the current depth of the node on the binary expression tree
* @return feature expression
*/
inline std::string expr(const double* params, const int depth = 1) const {return _expr;};
/**
* @brief Get the latexified expression for the overall feature (From root node down)
* @brief Get the valid LaTeX expression that represents the feature
*
* @param params parameter values for non-linear operations
* @param depth the current depth of the node on the Binary expression tree
* @param depth the current depth of the node on the binary expression tree
* @return the latexified expression
*/
inline std::string get_latex_expr(const double* params, const int depth=1) const {return str_utils::latexify(_expr);}
......@@ -462,7 +462,7 @@ public:
* @brief Get the string that corresponds to the code needed to evaluate the node in matlab
*
* @param params parameter values for non-linear operations
* @param depth the current depth of the node on the Binary expression tree
* @param depth the current depth of the node on the binary expression tree
* @return The matlab code for the feature
*/
virtual inline std::string matlab_fxn_expr(const double* params, const int depth=1) const
......@@ -476,7 +476,7 @@ public:
* @param lb pointer to the lower bounds data
* @param ub pointer to the upper bounds data
* @param from_parent How many parameters are between the start of this node's parameters and its parent
* @param depth the current depth of the node on the Binary expression tree
* @param depth the current depth of the node on the binary expression tree
*/
inline void set_bounds(double* lb, double* ub, const int depth=1) const {};
......@@ -484,7 +484,7 @@ public:
* @brief Set the bounds for the nl parameterization
*
* @param params pointer to the parameters vector
* @param depth the current depth of the node on the Binary expression tree
* @param depth the current depth of the node on the binary expression tree
*/
virtual void initialize_params(double* params, const int depth = 1) const {};
......
......@@ -76,7 +76,7 @@ public:
* @param matlab_fxn_expr The code to evaluate the feature in matlab
* @param value Value of the feature for each sample
* @param test_value Value of the feature for each test sample
* @param x_in_expr_list //!< vector storing the expressions for all primary features that show up in feature in the order they appear in the postfix notation
* @param x_in_expr_list vector storing the expressions for all primary features that show up in feature in the order they appear in the postfix notation
* @param unit Unit of the feature
*/
ModelNode(
......@@ -96,7 +96,7 @@ public:
/**
* @brief Copy constructor from general node_ptr
*
* @param in_node Node to be copied
* @param in_node (Node) Node to be copied
*/
ModelNode(node_ptr in_node);
......@@ -193,17 +193,14 @@ public:
// DocString: model_node_x_in_expr
/**
* @brief get the list of feature expressions for each of the leaves
* @return Vector containing the expression for each leaf in the binary expression tree
* @brief A vector storing the expressions for all primary features in the order they appear in the postfix expression
*/
inline std::vector<std::string> get_x_in_expr_list() const {return _x_in_expr_list;}
// DocString: model_node_n_leaves
/**
* @brief return the number of leaves in the feature
* @brief The number of primary features (non-unique) this feature contains (The number of leaves of the Binary Expression Tree)
*
* @param cur_n_leaves The current number of primary features that are inside the feature
* @return total number of leaves of the binary expression tree
*/
inline int n_leaves(int n_cur_leaves = 0) const {return _n_leaves;}
......@@ -239,31 +236,35 @@ public:
// DocString: model_node_set_value
/**
* @brief Set the values of the training data for the feature inside of the value storage arrays
* @brief Set the value of all training samples for the feature inside the central data storage array
*
* @param offset(int) Key to determine which part of the temporary storage array to look into
* @param for_comp(bool) If true then the evaluation is for comparing features
* @param offset (int) Where the current node is in the binary expression tree relative to other nodes at the same depth
* @param for_comp(bool) If true then the evaluation is used for comparing features
*/
inline void set_value(int offset=-1, const bool for_comp=false) const {return;}
// DocString: model_node_set_test_value
/**
* @brief Set the values of the test data for the feature inside of the value storage arrays
* @brief Set the value of all test samples for the feature inside the central data storage array
*
* @param offset(int) Key to determine which part of the temporary storage array to look into
* @param for_comp(bool) If true then the evaluation is for comparing features
* @param offset (int) Where the current node is in the binary expression tree relative to other nodes at the same depth
* @param for_comp(bool) If true then the evaluation is used for comparing features
*/
inline void set_test_value(int offset=-1, const bool for_comp=false) const {return;}
// DocString: model_node_is_nan
/**
* @brief Check if the feature contains NaN
* @brief Check if the feature has a NaN value in it
*
* @return True if one of the values of the feature is a NaN
*/
inline bool is_nan() const {return false;}
// DocString: model_node_is_const
/**
* @brief Check if feature is constant
* @brief Check if feature is constant for one of the tasks
*
* @return True if the feature is constant for all samples in any task
*/
inline bool is_const() const {return false;}
......@@ -275,24 +276,24 @@ public:
/**
* @brief The pointer to where the feature's training data is stored
*
* @param offset(int) Key to determine which part of the temporary storage array to look into
* @param for_comp(bool) If true then the evaluation is for comparing features
* @param offset (int) Where the current node is in the binary expression tree relative to other nodes at the same depth
* @param for_comp (bool) If true then the evaluation is used for comparing features
*/
inline double* value_ptr(int offset=-1, const bool for_comp=false){return _value.data();}
/**
* @brief The pointer to where the feature's test data is stored
*
* @param offset(int) Key to determine which part of the temporary storage array to look into
* @param for_comp(bool) If true then the evaluation is for comparing features
* @param offset (int) Where the current node is in the binary expression tree relative to other nodes at the same depth
* @param for_comp (bool) If true then the evaluation is used for comparing features
*/
inline double* test_value_ptr(int offset=-1, const bool for_comp=false){return _test_value.data();}
/**
* @brief The pointer to where the feature's training data is stored
*
* @param offset(int) Key to determine which part of the temporary storage array to look into
* @param for_comp(bool) If true then the evaluation is for comparing features
* @param offset (int) Where the current node is in the binary expression tree relative to other nodes at the same depth
* @param for_comp (bool) If true then the evaluation is used for comparing features
*/
inline double* value_ptr(int offset=-1, const bool for_comp=false) const
{
......@@ -303,8 +304,8 @@ public:
/**
* @brief The pointer to where the feature's test data is stored
*
* @param offset(int) Key to determine which part of the temporary storage array to look into
* @param for_comp(bool) If true then the evaluation is for comparing features
* @param offset (int) Where the current node is in the binary expression tree relative to other nodes at the same depth
* @param for_comp (bool) If true then the evaluation is used for comparing features
*/
inline double* test_value_ptr(int offset=-1, const bool for_comp=false) const
{
......@@ -314,9 +315,8 @@ public:
// DocString: model_node_rung
/**
* @brief return the rung of the feature
* @brief return the rung of the feature (Height of the binary expression tree + 1)
*
* @param cur_rung(int) The rung current rung of the feature tree (used to recursively calculate rung)
*/
inline int rung(int cur_rung = 0) const {return _rung;}
......@@ -341,7 +341,7 @@ public:
// DocString: model_node_latex_expr
/**
* @brief Get the latexified expression for the overall feature (From root node down)
* @brief Get the valid LaTeX expression that represents the feature
*/
inline std::string get_latex_expr() const {return _latex_expr.substr(1, _latex_expr.size() - 2);}
......@@ -376,11 +376,65 @@ public:
void update_div_mult_leaves(std::map<std::string, double>& div_mult_leaves, const double fact, double& expected_abs_tot) const;
#ifdef PY_BINDINGS
// DocString: model_node_init_list
/**
* @brief Constructs a feature node
*
* @param feat_ind (int) index of the feature
* @param rung (int) the rung of the feature
* @param expr (str) Expression for the feature
* @param latex_expr (str) The LaTeXified expression for the feature
* @param matlab_fxn_expr (str) The code to evaluate the feature in matlab
* @param value (list) Value of the feature for each sample
* @param test_value (list) Value of the feature for each test sample
* @param x_in_expr_list (list) //!< vector storing the expressions for all primary features that show up in feature in the order they appear in the postfix notation
* @param unit (Unit) Unit of the feature
*/
ModelNode(
const unsigned long int feat_ind,
const unsigned long int rung,
const std::string expr,
const std::string latex_expr,
const std::string expr_postfix,
const std::string matlab_fxn_expr,
const py::list value,
const py::list test_value,
const py::list x_in_expr_list,
const Unit unit
);
// DocString: model_node_init_arr
/**
* @brief Constructs a feature node
*
* @param feat_ind (int) index of the feature
* @param rung (int) the rung of the feature
* @param expr (str) Expression for the feature
* @param latex_expr (str) The LaTeXified expression for the feature
* @param matlab_fxn_expr (str) The code to evaluate the feature in matlab
* @param value (np.ndarray) Value of the feature for each sample
* @param test_value (np.ndarray) Value of the feature for each test sample
* @param x_in_expr_list (list) //!< vector storing the expressions for all primary features that show up in feature in the order they appear in the postfix notation
* @param unit (Unit) Unit of the feature
*/
ModelNode(
const unsigned long int feat_ind,
const unsigned long int rung,
const std::string expr,
const std::string latex_expr,
const std::string expr_postfix,
const std::string matlab_fxn_expr,
const np::ndarray value,
const np::ndarray test_value,
const py::list x_in_expr_list,
const Unit unit
);
// DocString: model_node_eval_arr
/**
* @brief Evaluate the model for a new point
*
* @param x_in The data point to evaluate the model (order the same as appending the results of _feats[nn]->get_x_in_expr_list() for all feature)
* @param x_in (np.ndarray) The data point to evaluate the model (order the same as appending the results of _feats[nn]->get_x_in_expr_list() for all feature)
* @return The prediction of the model for a given data point
*/
inline double eval_py(np::ndarray x_in){return eval(python_conv_utils::from_ndarray<double>(x_in));}
......@@ -389,7 +443,7 @@ public:
/**
* @brief Evaluate the model for a new point
*
* @param x_in The data point to evaluate the model (order the same as appending the results of _feats[nn]->get_x_in_expr_list() for all feature)
* @param x_in (list) The data point to evaluate the model (order the same as appending the results of _feats[nn]->get_x_in_expr_list() for all feature)
* @return The prediction of the model for a given data point
*/
inline double eval_py(py::list x_in){return eval(python_conv_utils::from_list<double>(x_in));}
......@@ -398,7 +452,7 @@ public:
/**
* @brief Evaluate the model for a new point
*
* @param x_in_dct Dictionary describing the new point (\"feature expr\": value)
* @param x_in (dict) Dictionary describing the new point (\"feature expr\": value)
* @return The prediction of the model for a given data point
*/
inline double eval_py(py::dict x_in){return eval(python_conv_utils::from_dict<std::string, double>(x_in));}
......@@ -407,7 +461,7 @@ public:
/**
* @brief Evaluate the model for a set of new points
*
* @param x_in The set data for a set of new data points (size of n_feature x n_points, and order the same as appending the results of _feats[nn]->get_x_in_expr_list() for all feature)
* @param x_in (np.ndarray) The set data for a set of new data points (size of n_feature x n_points, and order the same as appending the results of _feats[nn]->get_x_in_expr_list() for all feature)
* @return The prediction of the model for a given data point
*/
np::ndarray eval_many_py(np::ndarray x_in);
......@@ -416,7 +470,7 @@ public:
/**
* @brief Evaluate the model for a set of new points
*
* @param x_in_dct The set of data points to evaluate the model. Keys must be strings representing feature expressions and vectors must be the same length
* @param x_in (dict) The set of data points to evaluate the model. Keys must be strings representing feature expressions and vectors must be the same length
* @return The prediction of the model for a given data point
*/
np::ndarray eval_many_py(py::dict x_in);
......@@ -434,7 +488,7 @@ public:
* @brief Get the string that corresponds to the code needed to evaluate the node in matlab
*
* @param params parameter values for non-linear operations
* @param depth the current depth of the node on the Binary expression tree
* @param depth the current depth of the node on the binary expression tree
* @return The matlab code for the feature
*/
inline std::string matlab_fxn_expr(const double* params, const int depth=1) const
......
......@@ -126,35 +126,33 @@ public:
// DocString: node_x_in_expr
/**
* @brief Get the list of feature expressions
* @return vector storing the expressions for all primary features that show up in feature in the order they appear in the postfix notation
* @brief A vector storing the expressions for all primary features in the order they appear in the postfix expression
*/
virtual std::vector<std::string> get_x_in_expr_list() const = 0;
// DocString: node_n_leaves
/**
* @brief return the number of leaves in the feature
* @brief The number of primary features (non-unique) this feature contains (The number of leaves of the Binary Expression Tree)
*
* @param cur_n_leaves The current number of primary features that are inside the feature
* @return total number of leaves of the binary expression tree
* @param cur_n_leaves (int) A recurisve counting variable
* @return The number of leaves of the Binary Expression Tree
*/
virtual int n_leaves(const int cur_n_leaves = 0) const = 0;
// DocString: node_reindex_1
/**
* @brief Reindex the feature
* @details re-index the feature to be continuous
* @brief Reset _feat_ind and _arr_ind to ind
*
* @param ind(int) the new feature and array index
* @param ind (int) the new value of _feat_ind and _arr_ind
*/
inline void reindex(const unsigned long int ind){_feat_ind = ind; _arr_ind = ind;}
// DocString: node_reindex_2
/**
* @brief Reindex the feature
* @details re-index the feature to be continuous
* @brief Reset _feat_ind and _arr_ind to feat_ind and arr_ind, respectively
*
* @param ind(int) the new feature and array index
* @param feat_ind (int) the new value of _feat_ind
* @param arr_ind (int) the new value of _arr_ind
*/
inline void reindex(const unsigned long int feat_ind, const unsigned long int arr_ind){_feat_ind = feat_ind; _arr_ind = arr_ind;}
......@@ -166,13 +164,13 @@ public:
*/
virtual unsigned long long sort_score(unsigned int max_ind) const = 0;