Document

API Reference related to getting information from a specific document that has been analyzed.

lxaGetDocumentDetails

Summary: Retrieves various bits of useful information about the current text including term frequency analysis and document chunk information.

The acConfigurationID parameter specifies the configuration for the results, which are returned in a SalienceDocumentDetails structure. Configurations are defined using the method lxaAddSalienceConfiguration.

Call lxaFreeDocumentDetails when you are finished with the information to free any allocated memory.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaGetDocumentDetails(SalienceSession *pSession, SalienceDocumentDetails *pDetails, const char *acConfigurationID);

Parameter

Description

pSession

Pointer to a SalienceSession structure previously returned by a call to lxaOpenSalienceSession

pDetails

Pointer to a SalienceDocumentDetails structure

acConfigurationID

Character string specifying the configuration for the results, blank for the default configuration

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with 
  a valid LexalyticsLicense */

  char *acBuffer = "This is some text to process";
  SalienceSession *pSession;
  SalienceDocumentDetails oDetails;

  if(lxaOpenSalienceSession(oLicense, &oStartup, &pSession) != LXA_OK) {
    return 1;
  }

  lxaPrepareText(pSession,acBuffer);
  lxaGetDocumentDetails(pSession,&oDetails);
  lxaFreeDocumentDetails(&oDetails);

    // ...

  lxaCloseSalienceSession(pSession);

lxaGetSummary

Summary: Retrieves summary information for the current text. The SalienceSummaryResult structure provides a default summary and an alternate summary, as well as ranking for the sentences in the summary.

The default summary method determines the most significant fragments in the document, and extracts the first sentence from those fragments. The alternate method extracts sentences that connect the most fragments.

The acConfigurationID parameter specifies the configuration for the results, which are returned in a SalienceSummaryResult structure. Configurations are defined using the method lxaAddSalienceConfiguration.

After use you should free the result structure using lxaFreeSummaryResult.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaGetSummary(SalienceSession *pSession, int nLength, SalienceSummaryResult *pResult, const char *acConfigurationID);

Parameter

Description

pSession

Pointer to a SalienceSession structure previously returned by a call to lxaOpenSalienceSession

nLength

Length, in number of sentences, of the summary you want returned

pResult

Pointer to a SalienceSummaryResult structure

acConfigurationID

Character string specifying the configuration for the results, blank for the default configuration

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with 
  a valid LexalyticsLicense */

  char *acPath = "/path/to/content";
  SalienceSummaryResult oSummary;
  SalienceSession *pSession;

  lxaPrepareTextFromFile(pSession, acPath);
  lxaGetSummary(pSession, 4, &oSummary);

  std::cout << "Summary: " << oSummary.acSummary << std::endl;
  std::cout << "Alternate summary: " << oSummary.acAlternateSummary << std::endl;

  lxaFreeSummaryResult(oSummary);

    // ...

  lxaCloseSalienceSession(pSession);

lxaGetSentiment

Summary: Retrieves sentiment analysis of the document text. This consists of results for phrase-based and model-based sentiment analysis.

The acConfigurationID parameter specifies the configuration for the results, which are returned in a SalienceSentimentResult structure. Configurations are defined using the method lxaAddSalienceConfiguration.

Call lxaFreeSentimentResult when you are finished with the information to free any allocated memory.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaGetSentiment(SalienceSession *pSession, int nUseChains, SalienceSentimentResult *pResult, const char *acConfigurationID);

Parameter

Description

pSession

Pointer to a SalienceSession structure previously returned by a call to lxaOpenSalienceSession

nUseChains

Specifies if lexical chaining should be used to calculate sentiment

pResult

Pointer to a SalienceSentimentResult structure

acConfigurationID

Character string specifying the configuration for the results, blank for the default configuration

