New installation

After installing sentiment.ai from CRAN, you will need to make sure you have a compatible python environment for tensorflow and tensorflow-text. As this can be a cumbersome experience, we included a convenience function to install that for you:

install_sentiment.ai()

This only needs to be run the first time you install the package. If you’re feeling adventurous, you can modify the environment it will create with the following paramaters:

• envname - the name of the virtual environment

• method - if you specifically want “conda” or “virtualenv”

• gpu - set to TRUE if you want to run tensorflow-gpu

• python_version - The python version used in the virtual environment

• modules - a names list of the dependencies and versions

# Just leave this as default unless you have a good reason to change it. 
# This is quite dependent on specific versions of python moduules
install_sentiment.ai()

Assuming you’re using RStudio, it can be helpful to go to tools > global options > python > python interpreter and set your new tensorflow-ready environment as the default interpreter. There’salso an option for automatically setting project-level environments,

Note for GPU installations: you’ll need to make sure you have a compatible version of CUDA installed. Here is a helpful guide to pick your CUDA version: https://www.tensorflow.org/install/source#gpu

Initialize

You’ll probably want to initialize the language embedding model first if you want to 1) not use the default models, and 2) want to re-apply sentiment scoring without the overhead of preparing the embedding model in memory. Pre-initializing with init_sentiment.ai() is useful for making downstream sentiment scoring and matching run smoothly, especially on GPU.

