diff --git a/indicoio/images/features.py b/indicoio/images/features.py index dffc88f..cac6475 100644 --- a/indicoio/images/features.py +++ b/indicoio/images/features.py @@ -5,10 +5,30 @@ import numpy as np from indicoio import JSON_HEADERS -base_url = lambda c: "http://api.indico.io/%s" % c +def facial_features(image): + """ + Given an grayscale input image of a face, returns a 48 dimensional feature vector explaining that face. + Useful as a form of feature engineering for face oriented tasks. + Input should be in a list of list format, resizing will be attempted internally but for best + performance, images should be already sized at 48x48 pixels. -def facial_features(face): - data_dict = json.dumps({"face": face}) - response = requests.post(base_url("facialfeatures"), data=data_dict, headers=JSON_HEADERS) + Example usage: + + .. code-block:: python + + >>> from indicoio import facial_features + >>> import numpy as np + >>> face = np.zeros((48,48)).tolist() + >>> features = facial_features(face) + >>> len(features) + 48 + + :param image: The image to be analyzed. + :type image: list of lists + :rtype: List containing feature responses + """ + + data_dict = json.dumps({"face": image}) + response = requests.post("http://api.indico.io/facialfeatures", data=data_dict, headers=JSON_HEADERS) response_dict = json.loads(response.content) return response_dict['response'] diff --git a/indicoio/images/fer.py b/indicoio/images/fer.py index 2968661..d9fcf94 100644 --- a/indicoio/images/fer.py +++ b/indicoio/images/fer.py @@ -4,9 +4,30 @@ import requests import numpy as np from indicoio import JSON_HEADERS -base_url = "http://api.indico.io/fer" +def fer(image): + """ + Given a grayscale input image of a face, returns a probability distribution over emotional state. + Input should be in a list of list format, resizing will be attempted internally but for best + performance, images should be already sized at 48x48 pixels.. -def fer(face): - data_dict = json.dumps({"face": face}) - response = requests.post(base_url, data=data_dict, headers=JSON_HEADERS) + Example usage: + + .. code-block:: python + + >>> from indicoio import fer + >>> import numpy as np + >>> face = np.zeros((48,48)).tolist() + >>> emotions = fer(face) + >>> emotions + {u'Angry': 0.6340586827229989, u'Sad': 0.1764309536057839, + u'Neutral': 0.05582989039191157, u'Surprise': 0.0072685938275375344, + u'Fear': 0.08523385724298838, u'Happy': 0.04117802220878012} + + :param image: The image to be analyzed. + :type image: list of lists + :rtype: Dictionary containing emotion probability pairs + """ + + data_dict = json.dumps({"face": image}) + response = requests.post("http://api.indico.io/fer", data=data_dict, headers=JSON_HEADERS) return json.loads(response.content) diff --git a/indicoio/text/lang.py b/indicoio/text/lang.py index 522ed4c..fd56ac6 100644 --- a/indicoio/text/lang.py +++ b/indicoio/text/lang.py @@ -3,9 +3,29 @@ import json from indicoio import JSON_HEADERS -base_url = lambda c: "http://api.indico.io/%s" % c +def language(text): + """ + Given input text, returns a probability distribution over 33 possible + languages of what language the text was written in. -def language(test_text): - data_dict = json.dumps({'text': test_text}) - response = requests.post(base_url("language"), data=data_dict, headers=JSON_HEADERS) - return json.loads(response.content) + Example usage: + + .. code-block:: python + + >>> import indicoio + >>> import numpy as np + >>> text = 'Monday: Delightful with mostly sunny skies. Highs in the low 70s.' + >>> possible = indicoio.language(text) + >>> language = possible.keys()[np.argmax(possible.values())] + >>> probability = np.max(possible.values()) + >>> 'Predicted %s with probability %.4f'%(language,probability) + u'Predicted English with probability 0.8548' + + :param text: The text to be analyzed. + :type text: str or unicode + :rtype: Dictionary of language probability pairs + """ + + data_dict = json.dumps({'text': text}) + response = requests.post("http://api.indico.io/language", data=data_dict, headers=JSON_HEADERS) + return json.loads(response.content) \ No newline at end of file diff --git a/indicoio/text/sentiment.py b/indicoio/text/sentiment.py index 69e77c3..8e7f004 100644 --- a/indicoio/text/sentiment.py +++ b/indicoio/text/sentiment.py @@ -4,14 +4,57 @@ import json from indicoio import JSON_HEADERS from indicoio.utils import normalize -base_url = lambda c: "http://api.indico.io/%s" % c +def political(text): + """ + Given input text, returns a probability distribution over the political alignment of the speaker. -def political(test_text): - data_dict = json.dumps({'text': test_text}) - response = requests.post(base_url("political"), data=data_dict, headers=JSON_HEADERS) + Example usage: + + .. code-block:: python + + >>> from indicoio import political + >>> import numpy as np + >>> text = 'Wish we had more bike lanes. \ + Hopefully, driverless cars will chance economics from ownership to fee for service.' + >>> affiliation = political(text) + >>> affiliation + {u'Libertarian': 0.4923755446986322, u'Green': 0.2974443102818122, + u'Liberal': 0.13730032938784784, u'Conservative': 0.07287981563170784} + >>> least_like = affiliation.keys()[np.argmin(affiliation.values())] + >>> most_like = affiliation.keys()[np.argmax(affiliation.values())] + >>> 'This text is most like %s and least like %s'%(most_like,least_like) + u'This text is most like Libertarian and least like Conservative' + + :param text: The text to be analyzed. + :type text: str or unicode + :rtype: Dictionary of party probability pairs + """ + + data_dict = json.dumps({'text': text}) + response = requests.post("http://api.indico.io/political", data=data_dict, headers=JSON_HEADERS) return json.loads(response.content) -def posneg(test_text): - data_dict = json.dumps({'text': test_text}) - response = requests.post(base_url("sentiment"), data=data_dict, headers=JSON_HEADERS) +def posneg(text): + """ + Given input text, returns a scalar estimate of the sentiment of that text. + Values are roughly in the range 0 to 1 with 0.5 indicating neutral sentiment. + Likewise, 0 would suggest very negative sentiment and 1 would suggest very positive sentiment. + + Example usage: + + .. code-block:: python + + >>> from indicoio import sentiment + >>> text = 'Thanks everyone for the birthday wishes!! It was a crazy few days ><' + >>> sentiment = sentiment(text) + >>> sentiment + {u'Sentiment': 0.6946439339979863} + + :param text: The text to be analyzed. + :type text: str or unicode + :rtype: Dictionary containing Sentiment key with a float value + """ + + data_dict = json.dumps({'text': text}) + response = requests.post("http://api.indico.io/sentiment", data=data_dict, headers=JSON_HEADERS) return json.loads(response.content)