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

Update documenation for several files

parent 1d4b68ef
......@@ -870,8 +870,10 @@ void FeatureSpace::sis(std::vector<double>& prop)
_mpi_comm->barrier();
if(_mpi_comm->rank() == 0)
{
std::cout << "Projection time for features generated on the fly: " << omp_get_wtime() - start << " s" << std::endl;
}
}
// Reset scores
std::fill_n(&scores_sel_all[cur_feat], _n_sis_select, 0.0);
......
......@@ -106,6 +106,7 @@ public:
* @param cross_corr_max Maximum cross-correlation used for selecting features
* @param min_abs_feat_val minimum absolute feature value
* @param max_abs_feat_val maximum absolute feature value
* @param max_param_depth the maximum paremterization depths for features
*/
FeatureSpace(
std::shared_ptr<MPI_Interface> mpi_comm,
......@@ -277,7 +278,6 @@ public:
* @param size The size of the data to project over
* @param phi_selected The features that would be selected from the previous rungs
* @param scores_selected The projection scores of the features that would be selected from the previous rungs
* @param scores_comp vector to store temporary score comparisons
*/
void project_generated(double* prop, int size, std::vector<node_ptr>& phi_selected, std::vector<double>& scores_selected);
......@@ -325,6 +325,7 @@ public:
* @param cross_corr_max Maximum cross-correlation used for selecting features
* @param min_abs_feat_val minimum absolute feature value
* @param max_abs_feat_val maximum absolute feature value
* @param max_param_depth the maximum paremterization depths for features
*/
FeatureSpace(
py::list phi_0,
......@@ -360,6 +361,7 @@ public:
* @param cross_corr_max Maximum cross-correlation used for selecting features
* @param min_abs_feat_val minimum absolute feature value
* @param max_abs_feat_val maximum absolute feature value
* @param max_param_depth the maximum paremterization depths for features
*/
FeatureSpace(
py::list phi_0,
......
......@@ -67,8 +67,9 @@ public:
* @param feat_ind index of the feature
* @param expr Expression for the feature
* @param value Value of the feature for each sample
* @param value Value of the feature for each test sample
* @param test_value Value of the feature for each test sample
* @param unit Unit of the feature
* @param set_val if true set the value inside the VALUES_ARR object
*/
FeatureNode(unsigned long int feat_ind, std::string expr, std::vector<double> value, std::vector<double> test_value, Unit unit, bool set_val = true);
#ifdef PY_BINDINGS
......@@ -78,7 +79,7 @@ public:
* @param feat_ind index of the feature
* @param expr Expression for the feature
* @param value Value of the feature for each sample
* @param value Value of the feature for each test sample
* @param test_value Value of the feature for each test sample
* @param unit Unit of the feature
*/
FeatureNode(unsigned long int feat_ind, std::string expr, np::ndarray value, np::ndarray test_value, Unit unit);
......@@ -89,7 +90,7 @@ public:
* @param feat_ind index of the feature
* @param expr Expression for the feature
* @param value Value of the feature for each sample
* @param value Value of the feature for each test sample
* @param test_value Value of the feature for each test sample
* @param unit Unit of the feature
*/
FeatureNode(unsigned long int feat_ind, std::string expr, py::list value, py::list test_value, Unit unit);
......@@ -127,9 +128,19 @@ public:
*/
~FeatureNode();
/**
* @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
*/
virtual inline std::vector<std::string> get_x_in_expr_list(){return std::vector<std::string>(1, _expr);}
virtual inline int n_leaves(int cur_n_leaves = 0){return cur_n_leaves + 1;}
/**
* @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
*/
virtual inline int n_leaves(int cur_n_leaves = 0){return cur_n_leaves + 1;}
// DocString: feat_node_expr_1
/**
......@@ -170,6 +181,7 @@ public:
* @brief Set the values of the training data for the feature inside of the value storage arrays
*
* @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
*/
inline void set_value(int offset=-1, bool for_comp=false)
{
......@@ -181,6 +193,7 @@ public:
* @brief Set the values of the test data for the feature inside of the value storage arrays
*
* @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
*/
inline void set_test_value(int offset=-1, bool for_comp=false)
{
......@@ -211,6 +224,7 @@ 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
*/
inline double* value_ptr(int offset=-1, bool for_comp=false)
{
......@@ -221,6 +235,7 @@ 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
*/
inline double* test_value_ptr(int offset=-1, bool for_comp=false)
{
......@@ -254,6 +269,7 @@ public:
* @details Recursively creates a postfix representation of the string
*
* @param cur_expr The current expression
* @param add_params If true add the parameters
* @return The current postfix expression of the feature
*/
inline void update_postfix(std::string& cur_expr, bool add_params=true)
......@@ -300,10 +316,12 @@ public:
void update_add_sub_leaves(std::map<std::string, int>& add_sub_leaves, int pl_mn, int& expected_abs_tot);
/**
* @brief update the dictionary used to check if
* @details [long description]
* @brief update the dictionary used to check if a mult/div node is valid
*
* @param div_mult_leaves the dictionary used to check if an Mult/Div node is valid
* @param fact Factor used to update leaves (power of the feature)
* @param expected_abs_tot The expected absolute sum of all values in div_mult_leaves
*
* @param add_sub_leaves [description]
*/
void update_div_mult_leaves(std::map<std::string, double>& div_mult_leaves, double fact, double& expected_abs_tot);
......@@ -315,11 +333,16 @@ public:
/**
* @brief Set the non-linear parameters
* @param params The new parameters of the node
* @param check_sz If true check the size of the parameters
*/
inline void set_parameters(std::vector<double> params, bool check_sz=true){};
/**
* @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
* @return the number of parameters (_params.size())
*/
inline int n_params(int n_cur=0, int depth = 1){return n_cur;};
......@@ -329,6 +352,8 @@ public:
*
* @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
*/
inline void set_value(const double* params, int offset=-1, bool for_comp=false, int depth=0){set_value(offset);};
......@@ -337,6 +362,8 @@ public:
*
* @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
* @returns the pointer to the feature's data
*/
inline double* value_ptr(const double* params, int offset=-1, bool for_comp=false, int depth=0){return value_ptr(offset);};
......@@ -346,6 +373,8 @@ public:
*
* @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
*/
inline void set_test_value(const double* params, int offset=-1, bool for_comp=false, int depth=0){set_test_value(offset);};
......@@ -354,6 +383,8 @@ public:
*
* @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
* @returns the pointer to the feature's data
*/
inline double* test_value_ptr(const double* params, int offset=-1, bool for_comp=false, int depth=0){return test_value_ptr(offset);};
......@@ -362,7 +393,7 @@ public:
* @brief The expression of the feature
*
* @param params parameter values for non-linear operations
* @param params parameter values for non-linear operations
* @param depth the current depth of the node on the Binary expression tree
* @return feature expression
*/
inline std::string expr(double* params, int depth = 1){return _expr;};
......@@ -370,7 +401,6 @@ public:
/**
* @brief Get the latexified expression for the overall feature (From root node down)
*
* @param cap string to place in the start/end of the string
* @param params parameter values for non-linear operations
* @param depth the current depth of the node on the Binary expression tree
* @return the latexified expression
......@@ -382,6 +412,8 @@ 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
*/
inline void set_bounds(double* lb, double* ub, int from_parent=2, int depth = 1){};
......@@ -389,7 +421,7 @@ public:
* @brief Calculates the derivative of an operation with respect to the parameters for a given sample
*
* @param params pointer to the parameters
* @param samp_ind sample index number
* @param dfdp pointer to where the feature derivative pointers are located
*/
void param_derivative(const double* params, double* dfdp){}
......@@ -397,7 +429,7 @@ public:
* @brief Get the parameter gradient for non-linear optimization
*
* @param grad pointer to the gradient storage
* @param samp_ind sample index to calculate the gradient for
* @param dfdp pointer to where the feature derivative pointers are located
*/
virtual void gradient(double* grad, double* dfdp)
{
......@@ -408,7 +440,7 @@ public:
* @brief Get the parameter gradient for non-linear optimization
*
* @param grad pointer to the gradient storage
* @param samp_ind sample index to calculate the gradient for
* @param dfdp pointer to where the feature derivative pointers are located
* @param params pointer to the parameters vector
*/
inline void gradient(double* grad, double* dfdp, const double* params){};
......
......@@ -49,9 +49,9 @@ protected:
std::vector<double> _value_svm; //!< Value of the feature converted to a range of -1.0 to 1.0
std::vector<double> _test_value_svm; //!< Value of the feature converted to a range of -1.0 to 1.0
std::vector<fxn_nterms_pair> _fxn_list;
std::vector<fxn_nterms_pair> _fxn_list; //!< list of functions used for evaluating feature values
std::vector<std::string> _x_in_expr_list;
std::vector<std::string> _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
std::string _expr_postfix; //!< postfix expression for the feature
std::string _latex_expr; //!< postfix expression for the feature
......@@ -59,8 +59,7 @@ protected:
double _w_remap_svm; //!< value to remap the w from SVM to real life
int _rung; //!< rung of the feature
int _n_leaves;
int _n_leaves; //!< Total number of primary features of the feature
public:
/**
* @brief Base Constructor
......@@ -75,7 +74,8 @@ public:
* @param rung the rung of the feature
* @param expr Expression for the feature
* @param value Value of the feature for each sample
* @param value Value of the feature for each test 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 unit Unit of the feature
*/
ModelNode(
......@@ -129,30 +129,101 @@ public:
*/
~ModelNode();
/**
* @brief Generate the list of functions used to evaluate the value of this feature for a new data point from the postfix expression
*/
void generate_fxn_list();
/**
* @brief Evaluate the model for a new point
*
* @param x_in pointer to the new data point (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
*/
double eval(double* x_in);
/**
* @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)
* @return The prediction of the model for a given data point
*/
double eval(std::vector<double> x_in);
/**
* @brief Evaluate the model for a new point
*
* @param x_in_dct Dictionary describing the new point ("feature expr": value)
* @return The prediction of the model for a given data point
*/
double eval(std::map<std::string, double> x_in_dct);
/**
* @brief Evaluate the model for a new set of new points
*
* @param x_in a vector of pointers to the set of values for new data points (one pointer per each feature 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 set of data points
*/
std::vector<double> eval(std::vector<double>* x_in);
/**
* @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)
* @return The prediction of the model for a given data point
*/
std::vector<double> eval(std::vector<std::vector<double>> x_in);
std::vector<double> eval(std::map<std::string, std::vector<double>> x_in_dct);
/**
* @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
* @return The prediction of the model for a given data point
*/
std::vector<double> eval(std::map<std::string, std::vector<double>> x_in_dct);
/**
* @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
*/
inline std::vector<std::string> get_x_in_expr_list(){return _x_in_expr_list;}
/**
* @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
*/
inline int n_leaves(int n_cur_leaves = 0){return _n_leaves;}
/**
* @return Value of the feature converted to a range of -1.0 to 1.0
*/
inline std::vector<double> svm_value(){return _value_svm;}
/**
* @return pointer to the start of the vector storing the value of the feature transformed into a range of -1.0 to 1.0
*/
inline double* svm_value_ptr(){return _value_svm.data();}
/**
* @return Value of the test value fo the feature converted to a range of -1.0 to 1.0
*/
inline std::vector<double> svm_test_value(){return _test_value_svm;}
/**
* @return Pointer to the start of the vector storing the test value of the feature converted to a range of -1.0 to 1.0
*/
inline double* svm_test_value_ptr(){return _test_value_svm.data();}
/**
* @return value used to map the b value from SVM from -1.0 to 1.0 range to the real one
*/
inline double remap_b_svm(double w){return w * _b_remap_svm;}
/**
* @return value used to map the w value from SVM from -1.0 to 1.0 range to the real one
*/
inline double remap_w_svm(double w){return w * _w_remap_svm;}
// DocString: model_node_set_value
......@@ -160,6 +231,7 @@ public:
* @brief Set the values of the training data for the feature inside of the value storage arrays
*
* @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
*/
inline void set_value(int offset=-1, bool for_comp=false){return;}
......@@ -168,6 +240,7 @@ public:
* @brief Set the values of the test data for the feature inside of the value storage arrays
*
* @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
*/
inline void set_test_value(int offset=-1, bool for_comp=false){return;}
......@@ -192,6 +265,7 @@ 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
*/
inline double* value_ptr(int offset=-1, bool for_comp=false){return _value.data();}
......@@ -199,6 +273,7 @@ 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
*/
inline double* test_value_ptr(int offset=-1, bool for_comp=false){return _test_value.data();}
......@@ -245,21 +320,60 @@ public:
void update_add_sub_leaves(std::map<std::string, int>& add_sub_leaves, int pl_mn, int& expected_abs_tot);
/**
* @brief update the dictionary used to check if
* @details [long description]
* @brief update the dictionary used to check if a mult/div node is valid
*
* @param div_mult_leaves the dictionary used to check if an Mult/Div node is valid
* @param fact Factor used to update leaves (power of the feature)
* @param expected_abs_tot The expected absolute sum of all values in div_mult_leaves
*
* @param add_sub_leaves [description]
*/
void update_div_mult_leaves(std::map<std::string, double>& div_mult_leaves, double fact, double& expected_abs_tot);
#ifdef PY_BINDINGS
/**
* @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)
* @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));}
/**
* @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)
* @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));}
/**
* @brief Evaluate the model for a new point
*
* @param x_in_dct 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));}
/**
* @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)
* @return The prediction of the model for a given data point
*/
np::ndarray eval_many_py(np::ndarray x_in);
/**
* @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
* @return The prediction of the model for a given data point
*/
np::ndarray eval_many_py(py::dict x_in);
/**
* @brief get the list of feature expressions for each of the leaves
* @return Python list containing the expression for each leaf in the binary expression tree
*/
inline py::list x_in_expr_list_py(){return python_conv_utils::to_list<std::string>(_x_in_expr_list);}
#endif
};
......
......@@ -113,7 +113,18 @@ public:
*/
virtual ~Node();
/**
* @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
*/
virtual std::vector<std::string> get_x_in_expr_list() = 0;
/**
* @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
*/
virtual int n_leaves(int cur_n_leaves = 0) = 0;
// DocString: node_reindex_1
......@@ -225,6 +236,7 @@ public:
* @brief Set the values of the training data for the feature inside of the value storage arrays
*
* @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
*/
virtual void set_value(int offset=-1, bool for_comp=false) = 0;
......@@ -239,6 +251,7 @@ 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
*/
virtual double* value_ptr(int offset=-1, bool for_comp=false) = 0;
......@@ -247,6 +260,7 @@ public:
* @brief Set the values of the test data for the feature inside of the value storage arrays
*
* @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
*/
virtual void set_test_value(int offset=-1, bool for_comp=false) = 0;
......@@ -254,6 +268,7 @@ 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
*/
virtual double* test_value_ptr(int offset=-1, bool for_comp=false) = 0;
......@@ -301,6 +316,7 @@ public:
* @details Recursively creates a postfix representation of the string
*
* @param cur_expr The current expression
* @param add_params If true include the parameters in teh postfix expression
* @return The current postfix expression of the feature
*/
virtual void update_postfix(std::string& cur_expr, bool add_params=true) = 0;
......@@ -345,11 +361,16 @@ public:
/**
* @brief Set the non-linear parameters
* @param params The new parameters of the node
* @param check_sz If true check the size of the parameters
*/
virtual void set_parameters(std::vector<double>, bool check_sz=true) = 0;
virtual void set_parameters(std::vector<double> params, bool check_sz=true) = 0;
/**
* @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
* @return the number of parameters (_params.size())
*/
virtual int n_params(int n_cur = 0, int depth = 1) = 0;
......@@ -359,6 +380,8 @@ public:
*
* @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 in the binary expression tree (from the root)
*/
virtual void set_value(const double* params, int offset=-1, bool for_comp=false, int depth=0) = 0;
......@@ -367,6 +390,8 @@ public:
*
* @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 in the binary expression tree (from the root)
* @returns the pointer to the feature's data
*/
virtual double* value_ptr(const double* params, int offset=-1, bool for_comp=false, int depth=0) = 0;
......@@ -376,6 +401,8 @@ public:
*
* @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 in the binary expression tree (from the root)
*/
virtual void set_test_value(const double* params, int offset=-1, bool for_comp=false, int depth=0) = 0;
......@@ -384,6 +411,8 @@ public:
*
* @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 in the binary expression tree (from the root)
* @returns the pointer to the feature's data
*/
virtual double* test_value_ptr(const double* params, int offset=-1, bool for_comp=false, int depth=0) = 0;
......@@ -400,7 +429,6 @@ public:
/**
* @brief Get the latexified expression for the overall feature (From root node down)
*
* @param cap string to place in the start/end of the string
* @param params parameter values for non-linear operations
* @param depth the current depth of the node on the Binary expression tree
* @return the latexified expression
......@@ -412,6 +440,8 @@ 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
*/
virtual void set_bounds(double* lb, double* ub, int from_parent=2, int depth = 1) = 0;
......@@ -427,7 +457,7 @@ public:
* @brief Get the parameter gradient for non-linear optimization
*
* @param grad pointer to the gradient storage
* @param samp_ind sample index to calculate the gradient for
* @param dfdp pointer to where the feature derivative pointers are located
*/
virtual void gradient(double* grad, double* dfdp) = 0;
......@@ -435,7 +465,7 @@ public:
* @brief Get the parameter gradient for non-linear optimization
*
* @param grad pointer to the gradient storage
* @param samp_ind sample index to calculate the gradient for
* @param dfdp pointer to where the feature derivative pointers are located
* @param params pointer to the parameters vector
*/
virtual void gradient(double* grad, double* dfdp, const double* params) = 0;
......
......@@ -112,6 +112,10 @@ public:
~OperatorNode()
{}
/**