Notes on 'nUseChains':
Lexical chaining provides an improvement in quality of result in most cases. It specifically assists with dealing with ambiguity and determinations of cohesion and discourse. For more information https://en.wikipedia.org/wiki/Lexical_chain is a good place to start.

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with 
  a valid LexalyticsLicense */

  char *acPath = "/path/to/content";

  lxaPrepareTextFromFile(pSession, acPath);
  SalienceSentimentResult oResult;
  lxaGetSentiment(pSession, 1, &oResult);

  //Phrase-based sentiment results
  std::cout << "Document Sentiment: " << oResult.fScore << std::endl;

  SalienceSentimentPhraseList sspList = oResult.oPhrases;
  for(int i = 0; i < sspList.nLength; i++) {
    std::cout << "oPhrase: " << sspList.pPhrases->oPhrase.acText << std::endl;
    std::cout << "oSupportingPhrase: " << sspList.pPhrases->oSupportingPhrase.acText;
  }

  //Model-based sentiment results
  SalienceSentimentModel *ssm = oResult.pModel;
  std::cout << "Model:\t" << ssm->acModelName << std::endl;
  std::cout << "Best:\t" << ssm->nBest << std::endl;
  std::cout << "Pos:\t" << ssm->fPositive << std::endl;
  std::cout << "Neg:\t" << ssm->fNegative << std::endl;
  std::cout << "Mixed:\t" << ssm->fMixed << std::endl;
  std::cout << "Count:\t" << oResult.nModelCount << std::endl;

  lxaFreeSentimentResult(&oResult);

    // ...

  lxaCloseSalienceSession(pSession);

lxaGetThemes

Summary: Retrieves the document-level themes of the text.

The acConfigurationID parameter specifies the configuration for the results, which are returned in a SalienceThemeList structure. Configurations are defined using the method lxaAddSalienceConfiguration.

After use you should free the allocated memory by calling lxaFreeThemeList.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaGetThemes(SalienceSession *pSession, SalienceThemeList *pResults, const char *acConfigurationID);

Parameter

Description

pSession

Pointer to a SalienceSession structure previously returned by a call to lxaOpenSalienceSession

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with 
    a valid LexalyticsLicense */

  char *acPath = "/path/to/content";

  lxaPrepareTextFromFile(pSession, acPath);
  SalienceThemeList oThemeList;
  lxaGetThemes(pSession, &oThemeList);

  for(int i = 0; i < oThemeList.nLength; i++) {
    printf("%d", i);
  }

  lxaFreeTopicList(&oTopicList);

    // ...

  lxaCloseSalienceSession(pSession);

lxaGetQueryDefinedTopics

Summary: Retrieves the topics determined for the text via user-defined queries. Before calling this method, you must specify the topic list using the Topic List option.

The acConfigurationID parameter specifies the configuration for the results, which are returned in a SalienceTopicList structure. Configurations are defined using the method lxaAddSalienceConfiguration.

After use you should free the allocated memory by calling lxaFreeTopicList.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaGetQueryDefinedTopics(SalienceSession *pSession, SalienceTopicList *pTopicList, const char *acConfigurationID);

Parameter

Description

pSession

Pointer to a SalienceSession structure previously returned by a call to lxaOpenSalienceSession

pTopicList

Pointer to a SalienceTopicList structure

acConfigurationID

Character string specifying the configuration for the results, blank for the default configuration

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with 
  a valid LexalyticsLicense */

  SalienceOption oOption;
  oOption.nOption = SALIENCEOPTION_QUERYTOPICLIST;
  oOption.acValue = "/path/to/topic/list";
  lxaSetSalienceOption(pSession, &oOption);

  lxaPrepareTextFromFile(pSession, acPath);          
  SalienceTopicList oTopicList;
  lxaGetQueryDefinedTopics(pSession, &oTopicList);
  std::cout << "Query-Defined Topics: " << std::endl;

  for(int i = 0; i < oTopicList.nLength; i++) {
    std::cout << "Topic: " << oTopicList.pTopics[i].acTopic << std::endl;
    std::cout << "\tTopic Sentiment: " << oTopicList.pTopics[i].fSentiment << std::endl;
    std::cout << "\tHit(s): " << oTopicList.pTopics[i].nHits << "\n" << std::endl;
  }

  lxaFreeTopicList(&oTopicList);

  // ...

  lxaCloseSalienceSession(pSession);

lxaGetConceptDefinedTopics

