Turi Create  4.0
unity_nearest_neighbors.hpp
1 /* Copyright © 2017 Apple Inc. All rights reserved.
2  *
3  * Use of this source code is governed by a BSD-3-clause license that can
4  * be found in the LICENSE.txt file or at https://opensource.org/licenses/BSD-3-Clause
5  */
6 #ifndef TURI_UNITY_NEAREST_NEIGHBORS_H
7 #define TURI_UNITY_NEAREST_NEIGHBORS_H
8 
9 #include <vector>
10 
11 #include <model_server/lib/toolkit_function_specification.hpp>
12 #include <model_server/lib/variant.hpp>
13 
14 namespace turi {
15 namespace nearest_neighbors {
16 
17 /*
18  * Get the list of options that are relevant ot each model.
19  *
20  * \param[in] model_name Name of the model.
21  * \returns List of keys of option names relevant to a model.
22  */
23 std::vector<std::string> get_model_option_keys(std::string model_name);
24 
25 /**
26  * Get the current set of options.
27  *
28  * \param[in] params dictionary with function arguments
29  * \returns Dictionary with current options.
30  *
31  * Params dictionary keys
32  * \property[in] model Regression model object.
33  * \property[in] model_name Name of the model.
34  */
35 variant_map_type get_current_options(variant_map_type& params);
36 
37 /**
38  * Get training stats.
39  *
40  * \param[in] params dictionary with function arguments
41  * \returns Dictionary with train stats.
42  *
43  * Params dictionary keys
44  * \property[in] model Regression model object.
45  * \property[in] model_name Name of the model.
46  */
47 variant_map_type training_stats(variant_map_type& params);
48 
49 /**
50  * Get any value from the model.
51  *
52  * \param[in] params dictionary with function arguments
53  * \returns Dictionary
54  *
55  * Params dictionary keys
56  * \property[in] model Regression model object.
57  * \property[in] model_name Name of the model.
58  * \property[out] "value" Value of the key.
59  *
60  */
61 variant_map_type get_value(variant_map_type& params);
62 
63 /**
64  * List all keys in the model.
65  *
66  * \param[in] params dictionary with function arguments
67  * \returns Dict with "model" keys but empty values.
68  *
69  * Params dictionary keys
70  * \property[in] model Regression model object.
71  * \property[in] model_name Name of the model.
72  *
73  */
74 variant_map_type list_fields(variant_map_type& params);
75 
76 /**
77  * Creation function for nearest neighbors reference objects. Checks for errors
78  * in inputs and makes sure all options provided by the user overwrite default
79  * options.
80  *
81  * \param[in] params dictionary with function arguments
82  * \returns Dictionary with new model.
83  *
84  * Params dictionary keys
85  * \property[in,out] model Regression model object.
86  * \property[in] model_name Name of the model.
87  */
88 variant_map_type train(variant_map_type& params);
89 
90 /**
91  * Query function for the nearest neighbors toolkit.
92  *
93  * \param[in] params dictionary with function arguments
94  * \returns SFrame with labels of queries, reference points in the nearest
95  * neighbors model, distances between the queries and answers, and ranks of the
96  * answers for each query.
97  *
98  * Params dictionary keys
99  * \property[in, out] model NearestNeighborsModel object
100  * \property[in] model_name Name of the model
101  */
102 variant_map_type query(variant_map_type& params);
103 
104 /**
105  * Similarity graph function for the nearest neighbors toolkit.
106  *
107  * \param[in] params dictionary with function arguments
108  * \returns SFrame with labels of queries, reference points in the nearest
109  * neighbors model, distances between the queries and answers, and ranks of the
110  * answers for each query.
111  *
112  * Params dictionary keys
113  * \property[in, out] model NearestNeighborsModel object
114  * \property[in] model_name Name of the model
115  */
116 variant_map_type similarity_graph(variant_map_type& params);
117 
118 /**
119  * Obtain registration for the nearest_neighbors toolkit.
120  */
121 std::vector<toolkit_function_specification> get_toolkit_function_registration();
122 
123 } // namespace nearest_neighbors
124 } // namespace turi
125 
126 #endif