Version 1.0 - RetinaApi Java Tutorial

Version 1.0 is now deprecated.

Introduction to cortical.io's Semantic Fingerprints and API


So, as a developer, what is a Semantic Fingerprint to you, and what can you do with it?

Simply put, a Semantic Fingerprint is a representation of semantic content based on cortical.io's Retina. It consists of a vector of positions, each of which represents individual clusters of meaning and their contexts in the Retina. The combination of these fingerprint positions forms the meaning or semantic content of the Fingerprint, effectively reducing meaning and operations on meaning to a mathematically computable problem space.

No knowledge or experience of semantics or Natural Language Processing is required.

cortical.io's Semantic Fingerprint representation allows you to perform all kinds of logical operations at the linguistic or semantic level with absolutely no need for in-depth knowledge of NLP or NLP techniques.

For instance, we can compute the semantic content (meaning) of Jaguar minus the semantic content of Porsche simply by subtracting the Fingerprint positions of Porsche from those of Jaguar. (Essentially all the contexts associated with Porsche which also exist in Jaguar will be removed leaving a Fingerprint of Jaguar which does not include e.g. car related contexts.)

Or, take search as an example. Right now, if you wanted to perform an exhaustive search to find all possible references to car, then you would need to list all possible synonyms for car and search for each of these independently. But with cortical.io's API you simply create a Semantic Fingerprint (a kind of meaning profile) for car and use this as your search pattern – it will match every text which has a similar Semantic Fingerprint, (that is, any text about the subject car), even if the text doesn't contain the actual word car.

cortical.io's APIs provide these functions and more. Explore the possibilities of this new technology and you will be amazed!

If you want to see a demonstration of these APIs then take a look at our Swagger User Interface. http://api.cortical.io/.

Getting started