Summary: Retrieves the topics determined for the text via the Salience 6 Concept Matrix. Before calling this method, you must specify a concept topic list using the Concept Topic List option.

The acConfigurationID parameter specifies the configuration for the results, which are returned in a SalienceTopicList structure. Configurations are defined using the method lxaAddSalienceConfiguration.

After use you should free the allocated memory by calling lxaFreeTopicList.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaGetConceptDefinedTopics(SalienceSession *pSession, SalienceTopicList *pTopicList, const char *acConfigurationID);

Parameter

Description

pSession

Pointer to a SalienceSession structure previously returned by a call to lxaOpenSalienceSession.

pTopicList

Pointer to a SalienceTopicList structure.

acConfigurationID

Character string specifying the configuration for the results, blank for the default configuration.

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with 
  a valid LexalyticsLicense */

  SalienceOption oOption;
  oOption.nOption = SALIENCEOPTION_CONCEPTTOPICLIST;
  oOption.acValue = "/path/to/concept/topic/list";
  lxaSetSalienceOption(pSession, &oOption);

  lxaPrepareTextFromFile(pSession, acPath);          
  SalienceTopicList oTopicList;
  lxaGetConceptDefinedTopics(pSession, &oTopicList);
  std::cout << "Concept Topics: " << std::endl;

  for(int i = 0; i < oTopicList.nLength; i++) {
    std::cout << "Topic: " << oTopicList.pTopics[i].acTopic << std::endl;
    std::cout << "\tTopic Sentiment: " << oTopicList.pTopics[i].fSentiment << std::endl;
    std::cout << "\tHit(s): " << oTopicList.pTopics[i].nHits << "\n" << std::endl;
  }

  lxaFreeTopicList(&oTopicList);

  // ...

  lxaCloseSalienceSession(pSession);

lxaExplainConceptMatches

Summary: Retrieves the topics determined for the text via the Salience 6 Concept Matrix, as well as terms from the content that generated the match. Before calling this method, you must specify a concept topic list using the ConceptTopicList option.

This method has a longer execution time than the call to lxaGetConceptDefinedTopics and should be reserved for use in diagnostic or research interfaces or other application areas where a longer execution time is feasible.

The acConfigurationID parameter specifies the configuration for the results, which are returned via a pointer to a character buffer. Configurations are defined using the method lxaAddSalienceConfiguration.

After use you should free the allocated memory by calling lxaFreeString.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaExplainConceptMatches(SalienceSession *pSession, char **ppBuffer, const char *acConfigurationID);

Parameter

Description

pSession

Pointer to a SalienceSession structure previously returned by a call to lxaOpenSalienceSession

ppBuffer

Pointer to a character buffer containing a concept matches and a list of terms with match scores

acConfigurationID

Character string specifying the configuration for the results, blank for the default configuration

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with 
  a valid LexalyticsLicense */

    char *acPath = "path/to/the/file";

  SalienceOption oOption;
  oOption.nOption = SALIENCEOPTION_CONCEPTTOPICLIST;
  oOption.acValue = "/path/to/concept/topic/list";
  lxaSetSalienceOption(pSession, &oOption);

  char* acConceptMatches;
  lxaPrepareTextFromFile(pSession, acPath);          
  lxaExplainConceptMatches(pSession, &acConceptMatches);

  std::cout << "Concept Topics: " << std::endl;
  std::cout << acConceptMatches << std::endl;
  lxaFreeString(&acConceptMatches);

  // ...

  lxaCloseSalienceSession(pSession);

lxaGetDocumentCategories

Summary: Retrieves the categories for a document based on a predefined taxonomy, which can be tuned through additional data files.

The acConfigurationID parameter specifies the configuration for the results, which are returned in a SalienceTopicList structure. Configurations are defined using the method lxaAddSalienceConfiguration.

After use you should free the allocated memory by calling lxaFreeTopicList.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaGetDocumentCategories(SalienceSession *pSession, SalienceTopicList *pTopicList, const char *acConfigurationID);

Parameter

Description

pSession

Pointer to a SalienceSession structure previously returned by a call to lxaOpenSalienceSession

pTopicList

