KeLP adopts a simple and intuitive serialization\/deserialization formalism for objects, such as kernels and algorithms, that is based on JSON.
\nJSON is the\u00a0JavaScript Object Notation, a standard de facto when exchanging data in WEB, and its main characteristic is that it is easily readable by humans, and can be composed in an efficient way to represent object hierarchies. For example, a kernel function can be completely defined in a JSON representation without the need of programattically defining its characteristics.
\nWe decided to provide a JSON interface to help those users that are not familiar with programming languages, or for those users that know other programming languages and are not familiar with Java. In fact, for the first class of users, JSON is easily readable and can be written without any programming skill. The second class of users can leverage on well-estabilished JSON library in their preferred language.<\/p>\n
Objects can be stored\/loaded in the KeLP supported JSON format by using the Java class JacksonSerializerWrapper<\/a> of the package it.uniroma2.sag.kelp.utils<\/em>. For example, to store the JSON format of a LinearKernel<\/a>:<\/p>\n The previous snippet of code should print something similar to:<\/p>\n To load such kernel from its JSON representation stored in the json<\/em> Java String object, it will be sufficient to do:<\/p>\n Definining a kernel function with JSON requires to insert in the function specification some parameters. A kernel must be defined with its name and the configuration of its parameters and, eventually, of the caches.<\/p>\n For example, if you want to define a kernel operating directly on a representation (DirectKernel<\/a>) of type PartialTreeKernel<\/a> operating over the representation named TREE, the associated JSON must contain at least:<\/p>\n This will instantiate a PartialTreeKernel<\/a> with default parameters by using its JSON name ptk<\/em>. If one\u00a0wants to customize a specific parameter, it can be done\u00a0in the JSON representation. For example, to customize the terminalFactor<\/em> value, \u00a0the JSON should be modified as follows:<\/p>\n The available kernel functions with their name and parameters that can be defined in JSON can be found on the Kernel<\/a>\u00a0documentation page.<\/p>\n JSON flexibility allows also the definition of complex<\/em> kernel functions, such as composition or combination of them, that are characterized by complex object structures. Let us assume that we must define a kernel, that is the sum (KernelCombination<\/a>) of a PolynomialKernel<\/a> applied over a LinearKernel<\/a> operating over the representation named VECTOR<\/em> and a PartialTreeKernel<\/a> operating over a representation named TREE<\/em>. The following JSON code will define such kernel with a cache that will store the kernel computations of 1000 examples:<\/p>\n Notice that the kernel so defined contains all the object hierarchy needed to rebuild at runtime the correct Kernel function.<\/p>\n Learning algorithms can be represented in JSON as well as kernels. The JSON formalism\u00a0allows to define full experiments configurations and to write only a general purpose algorithm that will read the learning algorithm specification from JSON and will produce its outputs over the provided datasets.<\/p>\n As for the kernel functions case, it is possibile to store\/load such representation via simple calls to the class JacksonSerializerWrapper<\/a>. For example, let us assume that we want to define a linear model over the representation REPRESENTATION_NAME<\/em> through\u00a0LibLinearLearningAlgorithm<\/a> where the positive class is +1<\/em>. This algorithm can be defined in JSON through the following code:<\/p>\n The algorithm is defined by a full set of meta-parameters, such as cp<\/em>, cn<\/em> and fairness<\/em>. This allows to define different parameterisation of the algorithms (for example in a parameter tuning phase) through different JSON specifications. Then, it can be possible to iterate over such specifications and use the same general code to perform different measures.<\/p>\n Kernel-based learning algorithms can be defined by defining in a single JSON representation both the learning algorithm and the kernel to be used. Again, it allows to fully specify an experiment via JSON, and to use a general purpose Java KeLP-based interpreter. The following JSON code will define such experiment:<\/p>\n Notice that the algorithms fully includes the set of its meta-parameters as well as the full kernel specification. Learning processes produce the so-called models<\/em>. These contain the outcome of the learning process, that is all the necessary information to provide future classifications. For example, a linear model will contain the values of the weights of the linear classification function, or a kernel-based model will contain the set of examples with their weights. For example, let us assume we learn a binary linear model through a LibLinearLearningAlgorithm<\/a>\u00a0(similar to the one we defined above) over a dataset with positive class +1<\/em> over the first representation (0<\/em>) with cp<\/em> and cn<\/em> values equal to 1<\/em>. We can define such algorithm in JSON as<\/p>\n In order to produce a model we need to load a training dataset, load the JSON learning algorithm specification and call the learn method. Finally, the model (i.e., the PredictionFunction) can be obtained through:<\/p>\n To save such model on a file named binary_model.klp<\/em>, we can use again the\u00a0JacksonSerializerWrapper<\/a> with:<\/p>\n Notice that the Java code we just provided is general and it has no specific knowledge of the types of the experiment we are making. It means that it can be possible to write general purpose experimenter classes, and to customize its use via configuration files written in JSON.<\/p>\n The file\u00a0binary_model.klp<\/em> \u00a0will contain the model specification, i.e., something similar to:<\/p>\n The model contains some useful information: the type of the classifier (linear), its model (BinaryLinearModel) with its full set of weights. Similarly, we can obtain a model of a kernel-based classifier. For example, if we adopt a 2-degree polynomial kernel over the first representation of the same dataset with a binary SVM, we can obtain a different model, made of support vectors, similar to:<\/p>\n Again, the model contains all the information necessary to provide future classification. In particular, this model contains the type of the model, the full specification of the kernel function that must be adopted, and the set of support vectors to be used when classifying a new instance.<\/p>\n","protected":false},"excerpt":{"rendered":" KeLP adopts a simple and intuitive serialization\/deserialization formalism for objects, such as kernels and algorithms, that is based on JSON. JSON is the\u00a0JavaScript Object Notation, a standard de facto when exchanging data in WEB, and its main characteristic is that it is easily readable by humans, and can be composed in an efficient way to Read more about JSON Interface<\/span>[…]<\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"parent":112,"menu_order":14,"comment_status":"closed","ping_status":"closed","template":"","meta":[],"_links":{"self":[{"href":"http:\/\/www.kelp-ml.org\/index.php?rest_route=\/wp\/v2\/pages\/186"}],"collection":[{"href":"http:\/\/www.kelp-ml.org\/index.php?rest_route=\/wp\/v2\/pages"}],"about":[{"href":"http:\/\/www.kelp-ml.org\/index.php?rest_route=\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"http:\/\/www.kelp-ml.org\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/www.kelp-ml.org\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=186"}],"version-history":[{"count":33,"href":"http:\/\/www.kelp-ml.org\/index.php?rest_route=\/wp\/v2\/pages\/186\/revisions"}],"predecessor-version":[{"id":717,"href":"http:\/\/www.kelp-ml.org\/index.php?rest_route=\/wp\/v2\/pages\/186\/revisions\/717"}],"up":[{"embeddable":true,"href":"http:\/\/www.kelp-ml.org\/index.php?rest_route=\/wp\/v2\/pages\/112"}],"wp:attachment":[{"href":"http:\/\/www.kelp-ml.org\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=186"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
\nIn general, given a KeLP serializable object, the methods writeValue<\/em>\u00a0and readValue<\/em> will respectively store\/load data to\/from a JSON format.<\/p>\nJacksonSerializerWrapper serializer = new JacksonSerializerWrapper();\r\nKernel linearKernel = new LinearKernel(\"REPRENTATION_NAME\");\r\nString json = serializer.writeValueAsString(linearKernel);\r\nSystem.out.println(json);\r\n<\/pre>\n
{\r\n \"kernelType\" : \"linear\",\r\n \"kernelID\" : 1,\r\n \"representation\" : \"REPRENTATION_NAME\"\r\n}\r\n<\/pre>\nLinearKernel loadedKernel =(LinearKernel) serializer.readValue(json, Kernel.class);\r\nSystem.out.println(loadedKernel.getRepresentation());\r\n<\/pre>\n
JSON Representation of Kernel Functions<\/h3>\n
{\r\n \"kernelType\" : \"ptk\",\r\n \"kernelID\" : 1,\r\n \"representation\" : \"TREE\",\r\n}\r\n<\/pre>\n {\r\n \"kernelType\" : \"ptk\",\r\n \"representation\" : \"TREE\",\r\n \"terminalFactor\" : 3\r\n}\r\n<\/pre>\n{\r\n \"kernelType\" : \"linearComb\",\r\n \"toCombine\" : [ {\r\n \"kernelType\" : \"poly\",\r\n \"baseKernel\" : {\r\n \"kernelType\" : \"linear\",\r\n \"representation\" : \"VECTOR\"\r\n },\r\n \"degree\" : 2.0,\r\n \"a\" : 1.0,\r\n \"b\" : 0.0\r\n }, {\r\n \"kernelType\" : \"ptk\",\r\n \"representation\" : \"TREE\",\r\n \"mu\" : 0.4,\r\n \"lambda\" : 0.1,\r\n \"terminalFactor\" : 3.0,\r\n } ],\r\n \"weights\" : [ 1.0, 1.0 ],\r\n \"kernelCache\" : {\r\n \"cacheType\" : \"fixIndex\",\r\n \"examplesToStore\" : 1000\r\n }\r\n}\r\n<\/pre>\nJSON Representation of Algorithms<\/h3>\n
{\r\n \"algorithm\" : \"liblinear\",\r\n \"label\" : {\r\n \"labelType\" : \"StringLabel\",\r\n \"className\" : \"+1\"\r\n },\r\n \"cp\" : 1.0,\r\n \"cn\" : 1.0,\r\n \"fairness\" : false,\r\n \"representation\" : \"REPRESENTATION_NAME\"\r\n}\r\n<\/pre>\n
\nLet us assume, that we need to adopt the LinearKernelCombination<\/a> kernel we defined above within an SVM for a binary classification task, i.e., a BinaryCSvmClassification<\/a>.<\/p>\n{\r\n \"algorithm\" : \"binaryCSvmClassification\",\r\n \"cp\" : 1.0,\r\n \"cn\" : 1.0,\r\n \"kernel\" : {\r\n \"kernelType\" : \"linearComb\",\r\n \"toCombine\" : [ {\r\n \"kernelType\" : \"poly\",\r\n \"baseKernel\" : {\r\n \"kernelType\" : \"linear\",\r\n \"representation\" : \"VECTOR\"\r\n },\r\n \"degree\" : 2.0,\r\n \"a\" : 1.0,\r\n \"b\" : 0.0\r\n }, {\r\n \"kernelType\" : \"ptk\",\r\n \"representation\" : \"TREE\",\r\n \"mu\" : 0.4,\r\n \"lambda\" : 0.1,\r\n \"terminalFactor\" : 3.0,\r\n } ],\r\n \"weights\" : [ 1.0, 1.0 ],\r\n \"kernelCache\" : {\r\n \"cacheType\" : \"fixIndex\",\r\n \"examplesToStore\" : 1000\r\n }\r\n },\r\n \"label\" : {\r\n \"labelType\" : \"StringLabel\",\r\n \"className\" : \"+1\"\r\n },\r\n \"fairness\" : false\r\n}\r\n<\/pre>\n
\nThe list of available learning algorithms in KeLP with their JSON names can be found on the Learning Algorithms<\/a>\u00a0documentation page.<\/p>\nJSON Representation of Models<\/h3>\n
\nModels are meant to be produced during the learning phase, and then adopted during a separate classification phase. For this reason, a storing\/loading mechanism is necessary: KeLP adopts, again, the JSON representation formalism to provide such functionality.
\nNotice that, differently from Kernel and Learning Algorithms, the JSON representation of models is not meant for a manual specification, but instead it is the result of an automatic process.
\nA model in KeLP is represented by a PredictionFunction<\/a> object. This is obtained after the learning phase, by extracting it from the LearningAlgorithm<\/a> object with a call of the method getPredictionFunction()<\/a>.<\/p>\n{\r\n \"algorithm\" : \"liblinear\",\r\n \"label\" : {\r\n \"labelType\" : \"StringLabel\",\r\n \"className\" : \"+1\"\r\n },\r\n \"cp\" : 1.0,\r\n \"cn\" : 1.0,\r\n \"fairness\" : false,\r\n \"representation\" : \"0\"\r\n}\r\n<\/pre>\n
\nLet us assume our dataset is contained in the file train.klp<\/em> and that the above JSON learning algorithm specification is contained in a file named learning_algo.klp<\/em>.<\/p>\nJacksonSerializerWrapper serializer = new JacksonSerializerWrapper();\r\nSimpleDataset trainingSet = new SimpleDataset();\r\ntrainingSet.populate(\"train.klp\");\r\nLearningAlgorithm binaryLearner = serializer.readValue(new File(\"learning_algo.klp\"),\r\n\t\t\t\tLearningAlgorithm.class);\r\nbinaryLearner.learn(trainingSet);\r\n<\/pre>\n
PredictionFunction predictionFunction = binaryLearner.getPredictionFunction();\r\n<\/pre>\n
serializer.writeValueOnFile(predictionFunction, \"binary_model.klp\");\r\n<\/pre>\n
{\r\n \"type\" : \"linearClassifier\",\r\n \"model\" : {\r\n \"type\" : \".BinaryLinearModel\",\r\n \"bias\" : 0.0,\r\n \"hyperplane\" : {\r\n \"type\" : \"V\",\r\n \"content\" : \"__LIB_LINEAR_BIAS_:0.0 5045:-0.09723804 3804:-0.08888734 ... \"\r\n },\r\n \"representation\" : \"0\"\r\n },\r\n \"label\" : {\r\n \"labelType\" : \"StringLabel\",\r\n \"className\" : \"+1\"\r\n }\r\n}\r\n<\/pre>\n
\nThe hyperplane field contain in fact the weights of the linear classification function. Notice how the JSON formalism allows to easily inspect such information.<\/p>\n{\r\n \"type\" : \"kernelMachineClassifier\",\r\n \"model\" : {\r\n \"type\" : \".BinaryKernelMachineModel\",\r\n \"bias\" : 0.16920261,\r\n \"kernel\" : {\r\n \"kernelType\" : \"poly\",\r\n \"baseKernel\" : {\r\n \"kernelType\" : \"linear\",\r\n \"representation\" : \"0\"\r\n },\r\n \"degree\" : 2.0,\r\n \"a\" : 1.0,\r\n \"b\" : 0.0\r\n },\r\n \"supportVectors\" : [ {\r\n \"weight\" : 0.6423006,\r\n \"instance\" : {\r\n \"type\" : \"simple\",\r\n \"ID\" : 3,\r\n \"classificationLabels\" : [ {\r\n \"labelType\" : \"StringLabel\",\r\n \"className\" : \"+1\"\r\n } ],\r\n \"representations\" : {\r\n \"0\" : {\r\n \"type\" : \"V\",\r\n \"content\" : \"8311:0.21969146 3374:0.1667255 ... \"\r\n }\r\n }\r\n }\r\n }, \r\n {},\r\n ...\r\n ]\r\n },\r\n \"label\" : {\r\n \"labelType\" : \"StringLabel\",\r\n \"className\" : \"+1\"\r\n }\r\n}\r\n<\/pre>\n