Technically init_sentiment.ai() will give access to a function called sentiment.ai_embed$f() which uses the pre-trained tensorflow model to embed a vector of text. Power users, the curious, and the damned may want to look in (Helper Functions for an example of this magic)[#power-move].

init_sentiment.ai() has the following optional paramaters:

# NOTEL In most cases all you need is this:!!
init_sentiment.ai()

# To change the default behavior:
# e.g. to initialise for use on multi lingual comments:
# leave envname alone unless you have a good reason to change it! 
init_sentiment.ai(model = "multi.large")

sentiment_score()

For most use cases, sentiment_score() is the function you’ll use.

Returns a vector of sentiment scores. The scores are a rescaled probability of being positive (i.e 0 to 1 scaled as -1 to 1). These are calculated with a secondary scoring model which, by default is from xgboost (a simple GLM is available if for some reason xgboost doesn’t work for you!).

The paramaters sentiment_score() takes are:

• x character vector to analyse.

• model (optional) the name of the embedding model you are using (from init_sentiment.ai())

• scoring (optional) the method of scoring sentiment. Options are xgb (default) and glm. xgb is generally more powerful, but requires xgboost (shouldn’t be an issue!), glm is faster and almost as powerful (can be better for more ‘black and white’ use cases)

• scoring_version (optional) “1.0” is the default and (currently) only option. In future this will allow you to use updated/improved models.

• batch_szie (optional) determines how many rows are processed at a time. On CPU this doesn’t change much, but can be important if you installed the GPU version. Put simply, small bathes take longer but use less RAM/VRAM, large batches run faster on GPU but could exhaust memopry if too large. Default is 100 (works reliably on an RTX 2080)

Note that if init_sentiment.ai() has not been called before, the function will try to recover by calling it into the default environment. If you’re using CUDA/GPU acceleration, you’ll see a lot of work happening in the console as the model is compiled on the GPU.

For example:

my_comments <- c("Will you marry me?", "Oh, you're breaking up with me...")

# for English, default is fine
sentiment_score(my_comments)

sentiment_match()

Sometimes you want to classify comments too. For that, we added sentiment_match() which takes a list of positive and negative terms/phrases and returs a dataframe like so:

While there are default lists of positive and negative phrases, you can overwrite them with your own. In this way you can quickly make inferences about the class of comments from your specific domain. The sentiment score is the same as calling sentiment_score() but you also get the most similar phrase, the category of that phrase, and the cosine similarity to the closest phrase.

For example:

my_comments <- c("Will you marry me?", "Oh, you're breaking up with me...")

my_positives <- c("excited", "loving", "content", "happy")
my_negatives <- c("lame", "lonely", "sad", "angry")

my_categories <- list(positive = my_positives, negative = my_negatives)

result <- sentiment_match(x = my_comments, phrases = my_categories)

print(result)

##                                 text  sentiment phrase    class similarity
## 1:                Will you marry me?  0.5393031 loving positive  0.1723714
## 2: Oh, you're breaking up with me... -0.6585207    sad negative  0.1512707

Note Cosine similarity is relative here & longer text will tend to have lower overall similarity to a specific phrase!

Note 2 You can also be tricky and pass in a list of arbitrary themes rather than just positive and negative - in this way sentiment.ai can do arbitrary category matching for you!

cosine()

A light equivilent of text2vec::sim2 that gives pairwise cosine similarity between each row of a matrix.

x1 <- matrix(rnorm(4 * 6), 
             ncol = 6,
             dimnames = list(c("a", "b", "c", "d"), 1:6))

x2 <- matrix(rnorm(4 * 6), 
             ncol = 6,
             dimnames = list(c("w", "x", "y", "z"), 1:6 ))

# to check that it's the same result
# all.equal(cosine(x1, x2), text2vec::sim2(x1, x2))

cosine(x1, x2)

##            w          x           y           z
## a -0.1776981 -0.1743733  0.04111033  0.88174300
## b -0.5699782  0.6938432  0.21893192  0.05391341
## c  0.5076042  0.0169079  0.04563749  0.38885764
## d  0.2050958 -0.7644069 -0.74160285 -0.13175003

cosine_match()

This is a helper function to take two matrices, compute their cosine similarity, and give a pairwise ranked table. For example:

cosine_match(target = x1, reference = x2)

##     target reference  similarity rank
##  1:      a         w -0.17769814    4
##  2:      b         w -0.56997820    4
##  3:      c         w  0.50760421    1
##  4:      d         w  0.20509577    1
##  5:      a         x -0.17437331    3
##  6:      b         x  0.69384318    1
##  7:      c         x  0.01690790    4
##  8:      d         x -0.76440688    4
##  9:      a         y  0.04111033    2
## 10:      b         y  0.21893192    2
## 11:      c         y  0.04563749    3
## 12:      d         y -0.74160285    3
## 13:      a         z  0.88174300    1
## 14:      b         z  0.05391341    3
## 15:      c         z  0.38885764    2
## 16:      d         z -0.13175003    2

If you filter that to only the rows where rank is 1, you’ll have a table of the top matches between target and reference.

embed_text()

As an added bonus of manually calling init_sentiment.ai() you can call embed_text() to turn a vector of text into a numeric embedding matrix (e.g if you want to cluster comments).

For example

# Note, there's some weird behavior when you do this with a single string! 
test_target <- c("dogs", "cat", "IT", "computer")
test_ref    <- c("animals", "technology")

# Work it!
target_mx <- embed_text(test_target)
ref_mx    <- embed_text(test_ref)
ref_mx[1:2, 1:4]

##                    [,1]       [,2]       [,3]          [,4]
## animals    -0.042174224 0.01914462 0.07767479 -0.0362021662
## technology  0.005067721 0.02222563 0.06019276  0.0006833972

# And slay.
result <- cosine_match(target_mx, ref_mx)
result[rank==1] # filtered to top match (with data.table's [] syntax)

##      target  reference similarity rank
## 1:     dogs    animals  0.8034535    1
## 2:      cat    animals  0.6122806    1
## 3:       IT technology  0.4383662    1
## 4: computer technology  0.6668407    1

RPyTools is not available

this happens on Windows sometimes. It appears to be a problem with Reticulate in RStudio. Weirdly the solution is to restart R and try the exact same thing again.

Running on a proxy server/docker container

We’ve found it difficult to change environment for Reticulate in this case - try installing into the base r-reticulate environment.

Rstudio & changing python environment.

As above. I’ve only encountered this a few times, I think it’s an issue of Rstudio countermanding the python environment. You can either install in the base reticulate environment OR go to tools > global options > python and force it to use r-sentiment.ai (or whatever environment you want)

You may see this message if that’s going to be an issue:

"The RETICULATE_PYTHON environment variable is set, which can be due to being in a project (regardless of whether the global/project Python options are set), having the global/project Python options set, or having RETICULATE_PYTHON in your .Renviron file or bash/zsh rc files."

Error messages about missing python modules

Either something went wrong in install_sentiment.ai() OR Reticulate isn’t changing to the r-sentiment.ai() environment (see points above).

Error in py_run_file_impl(file, local, convert)

If you see a message like this:

Preparing Model
Error in py_run_file_impl(file, local, convert) : AttributeError: module 'tensorflow.python.feature_column.feature_column_v2' has no attribute '_BaseFeaturesLayer'

It may be due to a previously activated reticulate environment. e.g if you run reticulate::py_config() reticulate seems to set your environment to r-reticulate and won’t let that change, which may mess with your tensorflow setup. Starting a new R session seems to fix that.

Using a newer version of Tensorflow

Do so at your own risk! In my experience tensorflow and its dependencies are somewhat lacking in the forwards and backwards compatibility departments having an “it’s different now - deal with it” approach… If you experiment and manage get it working faster with a newer Tensorflow setup, let us know so we can update the package! If you want to use an older Tensorflow version you may be out of luck as the Universal Sentence Encoder models need the new(ish) tensorflow-text module.

Other errors during installation of python packages

May include incorrect tls/ssl configurations (‘pip is configured with locations that require TLS/SSL, however the ssl module in Python is not available’). Please see the following for advice on possible solutions to solve this problem, solutions may include ensuring correct path environment variables and/or resolving dll conflicts.
+ Solutions for different operating systems : https://stackoverflow.com/questions/45954528/pip-is-configured-with-locations-that-require-tls-ssl-however-the-ssl-module-in + DLL Conflicts : https://stackoverflow.com/questions/41328451/ssl-module-in-python-is-not-available-when-installing-package-with-pip3

NVIDIA CUDA missing dependencies

If running on GPU, you’ll need need to make sure you have a compatible CUDA setup for tensorflow 2.4.1. For a list of compatible configurations, see https://www.tensorflow.org/install/source#gpu. On my personal Ubuntu 20 build, I ran into issues with libcublas.so - see this comment which helped me to get CUDA working properly. Interestingly, Windows has been the least hassle to get tensorflow running on GPU!

GPU on OSX

This will be a challenge as Apple now have their own fork of Tensorflow, which we have not yet made a setup script for. If you want to use GPU acceleration on OSX, you’ll need to configure your own environment, but if you do get it working, please let us know what config worked!

Running inside of Rmarkdown

This is a bit unhappy, but it you call init_sentiment.ai() in the R console before knitting, it works happily.