Pointer to a SalienceTopicList structure

acConfigurationID

Character string specifying the configuration for the results, blank for the default configuration

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with 
  a valid LexalyticsLicense */

    char *acPath = "path/to/the/file";

  lxaPrepareTextFromFile(pSession, acPath);

    // Call to lxaGetDocumentCategories and store results in oCategories
  SalienceTopicList oCategories;
  lxaGetDocumentCategories(pSession, &oCategories);

    // Print to standard output stream
    std::cout << "Document Categories: " << std::endl;
  for(int i = 0; i < oCategories.nLength; i++) {
    std::cout << "Category: " << oCategories.pTopics[i].acTopic << std::endl;
  }

    // Free memory and close SalienceSession
  lxaFreeTopicList(&oCategories);

  // ...

  lxaCloseSalienceSession(pSession);

lxaGetDocumentClasses

Summary: Retrieves the classifications for a document based on the provided classification model. The classification model is set using the ClassificationModel option.

The acConfigurationID parameter specifies the configuration for the results, which are returned in a SalienceTopicList structure. Configurations are defined using the method lxaAddSalienceConfiguration.

After use you should free the allocated memory by calling lxaFreeTopicList.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaGetDocumentClasses(SalienceSession *pSession, SalienceTopicList *pResult, const char *acConfigurationID);

Parameter

Description

pSession

Pointer to a SalienceSession structure previously returned by a call to lxaOpenSalienceSession

pResult

Pointer to a SalienceTopicList structure

acConfigurationID

Character string specifying the configuration for the results, blank for the default configuration

Example
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with 
  a valid LexalyticsLicense */

    char *acPath = "path/to/the/file";

  lxaPrepareTextFromFile(pSession, acPath);          
  SalienceTopicList oClasses;
  lxaGetDocumentClasses(pSession, &oClasses);

    // Print to standard output stream
  std::cout << "Document Classes: " << std::endl;
  for(int i = 0; i < oClasses.nLength; i++) {
    std::cout << "Class: " << oClasses.pTopics[i].acTopic << std::endl;
  }

    // Free memory and close SalienceSession
  lxaFreeTopicList(&oClasses);

  // ...

  lxaCloseSalienceSession(pSession);

lxaGetIntentions

Summary: Retrieves the intentions expressed within the document content. Intentions are returned as a list of SalienceIntention structures.

The acConfigurationID parameter specifies the configuration for the results. Configurations are defined using the method lxaAddSalienceConfiguration.

After use you should free the allocated memory by calling lxaFreeIntentionList.

Returns: Integer return code. To retrieve more information on the return code use lxaGetLastWarnings on the SalienceSession structure.

More information on errors and warnings can be found in the Errors and Warning Codes section of our documentation.

Function Signature:
int lxaGetIntentions(SalienceSession *pSession, SalienceIntentionList *pResults, const char *acConfigurationID);

Parameter

Description

pSession

Pointer to a SalienceSession structure previously returned by a call to lxaOpenSalienceSession

pResults

Pointer to a SalienceIntentionList structure

acConfigurationID

Character string specifying the configuration for the results, blank for the default configuration

Example:
Use lxaLoadLicense to create LexalyticsLicense structure. This will then be given to lxaOpenSalienceSession, which is then used to start a session with Salience.

/* Assuming a SalienceSession (*pSession) has already been opened with 
  a valid LexalyticsLicense */
    
    char *acPath = "path/to/the/file";

  lxaPrepareTextFromFile(pSession, acPath);

    // Call to lxaGetIntentions and store results in oIntentions
  SalienceIntentionList oIntentions;
  lxaGetIntentions(pSession, &oIntentions);

  // Print to standard output stream
  std::cout << "Intentions: " << std::endl;
  for(int i = 0; i < oIntentions.nLength; i++) {
    std::cout << "Intention: " << oIntentions.pResults[i].acType << "\t" 
      << oIntentions.pResults[i].acEvidence << std::endl;
  }

    // Free memory and close SalienceSession
  lxaFreeIntentionList(&oIntentions);

  // ...

  lxaCloseSalienceSession(pSession);