Metadata-Version: 2.1
Name: statebasedml
Version: 0.0.13
Summary: Train data with state based machine learning.
Home-page: https://github.com/bellemanwesley/statebasedml
Author: Wesley Belleman
Author-email: bellemanwesley@gmail.com
License: MIT
Description: statebasedml
        ========
        
        [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
        
        ## Overview
        
        statebasedml is a Python library for training data with state based machine learning. The documentation below should help you understand the parameters passed to the statebasedml functions and what they return, but I recommend starting with examples. Check out the examples in the [samples folder](/samples)
        
        Installation instructions
        -------------------------
        
            python3 -m pip install --upgrade pip
        	python3 -m pip install statebasedml
        
        ## Classes
        The statebasedml library has two classes:
           - `bitfold`: [compresses states in order to shrink big data](https://medium.com/swlh/shrinking-big-data-with-bit-folding-4ea0aa6a055d)
           - `data`: trains, tests, and classifies input datasets 
           - `pack`: packs strings into shorter strings without losing information
        
        # bitfold
        
        *import statebasedml.bitfold*
        
        ```python
        	from statebasedml import bitfold
        ```
        
        *bitfold has 2 methods*
           - `gen_param()`: generates the parameters for a fold
           - `fold()`: actually folds the input data
        
        ## gen_param
        
        *request syntax*
        
        ```python
        
            fold_parameters = bitfold.gen_param(
                size = 256
            )
        
        ```
        
        *parameters*
           - `size` *(integer)*: The number of bits of the largest sized string that you want to fold. You can determine the bit size of a string with `8*len(string)`
        
        *response syntax*
        
        ```python
        
            {
                "mapping":mapping,
                "ops":ops
            }
        
        ```
        
        
        ## fold
        
        *request syntax*
        
        ```python
        
            folded_value = bitfold.fold(
                value = string,
                new_size = 123,
                mapping = [1, 2, 3],
                ops = [1, 2, 3]
            )
        
        ```
        
        *parameters*
           - `value` *(string)*: This is simply the input value that you want to shrink.
           - `new_size` *(integer)*: The number of bits of the new string that you want to be generated. If you want to output strings of length `l` then this value is `l * 8`.
           - `mapping` *(list)*: This is a mapping of the bits to be folded. This paramater is generated with `fold_parameters = bitfold.gen_param()`. Then you should have `mapping = fold_parameters["mapping"]`.
           - `ops` *(list)*: This is a list of the operations to be perfomed on the mapping. This paramater is generated with `fold_parameters = bitfold.gen_param()`. Then you should have `ops = fold_parameters["ops"]`.
        
        *response syntax*
        
        The `fold()` function simply outputs a folded string.
        
        # data
        
        *import statebasedml.data*
        
        ```python
        	from statebasedml import data
        ```
        
        *data has 4 methods*
           - `train()`: generates a model based on tagged input data
           - `update()`: updates a model with new tagged input data
           - `test()`: tests a trained model based on additional tagged input data
           - `classify()`: classifies untagged data using a provided model
        
        ## train
        
        *request syntax*
        
        ```python
        
            trained_model = data.train(
                datalist = [
                    {
                        "key1": {
                            "result": string,
                            "options": [option1, option2, ..., optionN],
                            "choice": optionN
                        }
                    },
                    {
                        ...
                    },
                    {
                        "keyN": ...
                    }
                ]
            )
        
        ```
        
        *parameters*
        
        * `datalist` *(list)*: The function takes a single list of dictionaries with the below key/value pairs.
           * `key` *(string)*: Each dictionary should include one or more keys. The key is the measured *state* of the system that you want to capture. One key per list item is recommended, but the function will accept multiple keys per list item.
              * `result` *(string)*: The result is the *tag* associated with that key. If you are using options, then the tag is associated with the key/choice pair.
              * `options` *(list)* \[OPTIONAL\]: Only use options if you have additional options associated with your state. One example of when to use options is for teaching the model to play board games. In this case, the state is the configuration of the board and options are possible moves.
              * `choice` *(string)* \[OPTIONAL\]: The choice parameter is required if you are using options. The choice must be a member of the options list. The choice parameter is the choice made to achieve the provided result. 
        
        *response syntax*
        
        ```python
        
            {
                "key1": {
                    "option_dict": {
                        "option1": {
                            "count": 123,
                            "result_dict": {
                                "result1":count1,
                                "result2":count2,
                                ...,
                                "resultN":countN
                            }
                        }, 
                        ...,
                        "optionN": ...
                    }
                },
                ...,
                "keyN": {
                    "count": 123,
                    "result_dict": {
                        "result1": count1,
                        ...,
                        "resultN": countN
                    }
                }
            }
        
        ```
        
        ## update
        
        The update function is similar to the train function, except you add a model to the second argument. In fact, the train function can operate as the update function if you pass a model to it as a `model=model` argument. I just added `update()` for syntatic convenience.
        
        *request syntax*
        
        ```python
        
            updated_model = data.update(
                datalist = datalist,
                model = model
            )
        
        ```
        
        *parameters*
        
        * `datalist` *(list)*: This takes the same format as the input specified in the `train()` function above.
        * `model` *(dict)*: This takes the same format as the output specified in the `train()` function above.
        
        *response syntax*
        
        The `update()` function outputs a model with the same format as the `train()` function above.
        
        ## test
        
        *request syntax*
        
        ```python
        
            model_performance = data.test(
                datalist = datalist,
                model = model
            )
        
        ```
        
        *parameters*
        
        * `datalist` *(list)*: This takes the same format as the input specified in the `train()` function above.
        * `model` *(dict)*: This takes the same format as the output specified in the `train()` function above.
        
        *response syntax*
        
        ```python
        
            {
                "accuracy": 0.123,
                "loss": 1.23
            }
        
        ```
        
        
        ## classify
        
        *request syntax*
        
        ```python
        
            classifications = data.classify(
                datalist = [
                    {
                        "key1": {
                            "options": [option1, option2, ..., optionN],
                            "desired_result": result
                        },
                        ...,
                        "keyN": {
                            "results": [result1, result2, result3]
                        }
                    },
                ]
                model = model
            )
        
        ```
        
        *response syntax*
        
        ```python
        
            [
                {"key1": "string"},
                ...,
                {"keyN": "string"}
            ]
        
        ```
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
