Merge pull request #2 from IndicoDataSolutions/docs

Added docs and removed lambdas

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']

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)

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)

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)