| predictionio Legacy Package Documentation |
| ==================================== |
| |
| .. automodule:: predictionio |
| |
| predictionio.Client (Deprecated) Usage Overview |
| -------------------------------------- |
| |
| .. deprecated:: 0.8.0 |
| |
| Before making any request through the PredictionIO API, you need to create a |
| client object for your App. |
| |
| >>> client = predictionio.Client(<your App Key>) |
| |
| .. note:: The App Key can be found in the PredictionIO Admin Server web control panel. |
| |
| Afterwards, you can import data or retrieve recommendations for your App by |
| calling methods of this object. For example, |
| |
| **User** |
| |
| To import a user record from you App with user id = "u100": |
| |
| >>> client.create_user("u100") |
| |
| To import a user record with the optional predefined location attribute "pio_latlng": |
| |
| >>> client.create_user("u100", { "pio_latlng" : [1.23, 4.56] }) |
| |
| You may also define your own custom attribute "custom" = "value": |
| |
| >>> client.create_user("u100", { "pio_latlng" : [1.23, 4.56], "custom": "value" }) |
| |
| .. note:: custom attributes and values could be any string but all attribute names with prefix ``'pio_'`` are reserved. You should not use the prefix ``'pio_'`` when define your custom attributes to avoid conflicts. |
| |
| **Item** |
| |
| To import an item record from your App with item id = "i200" and item type = "type3": |
| |
| >>> client.create_item("i200", ("type3",)) |
| |
| To import an item record with the predefined optional attribute "pio_latlng": |
| |
| >>> client.create_item("i200", ("type3",), { "pio_latlng" : [1.23, 4.56] }) |
| |
| You may also define your own custom attribute "custom" = "value": |
| |
| >>> client.create_item("i200", ("type3",), { "pio_latlng" : [1.23, 4.56], "custom": "value" }) |
| |
| .. note:: custom attributes and values could be any string but all attribute names with prefix ``'pio_'`` are reserved. You should not use the prefix ``'pio_'`` when define your custom attributes to avoid conflicts. |
| |
| **User Action on Item** |
| |
| To import a user "rate" action record from your App with user id = "u100", item id = "i200" and rating = 2: |
| |
| >>> client.identify("u100") |
| >>> client.record_action_on_item("rate", "i200", { "pio_rate": 2 }) |
| |
| .. note:: the "pio_rate" attribute is required for "rate" action. |
| |
| To import a "view" action record from your App for the same user and item: |
| |
| >>> client.record_action_on_item("view", "i200" ) |
| |
| To import a "like" record with predefined optional timestamp attribute "pio_t": |
| |
| >>> client.record_action_on_item("like", "i200", { "pio_t": 12345678 }) |
| |
| .. note:: predefined actions: "like", "dislike", "rate", "view", "conversion" |
| |
| **Item Recommendation Engine** |
| |
| When there is enough data imported from your App and the prediction results are ready, you can get recommendations for a user. |
| |
| To get top 5 item recommendation for the same user id from the item recommendation engine "engine-1" |
| |
| >>> result = client.get_itemrec_topn("engine-1", 5) |
| |
| **Item Similarity Engine** |
| |
| To get top 5 similar items of the item i200 from the item similarity engine "engine-2" |
| |
| >>> result = client.get_itemsim_topn("engine-2", "i200", 5) |
| |
| To get top 5 similar items given a list of items i200,i300,i400 from the item similarity engine "engine-2" |
| |
| >>> result = client.get_itemsim_topn("engine-2", "i200,i300,i400", 5) |
| |
| **Item Rank Engine** |
| |
| To rank a list of items i100, i101, i102, i103 for user "u100" from the item rank engine "engine-3" |
| |
| >>> client.identify("u100") |
| >>> result = client.get_itemrank_ranked("engine-3", ["i100","i101","i102", "i103"]) |
| |
| |
| Please refer to the documentation of the :class:`predictionio.Client` class for more details of all available methods. |
| |
| |
| Error Handling |
| -------------- |
| |
| An exception will be raised when an error occur during the request. Please refer to the documentation of the :class:`predictionio.Client` class for details. |
| In general, you may want to catch the exception and decide what to do with the error (such as logging it). |
| |
| For example, the method :meth:`~Client.record_action_on_item` may raise ``U2IActionNotCreatedError``. |
| |
| >>> try: |
| >>> client.record_action_on_item("view", "i200") |
| >>> except: |
| >>> <log the error> |
| |
| |
| Asynchronous Requests |
| --------------------- |
| |
| In addition to normal :ref:`blocking (synchronous) request methods <sync-methods-label>`, this SDK also provides :ref:`methods which can generate asynchronous requests <async-methods-label>`. |
| All methods prefixed with 'a' are asynchronous (eg, :meth:`~Client.acreate_user`, :meth:`~Client.acreate_item`). |
| Asynchronous requests are handled by separate threads in the background, so you can generate multiple requests at the same time without waiting for any of them to finish. |
| These methods return immediately without waiting for results, allowing your code to proceed to work on something else. |
| The concept is to break a normal blocking request (such as :meth:`~Client.create_user`) into two steps: |
| |
| 1. generate the request (e.g., calling :meth:`~Client.acreate_user`); |
| 2. get the request status and return data (calling :meth:`~Client.aresp`); |
| |
| This allows you to do other work between these two steps. |
| |
| .. note:: |
| In some cases you may not care whether the request is successful for performance or application-specific reasons, then you can simply skip step 2. |
| |
| .. note:: |
| If you do care about the request status or need to get the return data, then at a later time you will need to call :meth:`~Client.aresp` with the AsyncRequest object returned in step 1. |
| Please refer to the documentation of :ref:`asynchronous request methods <async-methods-label>` for more details. |
| |
| For example, the following code first generates an asynchronous request to retrieve recommendations, then get the result at later time:: |
| |
| >>> # Generates asynchronous request and return an AsyncRequest object |
| >>> request = client.aget_itemrec_topn("engine-1", 5) |
| >>> <...you can do other things here...> |
| >>> try: |
| >>> result = client.aresp(request) # check the request status and get the return data. |
| >>> except: |
| >>> <log the error> |
| |
| |
| Batch Import Data |
| ----------------- |
| |
| When you import large amount of data at once, you may also use asynchronous request methods to generate lots of requests in the beginning and then check the status at a later time to minimize run time. |
| |
| For example, to import 100000 of user records:: |
| |
| >>> # generate 100000 asynchronous requests and store the AsyncRequest objects |
| >>> req = {} |
| >>> for i in range(100000): |
| >>> req[i] = client.acreate_user(user_record[i].uid) |
| >>> |
| >>> <...you can do other things here...> |
| >>> |
| >>> # now check the status of the previous asynchronous requests |
| >>> for i in range(100000): |
| >>> try: |
| >>> result = client.aresp(req[i]) |
| >>> except: |
| >>> <log the error> |
| |
| Alternatively, you can use blocking requests to import large amount of data, but this has significantly lower performance:: |
| |
| >>> for i in range(100000): |
| >>> try: |
| >>> client.create_user(user_record[i].uid) |
| >>> except: |
| >>> <log the error> |
| |
| |
| |
| |
| predictionio.Client Class |
| --------------------------------- |
| |
| .. autoclass:: Client |
| .. deprecated:: 0.8.0 |
| Use :class:`EventClient` and :class:`EngineClient` instead. |
| |
| |
| .. automethod:: close |
| .. automethod:: identify |
| |
| .. versionadded:: 0.5.0 |
| |
| .. automethod:: pending_requests |
| |
| .. versionadded:: 0.6.1 |
| |
| | |
| |
| .. _sync-methods-label: |
| |
| .. note:: The following is blocking (synchronous) request methods |
| |
| .. automethod:: get_status |
| .. automethod:: create_user |
| .. automethod:: get_user |
| .. automethod:: delete_user |
| |
| .. automethod:: create_item |
| .. automethod:: get_item |
| .. automethod:: delete_item |
| |
| .. automethod:: record_action_on_item |
| |
| .. versionadded:: 0.5.0 |
| |
| .. automethod:: get_itemrec_topn |
| |
| .. versionadded:: 0.5.0 |
| |
| .. versionchanged:: 0.6.0 |
| Change the order of parameters. |
| |
| .. automethod:: get_itemsim_topn |
| |
| .. versionadded:: 0.6.0 |
| |
| .. automethod:: get_itemrank_ranked |
| |
| .. versionadded:: 0.7.0 |
| |
| .. automethod:: get_itemrec |
| |
| .. deprecated:: 0.5.0 |
| Use :func:`get_itemrec_topn` instead. |
| |
| .. automethod:: user_conversion_item |
| |
| .. deprecated:: 0.5.0 |
| Use :func:`record_action_on_item` instead. |
| |
| .. automethod:: user_dislike_item |
| |
| .. deprecated:: 0.5.0 |
| Use :func:`record_action_on_item` instead. |
| |
| .. automethod:: user_like_item |
| |
| .. deprecated:: 0.5.0 |
| Use :func:`record_action_on_item` instead. |
| |
| .. automethod:: user_rate_item |
| |
| .. deprecated:: 0.5.0 |
| Use :func:`record_action_on_item` instead. |
| |
| .. automethod:: user_view_item |
| |
| .. deprecated:: 0.5.0 |
| Use :func:`record_action_on_item` instead. |
| |
| | |
| |
| .. _async-methods-label: |
| |
| .. note:: The following is non-blocking (asynchronous) request methods |
| |
| .. automethod:: acreate_user |
| .. automethod:: aget_user |
| .. automethod:: adelete_user |
| |
| .. automethod:: acreate_item |
| .. automethod:: aget_item |
| .. automethod:: adelete_item |
| |
| .. automethod:: arecord_action_on_item |
| |
| .. versionadded:: 0.5.0 |
| |
| .. automethod:: aget_itemrec_topn |
| |
| .. versionadded:: 0.5.0 |
| |
| .. versionchanged:: 0.6.0 |
| Change the order of parameters. |
| |
| .. automethod:: aget_itemsim_topn |
| |
| .. versionadded:: 0.6.0 |
| |
| .. automethod:: aget_itemrank_ranked |
| |
| .. versionadded:: 0.7.0 |
| |
| .. automethod:: aget_itemrec |
| |
| .. deprecated:: 0.5.0 |
| Use :func:`aget_itemrec_topn` instead. |
| |
| .. automethod:: auser_conversion_item |
| |
| .. deprecated:: 0.5.0 |
| Use :func:`arecord_action_on_item` instead. |
| |
| .. automethod:: auser_dislike_item |
| |
| .. deprecated:: 0.5.0 |
| Use :func:`arecord_action_on_item` instead. |
| |
| .. automethod:: auser_like_item |
| |
| .. deprecated:: 0.5.0 |
| Use :func:`arecord_action_on_item` instead. |
| |
| .. automethod:: auser_rate_item |
| |
| .. deprecated:: 0.5.0 |
| Use :func:`arecord_action_on_item` instead. |
| |
| .. automethod:: auser_view_item |
| |
| .. deprecated:: 0.5.0 |
| Use :func:`arecord_action_on_item` instead. |
| |
| .. automethod:: aresp |
| |
| |