Step 1: apply for an API key from (http://www.cortical.io/developers_apikey.html).

Step 2: download the current cortical.io Client jar file and add it to your path.

Step 3: start coding.

Let's try getting a list of keywords for a text.

Begin with creating a new TextApi object and initializing it with the API key (which you have just obtained from cortical.io) as the argument to the constructor:

    TextApi myTextApi = new TextApi("insertYourApiKeyHere");
    // Add our input text.
       
    String myText =
      "Our company was founded in 2011 in Vienna, "
      + "Austria, as a science-based start-up with the mission to "
       + "develop and commercialize a breakthrough, "
       + "patent pending technology: the Cortical Engine for Processing Text. The "
       + "fundamentally new approach offered by cortical.io "
       + "is the result of 20 years of growing dissatisfaction "
       + "with the limitations of traditional search "
       + "engines. In all those years, Francisco built information "
       + "retrieval systems in areas like healthcare data, "
       + "technical, scientific and patent publications, "
       + "exploring all facets of existing search paradigms. "
       + "He became aware of their strengths, but, above "
       + "all, of their pitfalls. All existing methods based "
       + "on statistics and linguistics were failing at "
       + "solving the so called \"representational problem\". "
       + "Considering the fact that the human brain does "
       + "solve this practically, Francisco turned his "
       + "attention to the upcoming field of neuroscience. In "
       + "fact, the recent findings on how the brain works offered "
       + "a simple, yet convincing approach to "
       + "solve the representational problem of language.";
       
    // RetinaApi methods mostly return Object so we need to remember to cast to the correct
    // object type. In this case we're expecting a List of String objects to be returned
    // so we cast to List<String>
       
    List<String> keywords = (List<String>) myTextApi.getKeywordsForText(body, retinaName);

It's that easy!

A more detailed look at each of the API methods can be found in the next tutorial sections.

The ApiClient classes


All API classes need to be initialized with the API key via the constructor. For instance:

RetinasApi myRetinasApi = new RetinaApi("insertYourApiKeyHere");

The client API classes are:
  • RetinasApi
  • TermsApi
  • ExpressionsApi
  • TextApi
  • CompareApi
  • FingerprintApi (coming soon)

Note: because many of the methods in our APIs allow the specification of multiple return types, it is necessary to cast the Object return value to the appropriate return type (see code examples).
Failure to cast to the correct return type will most likely result in a RuntimeException in your program.

RetinasApi


This API class has one method getRetinas(String retinaName) with 2 possible return values.

Parameters:
  • retinaName :
    • If the value of this parameter is set to the null object, this method will return a list of all available Retinas (List<Retina>).  If the value of this parameter is set to the name of a specific retina, this method will return a list containing the Retina object associated with that specific name as the first item in the list.

Example for getRetinas()
[returnTypes: List<Retina>]

// Get a listing of all available Retinas.
// term = null --> equates to all terms in the retina
// retinaName = “generic”
// startIndex = null --> equates to default of zero
// maxresults = null --> equates to default of 10

RetinasApi myRetinasApi = new RetinasApi(“insertYourApiKeyHere”);
List<Retina> response = (List<Retina>) myRetinasApi.getRetinas(null);

TermsApi


Create a new TermsApi object.
TermsApi myTermsApi = new TermsApi(“insertYourApiKeyHere”);

This API class has three methods:
  • getTerm(String term, String retinaName, Integer startindex, Integer maxresults)
  • getContextsForTerm(String term, String plotShape, String returnType, String retinaName, Integer startindex, Integer maxresults)
  • getSimilarTerms(String term, Integer contextId, String postype, String plotShape, String returnType, String retinaName, Integer startindex, Integer maxresults)

1. getTerm: provides the capability to get information about a term (or terms) in the Retina. By:
  • Entering a null object value for the term parameter. This will return a list of all the terms (TermInfo) in the Retina. - returnType: ArrayList<TermInfo>
  • Entering a word for the term parameter. This will return the TermInfo object for that word (as the first, and only, item in a list). - returnType: ArrayList<TermInfo>
  • Using the wildcard characters (more details can be found here). - returnType: ArrayList<TermInfo>
Parameters:
  • term : the input term. This is an optional parameter. If not specified, then all terms in the Retina will be returned.
  • retinaName : the name of the retina to use. REQUIRED.
  • startindex : the start index for pagination. This is an optional parameter. If not specified, the default value of zero (0) will be used.
  • maxresults : the maximum number of results. If not specified, the default value of 10 will be used. The maximum number of results per call is limited to 1000.
Examples for getTerm:
[returnTypes: List<TermInfo>]

// This call will result in a list of the first 10 terms (TermInfo objects)
// in the Retina.
// term = null --> equates to all terms in the retina
// retinaName = “generic”
// startindex = null --> equates to default of zero
// maxresults = null --> equates to default of 10

List<TermInfo> response = (List<TermInfo>) myTermsApi.getTerm(null, “generic”, null, null);

//and you could then get the next 10 terms in the Retina with the following call
//by setting the startindex to 10

List<TermInfo> response = (List<TermInfo>) myTermsApi.getTerm(null, “generic”, 10, null);


// Single term: This call will result in a list containing a single TermInfo object
//(for the term “banana”) at position 0 in the list
// term = “banana” // retinaName = “generic”
// startindex = null --> equates to default of zero
// maxresults = null --> equates to default of 10

List<TermInfo> response = (List<TermInfo>) myTermsApi.getTerm(“banana”, “generic”, null, null);

// Wildcard(1): This call will result in a list of the first 10 terms
// (TermInfo objects) in the Retina which begin with the characters “app”
// term = “app*”
// retinaName = “generic”
// startindex = null --> equates to default of zero
// maxresults = null --> equates to default of 10

List<TermInfo> response = (List<TermInfo>) myTermsApi.getTerm(“app*”, “generic”, null, null);

Note: Wildcard(1)
For more information on the wildcard usage and syntax see the section headed Wildcards.


2. getContextsForTerm
: provides the capability to obtain contexts (or representations of contexts) associated with an input term.

Parameters
:
  • term : the input term. This is a REQUIRED parameter.
  • plotShape : the shape of the requested image. One of circle or square. This is an optional parameter. If the image returnType is not requested, this parameter will be ignored. If the image returnType is chosen and this parameter is not specified then the default, circle, will be used.
  • returnType : the requested returnType. One of, context, fingerprint or image. If this parameter is not specified, then the default of “context” will be used.
  • retinaName : the name of the retina to use. REQUIRED.
  • startIndex : the start index for pagination. This is an optional parameter. If not specified, the default value of zero (0) will be used.
  • maxresults : the maximum number of results. If not specified, the default value of 5 will be used. The maximum total number of results is limited to 5.
Examples for getContextsForTerm:
[returnTypes: List<Context>, List<Fingerprint>, List<ByteArrayInputStream>]

// Retrieve Context objects
// This will result in a list of 5 Context objects representing the contexts of
// the input term.
// term = “banana”
// plotShape = null --> equates to default “circle” but is not used because we are
// not returning an “image” type.
// returnType = “context” (List<Context>)
// retinaName = “generic”
// startindex = null --> equates to default of zero
// maxresults = null --> equates to default of 5 which is the absolute maximum
// number of results returnable by this method

List<Context> response = (List<Context>) myTermsApi.getContextsForTerm(“banana”, null, “context”, “generic”, null, null);

// Retrieve Fingerprint objects
// This will result in a list containing the fingerprint representation of the
// context (with context_id = 2) of the input term
// term = “banana” 
// plotShape = null --> equates to default “circle” but not used because we are
// not returning an “image” type
// returnType = “fingerprint” (List<Fingerprint>)
// retinaName = “generic”
// startindex = 2
// maxresults = 1

List<Fingerprint> response = (List<Fingerprint>) myTermsApi.getContextsForTerm(“banana”, null, “fingerprint”, “generic”, 2, 1);

// Retrieve an Image
// This will result in a list of one ByteArrayInputStream object.
// This can be used, as shown below, to obtain a .png image made up of 5 distinct
// images, representing each of the 5 contexts associated with the term.
// term = “banana”
// plotShape = “square”
// returnType = “image” (List<ByteArrayInputStream>)
// retinaName = “generic”
// startIndex = null --> equates to default of zero
// maxresults = null --> equates to default of 5 which is the absolute maximum
// number of results returnable by this method

List<ByteArrayInputStream> response = (List<ByteArrayInputStream>)myTermsApi.getContextsForTerm(“banana”, “square”, “image”, “generic”, null, null); BufferedImage image = ImageIO.read(response.get(0)); File outputfile = new File("contextImage.png"); ImageIO.write(image, "png", outputfile);

3. getSimilarTerms: provides the capability to obtain similar terms (or their representations) associated with an input term.

Parameters:
  • term : the input term. This is a REQUIRED parameter.
  • contextId : the contextId of the term. This is an optional parameter. If the contextId is not specified, then this method will return a list of similarTerms (or their representations) over all contexts.
  • posType : this parameter enables filtering of the results by parts of speech (one of: NOUN, VERB, ADJECTIVE). If this parameter is unspecified, (null), no filtering will occur.
  • plotShape : the shape of the requested image. One of circle or square. This is an optional parameter. If the image returnType is not requested this parameter will be ignored. If the image returnType is chosen and this parameter is not specified then the default, circle, will be used.
  • returnType : the requested returnType. One of, term, fingerprint or image. If this parameter is not specified then the default of “context” will be used.
  • retinaName : the name of the retina to use. REQUIRED.
  • startIndex : the start index for pagination. This is an optional parameter. If not specified the default value of zero (0) will be used.
  • maxresults : the maximum number of results. If not specified the default value of 10 will be used. The maximum total number of results is limited to 10.
Examples for getSimilarTerms:
[returnTypes: List<Term>, List<Fingerprint>, List<ByteArrayInputStream>]

// Retrieve TermResult objects (with the default return type)
// This will result in a list of 10 TermResult objects.
// term = “banana”
// contextId = null --> equates to returning a list of similarTerms over all contexts
// posType = null --> equates to no filtering by part of speech
// plotShape = null --> equates to default “circle” but not used because we are
// not returning an “image” type.
// returnType = null --> equates to default (List<TermResult>)
// retinaName = “generic”
// startindex = null --> equates to default of zero
// maxresults = null --> equates to default of 10 which is the absolute maximum
// number of results returnable by this method.

List<TermResult> simTermsList = (List<TermResult>)myTermsApi.getSimilarTerms(“banana”, null, null, null, null, “generic”, null, null);

// Retrieve Fingerprint objects
// This will result in a list of 10 Fingerprint objects.
// term = “banana”
// contextId = 0 --> equates to returning a list of fingerprints similar in
// semantics to the 0th context of the input term.
// posType = “NOUN” --> only similarTerms which are nouns.
// plotShape = null --> equates to default “circle” but not used because we are
// not returning an “image” type.
// returnType = “fingerprint”
// retinaName = “generic”
// startindex = null --> equates to default of zero
// maxresults = null --> equates to default of 10 which is the absolute maximum // number of results returnable by this method.

List<Fingerprint> simTermsList = (List<Fingerprint>)myTermsApi.getSimilarTerms(“banana”, 0, “NOUN”, null, “fingerprint”, “generic”, null, null);

// Retrieve ByteArrayInputStream objects
// This will result in a list of one ByteArrayInputStream object. This can be used
// to obtain a .png image made up of 10 distinct
// images representing each of the 10 similarTerms (over all contexts) associated
// with the input term.
// term = “banana”
// contextId = 0 --> equates to returning a list of image representations similar
// in semantics to the 0th context of the input term.
// posType = “VERB” --> only similarTerms which are verbs.
// plotShape = null --> equates to default “circle”
// returnType = “image”
// retinaName = “generic”
// startindex = null --> equates to default of zero
// maxresults = null --> equates to default of 10 which is the absolute maximum number
// of results returnable by this method.

List<ByteArrayInputStream> simTermsList = (List<ByteArrayInputStream>)myTermsApi.getSimilarTerms(“banana”, 0, “VERB”, null, “image”, “generic”, null, null);

ExpressionsApi


Create a new ExpressionsApi object.

ExpressionsApi myExpressionsApi = new ExpressionsApi("insertYourApiKeyHere");

This API class has three methods:
  • resolveExpression(String body, String plotShape, String returnType, String retinaName)
  • getContextsForExpression(String body, String plotShape, String returnType, String retinaName, Integer startindex, Integer maxresults)
  • getSimilarTermsForExpressionContext(String body, Integer contextId, String postype, String plotShape, String returnType, String retinaName, Integer startindex, Integer maxresults)
1. resolveExpression: provides the capability to input an Expression and get a Retina representation of that expression. Note that the expression needs to conform to cortical.io's expression syntax which is based on JSON.
See the section “Expressions & Expression syntax” for more detailed information on expressions.

Parameters:
  • body : The expression to be evaluated. REQUIRED.
  • plotShape : the shape of the requested image. One of circle or square. This is an optional parameter. If the image returnType is not requested this parameter will be ignored. If the image returnType is chosen and this parameter is not specified then the default, circle, will be used.
  • returnType : the requested returnType. One of fingerprint or image. If this parameter is not specified then the default of “fingerprint” will be used.
  • retinaName : the name of the retina to use. REQUIRED.
Example for resolveExpressions:
[returnTypes: List<Fingerprint>, List<ByteArrayInputStream>]

// Get the fingerprint of a simple expression
// This will result in a list of 1 Fingerprint Object
// Note that the expression needs to conform to cortical.io's expression syntax which is
// based on JSON.
// body =
// plotShape = null --> equates to default “circle” but not used because we are
// not returning an “image” type.
// returnType = null --> equates to default (List<Fingerprint>)
// retinaName = “generic”
// expression --> subtract “jaguar” from “tiger”

String body = “{ \"sub\": [{ \"term\": \"jaguar\"},{ \"term\": \"tiger\"}]}”;

// Remember to cast to the expected returnType. Here we are getting the default which
// for this method is a List of Fingerprint.

List<Fingerprint> fingerprintList = (List<Fingerprint>)myExpressionsApi.resolveExpression(body, null, null, “generic”);

// and as this is a list of just one item, the fingerprint we want will be the first
//(and only) item in the list.

Fingerprint fp = fingerprintList.get(0);

2. getContextsForExpression: provides the capability to obtain contexts (or representations of contexts) associated with an input expression.

Parameters:
  • body : The expression to be evaluated. REQUIRED.
  • plotShape : the shape of the requested image. One of circle or square. This is an optional parameter. If the image returnType is not requested this parameter will be ignored. If the image returnType is chosen and this parameter is not specified then the default, circle, will be used.
  • returnType : the requested returnType. One of context, fingerprint or image. If this parameter is not specified then the default of “context” will be used.
  • retinaName : the name of the retina to use. REQUIRED.
  • startindex : the start index for pagination. This is an optional parameter. If not specified the default value of zero (0) will be used.
  • maxresults : the maximum number of results. If not specified the default value of 5 will be used. The maximum total number of results is limited to 5 for this method.
Example for getContextForExpressions:
[returnTypes: List<Context>, List<Fingerprint>, List<ByteArrayInputStream>]

// Get the semantic contexts of a simple expression
// This will result in a list of 5 Context objects
// body = { \"sub\": [{ \"term\": \"jaguar\"},{ \"term\": \"tiger\"}]}
// plotShape = null --> equates to default “circle” but not used because we are
// not returning an “image” type.
// returnType = null --> equates to default (List<TermResult>)
// retinaName = “generic”
// startindex = null --> equates to default of zero
// maxresults = null --> equates to default of 10 which is the absolute maximum number
// of results returnable by this method.
// expression --> subtract “jaguar” from “tiger”

String body = “{ \"sub\": [{ \"term\": \"jaguar\"},{ \"term\": \"tiger\"}]}”;

// Remember to cast to the expected returnType. Here we are getting the default which
// for this method is a List of Context objects.

List<Context> contextList = (List<Context>)myExpressionsApi.getContextsForExpression(body, null, null, “generic”, null, null);

3. getSimilarTermsForExpression: provides the capability to obtain similar terms (or representations thereof).

Parameters:
  • body : The expression to be evaluated. REQUIRED.
  • contextId : This is an optional parameter. If the contextId is not specified then this method will return a list over all contexts.
  • posType : this parameter enables filtering of the results by parts of speech (one of: NOUN, VERB, ADJECTIVE). If this parameter is unspecified, (null), no filtering will occur.
  • plotShape : the shape of the requested image. One of circle or square. This is an optional parameter. If the image returnType is not requested this parameter will be ignored. If the image returnType is chosen and this parameter is not specified then the default, circle, will be used.
  • returnType : the requested returnType. One of term, fingerprint or image. If this parameter is not specified then the default of “term” will be used.
  • retinaName : the name of the retina to use. REQUIRED.
  • startindex : the start index for pagination. This is an optional parameter. If not specified the default value of zero (0) will be used.
  • maxresults : the maximum number of results. If not specified the default value of 10 will be used. The maximum total number of results is limited to 100 for this method.
Example for getSimilarTermsForExpressions:
[returnTypes: List<Term>, List<Fingerprint>, List<ByteArrayInputStream>]

// This will result in a list of 10 Term objects
// Note that the expression needs to conform to cortical.io's expression syntax which is
// based on JSON.
// body = { \"sub\": [{ \"term\": \"jaguar\"},{ \"term\": \"tiger\"}]}
// contextId = null --> equates to ALL contexts.
// posType = “NOUN”
// plotShape = null --> equates to default “circle” but not used because we are
// not returning an “image” type.
// returnType = null --> equates to default (List<Term>)
// retinaName = “generic”
// startindex = null --> equates to default of zero
// maxresults = null --> equates to default of 10.
// expression --> subtract “jaguar” from “tiger”

String body = “{ \"sub\": [{ \"term\": \"jaguar\"},{ \"term\": \"tiger\"}]}”;

// Remember to cast to the expected returnType. Here we are getting the default,
// which for this method is a List of Term objects.

List<Term> termList = (List<Term>)myExpressionsApi.getSimilarTermsForExpression(body, null, “NOUN”, null, null, “generic”, null, null);

TextApi


Create a new TextApi object.

TextApi myTextApi = new TextApi("insertYourApiKeyHere");

This API class has three methods:
  • getRepresentationForText(String body, String plotShape, String returnType, String retinaName)
  • getKeywordsForText(String body, String retinaName)
  • getSlicesForText(String body, String plotShape, String returnType, String retinaName, Integer startindex, Integer maxresults)
1. getRepresentationForText: provides the capability to get a Retina representation of an input text.

Parameters:
  • body : The input text. REQUIRED.
  • plotShape : the shape of the requested image. One of circle or square. This is an optional parameter. If the image returnType is not requested, this parameter will be ignored. If the image returnType is chosen and this parameter is not specified then the default, circle, will be used.
  • returnType : the requested returnType. One of fingerprint or image. If this parameter is not specified, then the default of “fingerprint” will be used.
  • retinaName : the name of the retina to use. REQUIRED.
Example for getRepresentationForText:
[returnTypes: List<Fingerprint>, List<ByteArrayInputStream>]

// Get a Retina representation of an input text.
// This will result in a list of 1 ByteArrayInputStream.
// body = the input text
// plotShape = null --> equates to default “circle”.
// returnType = “image”
// retinaName = “generic”

TextApi myTextApi = new TextApi(“insertYourApiKeyHere”);

// expression --> subtract “jaguar” from “tiger”    
String myText = "Our company was founded in 2011 in Vienna, "
       + "Austria, as a science-based start-up with the mission to "
       + "develop and commercialize a breakthrough, patent pending "
       + "technology: the Cortical Engine for Processing Text. The "
       + "fundamentally new approach offered by "
       + "cortical.io is the result of 20 years of growing dissatisfaction "
       + "with the limitations of traditional search engines. "
       + "In all those years, Francisco built information "
       + "retrieval systems in areas like healthcare data, "
       + "technical, scientific and patent publications, "
       + "exploring all facets of existing search paradigms. "
       + "He became aware of their strengths, but, above "
       + "all, of their pitfalls. All existing methods based "
       + "on statistics and linguistics were failing at "
       + "solving the so called \"representational problem\". "
       + "Considering the fact that the human brain does "
       + "solve this practically, Francisco turned his attention "
       + "to the upcoming field of neuroscience. In "
       + "fact, the recent findings on how the brain works "
       + "offered a simple, yet convincing approach to "
       + "solve the representational problem of language.";

// Remember to cast to the expected returnType. Here we are expecting a List
// of ByteArrayInputStream.

List<ByteArrayInputStream> baisList = (List<ByteArrayInputStream>)myTextApi.getRepresentationForText(body, null, “image”, “generic”);


2. getKeywordsForText: provides the capability to get a list of keywords from an input text.

Parameters:
  • body : The input text. REQUIRED.
  • retinaName : the name of the retina to use. REQUIRED.

Example for getKeyWordsForText:
[returnTypes: List<String>]

// Get a list of keywords for an input text.
// This will result in a list of String. There is currently only one returnType for
// this method so no need to specify.
// body = the input text
// retinaName = “generic”

TextApi myTextApi = new TextApi(“myApiKey”);

String myText = "Our company was founded in 2011 in Vienna, "
       + "Austria, as a science-based start-up with the mission to "
       + "develop and commercialize a breakthrough, patent pending "
       + "technology: the Cortical Engine for Processing Text. The "
       + "fundamentally new approach offered by "
       + "cortical.io is the result of 20 years of growing dissatisfaction "
       + "with the limitations of traditional search engines. "
       + "In all those years, Francisco built information "
       + "retrieval systems in areas like healthcare data, "
       + "technical, scientific and patent publications, "
       + "exploring all facets of existing search paradigms. "
       + "He became aware of their strengths, but, above "
       + "all, of their pitfalls. All existing methods based "
       + "on statistics and linguistics were failing at "
       + "solving the so called \"representational problem\". "
       + "Considering the fact that the human brain does "
       + "solve this practically, Francisco turned his attention "
       + "to the upcoming field of neuroscience. In "
       + "fact, the recent findings on how the brain works "
       + "offered a simple, yet convincing approach to "
       + "solve the representational problem of language.";

// RetinaApi methods mostly return Object so we need to remember to cast to the
// correct object type. In this case we're expecting a List of String objects to
// be returned so we cast to List<String>

List<String> keywords = (List<String>)myTextApi.getKeywordsForText(body, “generic”);

3. getSlicesForText: provides the capability to get an input text chunked into slices. This can be returned as a list of text slices, a list of fingerprints (representing the slices), or a list of images.

Parameters:
  • body : The input text. REQUIRED.
  • plotShape : the shape of the requested image. One of circle or square. This is an optional parameter. If the image returnType is not requested, this parameter will be ignored. If the image returnType is chosen and this parameter is not specified then the default, circle, will be used.
  • returnType : the requested returnType. One of fingerprint or image. If this parameter is not specified, then the default of “fingerprint” will be used.
  • retinaName : the name of the retina to use. REQUIRED.
  • startindex : the start index for pagination. This is an optional parameter. If not specified, the default value of zero (0) will be used.
  • maxresults : the maximum number of results. If not specified, the default value of 10 will be used. If the image returnType is used, then the maximum total number of results per page is limited to 10.
Example for getSlicesForText:
[returnTypes: List<String>]

// Get a list of slices for an input text
// This will result in a list of the first 10 slices from the input text.
// body = the input text
// plotShape = null --> equates to default “circle” but not used as our return type
// is “slice” (String).
// returnType = “slice”
// retinaName = “generic”
// startindex = null --> equates to default of zero
// maxresults = null --> equates to default of 10.

TextApi myTextApi = new TextApi(“myApiKey”);

String myText = "Our company was founded in 2011 in Vienna, "
       + "Austria, as a science-based start-up with the mission to "
       + "develop and commercialize a breakthrough, patent pending "
       + "technology: the Cortical Engine for Processing Text. The "
       + "fundamentally new approach offered by "
       + "cortical.io is the result of 20 years of growing dissatisfaction "
       + "with the limitations of traditional search engines. "
       + "In all those years, Francisco built information "
       + "retrieval systems in areas like healthcare data, "
       + "technical, scientific and patent publications, "
       + "exploring all facets of existing search paradigms. "
       + "He became aware of their strengths, but, above "
       + "all, of their pitfalls. All existing methods based "
       + "on statistics and linguistics were failing at "
       + "solving the so called \"representational problem\". "
       + "Considering the fact that the human brain does "
       + "solve this practically, Francisco turned his attention "
       + "to the upcoming field of neuroscience. In "
       + "fact, the recent findings on how the brain works "
       + "offered a simple, yet convincing approach to "
       + "solve the representational problem of language.";

// RetinaApi methods mostly return Object so we need to remember to cast to the
// correct object type. In this case we're expecting a List of String objects to
// be returned so we cast to List<String>

List<String> slices = (List<String>)myTextApi.getSlicesForText(body, null, “slice”, “generic”, null, null);

CompareApi


Create a new CompareApi object.

CompareApi myCompareApi = new CompareApi("insertYourApiKeyHere");

This API class has one method:
  • compare(String body, String plotShape, Integer imageScalar, String returnType, String retinaName, Integer startindex, Integer maxresults)
compare: provides the capability to compare two elements, where an element can be any of: fingerprint (positions), term (word, compound term), or text. The input to this method must be a JSON list. For example:

[
  {
    "term": "jaguar"
  },
  {
    "positions": [73, 74, 79, 490, 502, 517, 801, 814, 826]
  }
]

Parameters:
  • body : The input pair to compare. REQUIRED.
  • plotShape : the shape of the requested image. One of circle or square. This is an optional parameter. If the image returnType is not requested, this parameter will be ignored. If the image returnType is chosen and this parameter is not specified then the default, circle, will be used.
  • returnType : the requested returnType. One of metric or image. If this parameter is not specified, then the default of “fingerprint” will be used. The metric return type is a Map containing an ordered list of similarity metrics and their respective values.
  • retinaName : the name of the retina to use. REQUIRED.

// Compare a term and a position
// This will result in a map of multiple similarity metrics. 
// jsonList = the input JSON list.
// plotShape = null --> equates to default “circle” but not used as our return type
// is “slice” (String).
// returnType = null --> equates to a return type of “metric”
// retinaName = “generic”

CompareApi myCompareApi = new CompareApi(“myApiKey”);

String jsonList = [{"term": "jaguar"}, {"positions": [73, 74, 79, 490, 502, 517, 801, 814, 826]}];

// RetinaApi methods mostly return Object so we need to remember to cast to the
// correct object type.
// In this case we're expecting a TreeMap<String, Double> object.

TreeMap<String, Double> comparisonMap = (TreeMap<String, Double>)myCompareApi.compare(jsonList, null, null, “generic”);

Wildcards


The wildcard characters are:
  • the asterisk *
    • representing zero or more characters.
  • the question mark ?
    • representing exactly one character.
The wildcard characters must be preceded initially by at least 3 characters.

E.g.   app*
This would result in a list such as the following: app, app store, appa, appachan ... etc.

E.g.   app?
This would result in a list such as the following: appa, appe ... etc.

Wildcards can also be combined and/or used multiple times in the same query.

E.g.   ban*n*a?
Would return something like the following: banana bread, banana leaf ... etc.

While only the terms themselves are listed in these examples, in reality a list of TermInfo objects (each containing a term) would be returned.

Expressions


Expression operators in the cortical.io Client are:
  • sub : subtract.
  • and : the logical AND operation.
  • xor : the logical exclusive OR operation.
  • or : the logical OR operation.
Expressions in the cortical.io Client APIs must be input in JSON format.
For example, to perform a logical AND operation of the semantic content of lion with eagle we could do the following:

{
   "and": [
           {
             "term": "lion"
           },
           {
             "term": "eagle"
            }
   ]
}

It is also possible to mix different representations in cortical.io Expressions.
For example, we could subtract the semantic content of a Fingerprint from that of jaguar in the following way:

{
  "sub": [
       {
          "term": "jaguar"
       },
       {
          "positions": [2, 3, 4, 5]
       }
   ]
}

The following elements are all legal elements in a cortical.io Expression:
  • terms e.g. "term": "car"
  • the positions of a fingerprint e.g. "positions": [8, 72, 105, 106]
  • text e.g. “Our technology is offered through an API and deployed using a Software-as-a-Service model. This approach has the advantage of keeping the lab-to-market time to the minimum. It is our declared goal to make it as easy as possible to experiment and adopt this fundamentally new technology. As soon as you have made yourself familiar with this new approach to natural language processing, a wide variety of functionalities can be implemented intuitively, without needing any knowledge in linguistics. We provide a growing number of client-SDKs to allow easy integration in various application environments.”
There must be at least one element in a cortical.io Expression.

Some of you may have noticed by now that the operations listed under the /terms/contexts and /terms/similarTerms endpoints can also be input as expressions under the /expressions/contexts and /expressions/similarTerms endpoints.
For instance to get terms which are similar to “banana” using the ExpressionsAPI would simply require the input of the following Expression syntax:

{
  "term": "banana"
}

JSON


Inputs to the ExpressionsApi and CompareApi must be formatted using JSON syntax (Javascript Object Notation).
More information on JSON can be found at: http://www.json.org/

There are many free JSON validators online such as:

Class Descriptions


Retina {

              String getRetinaName()
              Integer getNumberOfTermsInRetina()
}

Term {
           String getTerm()
           Double getScore()
}

TermInfo {
                 String getTerm()
                 Double getDf() List<String> getPosTypes()
}

Fingerprint {
                    List<Integer> getPositions()
}

Context {
               Integer getContextId()
               String getContextLabel()
}

FAQs - Technical


Retinas:
  • What is a Retina?
    • A Retina is a semantic vector model. The fundamental concept behind cortical.io's Retina consists of converting the symbolic representation of language into a Sparse Distributed Representation (SDR) form so that it becomes numerically computable.
  • What does morphologically stemmed retina mean?
    • Basically, this means that the inflected forms of words in the retina have been reduced to their base or root form. For instance, branch, branched, branching, branches will have all been reduced to the base form branch.
  • What is a non stemmed retina?
    • As an example: without stemming, searching for the term branched would only return occurrences of branched, but with stemming, searching on branched would return anything which resolves to the same root form (that is, branched, branching, branch, branches).
  • What it a synonymous retina, what is an associative retina and what is the difference between them?
    • The distinction between synonymous and associative Retinas is based on findings in cognitive linguistics. Based on word priming experimentation, two main relations between words have been identified (see [1]): synonymous relations (also referred to as similar or semantic relations in the cognitive science literature) and associative relations.
      As outlined in [1], the distinction for both relationship types is not exclusive; that is, word relations are not exclusively synonymous or associative. Doctor - Nurse is an example of a word relation that can be considered or as of a synonymous-associative nature. Due to their aim of replicating human word understanding this also applies to the Retinas.

      Two terms/words are associatively related if they often appear in a shared context. The following are examples of this type of relationship:
      • Spider - Web
      • Google - Page rank
      • Smoke - Cigarette
      • Phone - Call
      • Lighter - Fire
      Two terms/words are synonymously related if they share common features. The following are examples of this type of relationship:
      • Wolf - Dog
      • Whale - Dolphin
      • Astronaut - Man
      • Car - Van
      • Smartphone - iPhone 4s
  • Which Retinas are associative and which are synonymous and how can they be used?
    • en_associative is an associatively focused Retina. The development for this type of Retina is motivated by the aim of disambiguating terms, i.e. identifying which meanings are contained within a specific term. As an example, the following call identifies the potential meanings of the term plane: 
      http://api.cortical.io/rest/terms/contexts?retinaName=en_associative&term=plane&start-index=0&max-results=10
    • en_synonymous is a synonymously focused Retina. The development of this type of Retina is driven by the aim of identifying synonymous items for terms or texts. As an example, the following call identifies different types of diseases:
      http://api.cortical.io/rest/terms/similarTerms?retinaName=en_synonymous&term=disease&start-index=0&max-results=100
  • Note: the above example links also require an api key.

Operations with terms:

  • What does df mean in the Response Body?
    • This is an abbreviation of the phrase document frequency - the number of documents in which a given term appears.
  • When selecting the returnType fingerprint, I get a list of numbers: what do they represent?
    • The numbers represent the points in the retina which form the semantic content of, for instance, a term, or a phrase or the result of an expression.
  • What is a Fingerprint?
    • A Fingerprint is a unique semantic representation within the Retina. The positions in a Fingerprint represent particular nodes or clusters of meaning in the Retina and the combination of these nodes forms the semantic content. This Fingerprint representation enables logical operations on terms. For instance, we can compute the semantic content of Jaguar minus the semantic content of Porsche. Or we could build up a synthetic fingerprint, a kind of profile, and use this as a semantic filter.
  • In the list of similar terms, each term is followed by a score, e.g. 0.61523...: what does this score stand for?
    • This score is a similarity value indicating how close this term is to the "base" term which you input. The closer this number is to 1, the more similar the term is to your original base term.

Operations with expressions:

  • What is a retina representation? What is it good for?
    • This means a representation of your input calculated from the retina. This can be either a Fingerprint or an Image. A Fingerprint can for example be used as an intelligent search term. Images can be used as visual representations of semantic content (with respect to the retina).

Keywords:

  • Can I change the number of keywords the system retrieves?
    • Currently this isn't possible.
  • Can I change the type of keywords (e.g. only nouns or person names) the system retrieves?
    • Currently this isn't possible.
  • Is the list ordered randomly or are the most relevant keywords at the top?
    • The list ordering is by relevance - from most relevant to least relevant.
  • Is there a maximum size to the text I can copy?
    • Currently the public API doesn't limit the size of input text.

Compare:

  • What is the Cosine-similarity?
  • What is the Euclidian Distance?
  • What is the Jaccard Distance?
    • The Jaccard distance, which measures dissimilarity between sample sets, is complementary to the Jaccard coefficient and is obtained by subtracting the Jaccard coefficient from 1.  http://en.wikipedia.org/wiki/Jaccard_index
  • What is the difference between "overlapping left-right" and "overlapping right-left"?
    • It is a percentage over the number of positions. Left-right means the percentage of positions of the left side included in the right side and vice versa.
  • What is the Weighted Scoring?
    • This is a cortical.io defined weighting for similarity measures. The higher the weighting the more similar the terms.

Footnotes:

  • [1] Chiarello, Christine, et al. "Semantic and associative priming in the cerebral hemispheres: Some words do, some words don't... sometimes, some places." Brain and language 38.1 (1990): 75-104












Feedback and Knowledge Base