EmoTouch R Webservice Dokumentation

Aus emoTouch
Zur Navigation springen Zur Suche springen

Additional documentation

Additional documentation is served by swagger when running R web service: 

http://127.0.0.1:8000/__docs__/

Results structure

Results from R web service are always wrapped in a list to provide error handling and extra metadata about the returned object.

on R side

In case of successfully computed request (of a function returning scalar integer value 3): 

list( 
   error =  NULL,
   results =  3L,
   type =  "integer",
   length =  1L 
)

In case of an error: 

list( 
   error =  "an error message",
   results =  NULL ,
   type =  NULL,
   length =  NULL 
)

on JavaScript side

Note that results field is always boxed, even for scalar result: 

{"error":{},"result":[3],"type":"double","length":1}

An error: 

{"error":"an error message","result":{},"type":{},"length":{}}


Functions

All functions that takes any arguments are meant to be called as POST method. Those without arguments via GET method.

version

Returns the version of the R webservice. Takes no arguments. 

curl -H "Content-Type: application/json" http://localhost:8000/version

{"error":{},"result":["0.3"],"type":"character","length":1}

degap

Synchronize multiple series according to their indexes. Fill gaps with Last Observation Carried Forward. Indices provided in idx must have same sampling rate. Arguments:

  • x: list of series of numeric values.
  • idx: list of series of indexes, must be same number of series as series provided to x, must have same length as corresponding series provided to x.
  • sync: boolean default to true, takes min and max index from all indices to expand all series of x into it. See examples below.
  • how: character, default "locf" means that gaps are filled with last observation carried forward, could be also "nocb" for next observation carried backward, or "const" for the constant value specified in fill argument.
  • fill: numeric to be used when how="const".

examples of sync=true (default), sampling rate 1. 

x1    = [4,5,8,7,6]
x2    = [2,3,4,5,7]
idx1  = [2,3,5,6,8]
idx2  = [0,1,3,4,6]

synchronized indices 

idx12 = [0,1,2,3,4,5,6,7,8]
x1gap = [ , ,4,5, ,8,7, ,6]
x2gap = [2,3, ,4,5, ,7, , ]

gaps filled with locf (default) 

x1out = [ , ,4,5,5,8,7,7,6]
x2out = [2,3,3,4,5,5,7,7,7]

Note that x and idx can contain 1+ series.

Working example of 2 series (sampling rate 2): 

curl -H "Content-Type: application/json" --data '{"x": [[1,2.5,3,4,5.5,6,7,8],[1.5,3.5,4,4,5.5,6,7]],"idx": [[0,2,4,8,10,14,16,18],[0,2,4,6,8,14,18]]}' http://localhost:8000/degap
#{"error":{}, "result":[[1,2.5,3,3,4,5.5,5.5,6,7,8],[1.5,3.5,4,4,5.5,5.5,5.5,6,6,7]], "type":"length":2}

When sync=false then each series has gaps filled only within its own min-max boundaries. According to use cases discussed, use of sync=false and how!="locf" should be considered undesired.

Graphical representation of the function: 

x = c(4,6.5,3,4,7.5,4,8,9)
idx = c(0,1,2,4,5,6,7,9)


(((((Platzhalter Bild)))))))


norm

Normalizes multiple series. Arguments:

  • x: list of series of numeric values to normalize.
  • how: character, default "max", other supported values are "mean/sd" and "diff". The method used to normalize values, described below.

Note that x can contain 1+ series. 

# max
x / max(x)

# mean/sd
(x - mean(x)) / sd(x)

# diff # Lagged Differences: https://stat.ethz.ch/R-manual/R-devel/library/base/html/diff.html

diff(x)

Working example of 2 series, three different how argument values 

curl -H "Content-Type: application/json" --data '{"x":[[1,2.5,3,3,4,5.5,5.5,6,7,8],[1.5,3.5,4,4,5.5,5.5,5.5,6,6,7]],"how":"max"}' http://localhost:8000/norm
#{"error":{},"result":[[0.125,0.3125,0.375,0.375,0.5,0.6875,0.6875,0.75,0.875,1],[0.2143,0.5,0.5714,0.5714,0.7857,0.7857,0.7857,0.8571,0.8571,1]],"type":"list","length":2}

curl -H "Content-Type: application/json" --data '{"x":[[1,2.5,3,3,4,5.5,5.5,6,7,8],[1.5,3.5,4,4,5.5,5.5,5.5,6,6,7]],"how":"mean/sd"}' http://localhost:8000/norm
#{"error":{},"result":[[-1.6106,-0.9301,-0.7032,-0.7032,-0.2495,0.431,0.431,0.6578,1.1115,1.5652],[-2.0944,-0.844,-0.5314,-0.5314,0.4064,0.4064,0.4064,0.719,0.719,1.3442]],"type":"list","length":2}

curl -H "Content-Type: application/json" --data '{"x":[[1,2.5,3,3,4,5.5,5.5,6,7,8],[1.5,3.5,4,4,5.5,5.5,5.5,6,6,7]],"how":"diff"}' http://localhost:8000/norm
#{"error":{},"result":[[1.5,0.5,0,1,1.5,0,0.5,1,1],[2,0.5,0,1.5,0,0,0.5,0,1]],"type":"list","length":2}

Graphical representation of the function: 

x = c(4, 6.5, 3, 3, 4, 7.5, 4, 8, 8, 9)


(((((((Platzhalter Bild ))))))


denoise

Applies noise reduction over provided series. Arguments:

  • x: list of series of numeric values to apply noise reduction.
  • n: integer size of smoothing window.
  • how: character, default "median", also supported "mean". The method used to reduce noise.

Note that x can contain 1+ series.

n-1 leading observations are computed on partial window. 


# median of last 3 observations
curl -H "Content-Type: application/json" --data '{"x":[[-1.6106,-0.9301,-0.7032,-0.7032,-0.2495,0.431,0.431,0.6578,1.1115,1.5652],[-2.0944,-0.844,-0.5314,-0.5314,0.4064,0.4064,0.4064,0.719,0.719,1.3442]],"n":3,"how":"median"}' http://localhost:8000/denoise
#{"error":{},"result":[[-1.6106,-1.2704,-0.9301,-0.7032,-0.7032,-0.2495,0.431,0.431,0.6578,1.1115],[-2.0944,-1.4692,-0.844,-0.5314,-0.5314,0.4064,0.4064,0.4064,0.719,0.719]],"type":"list","length":2}

# mean of last 3 observations

curl -H "Content-Type: application/json" --data '{"x":[[-1.6106,-0.9301,-0.7032,-0.7032,-0.2495,0.431,0.431,0.6578,1.1115,1.5652],[-2.0944,-0.844,-0.5314,-0.5314,0.4064,0.4064,0.4064,0.719,0.719,1.3442]],"n":3,"how":"mean"}' http://localhost:8000/denoise 

#{"error":{},"result":[[-1.6106,-1.2704,-1.0813,-0.7788,-0.552,-0.1739,0.2042,0.5066,0.7334,1.1115],[-2.0944,-1.4692,-1.1566,-0.6356,-0.2188,0.0938,0.4064,0.5106,0.6148,0.9274]],"type":"list","length":2}

# mean of last 5 observations

curl -H "Content-Type: application/json" --data '{"x":[[-1.6106,-0.9301,-0.7032,-0.7032,-0.2495,0.431,0.431,0.6578,1.1115,1.5652],[-2.0944,-0.844,-0.5314,-0.5314,0.4064,0.4064,0.4064,0.719,0.719,1.3442]],"n":5,"how":"mean"}' http://localhost:8000/denoise 

#{"error":{},"result":[[-1.6106,-1.2704,-1.0813,-0.9868,-0.8393,-0.431,-0.1588,0.1134,0.4764,0.8393],[-2.0944,-1.4692,-1.1566,-1.0003,-0.719,-0.2188,0.0313,0.2814,0.5314,0.719]],"type":"list","length":2}

Graphical representation of the function: 

x = c(4, 6.5, 3, 3, 4, 7.5, 4, 8, 8, 9)


((((((((Platzhalter Bild))))))))


degap_norm_denoise

This function wraps around 3 other functions degap, norm and denoise. For detailed argument description see mentioned functions above. Arguments:

  • x: list of series of numeric values.
  • degap.idx: idx passed to degap.
  • degaps.sync: sync passed to degap.
  • degap.how: how passed to degap.
  • degap.fill: fill passed to degap.
  • norm.how: how passed to norm.
  • denoise.n: n passed to denoise.
  • denoise.how: how passed to denoise.
curl -H "Content-Type: application/json" --data '{"x":[[1,2.5,3,4,5.5,6,7,8],[1.5,3.5,4,4,5.5,6,7]],"degap.idx":[[0,2,4,8,10,14,16,18],[0,2,4,6,8,14,18]],"norm.how":"max","denoise.n":3,"denoise.how":"mean"} ' http://localhost:8000/degap_norm_denoise
#{"error":{},"result":[[0.125,0.2188,0.2708,0.3542,0.4167,0.5208,0.625,0.7083,0.7708,0.875],[0.2143,0.3571,0.4286,0.5476,0.6429,0.7143,0.7857,0.8095,0.8333,0.9048]],"type":"list","length":2}

Graphical representation of the function: 

x = c(4,6.5,3,4,7.5,4,8,9)
idx = c(0,1,2,4,5,6,7,9)


((((((((Platzhalter Bild ))))))))

dists

Computes time series distance statistics: autocorrelation, cross correlation, dynamic time warping, granger test p-value. Arguments:

  • x: first numeric series.
  • y: second numeric series.
  • granger.order: pass to granger test as order argument.

Note that x is not a list of numeric series but a single numeric series. Similarly y. 

curl -H "Content-Type: application/json" --data '{"x":[-1.6106,-1.2703,-0.9301,-0.7032,-0.7032,-0.2495,0.431,0.431,0.6578,1.1115],"y":[-2.0944,-1.4692,-0.844,-0.5314,-0.5314,0.4064,0.4064,0.4064,0.719,0.719],"granger.order":5}' http://localhost:8000/dists
#{"error":{},"result":{"acf":[0.1071],"ccor":[0.3566],"dtw":[2.6025],"gran":[0]},"type":"list","length":4}

Granger test p-value may be 0 in case when its function raises aliased coefficients error or perfect fit warning.

Horizontal scaling

R package valve can provide concurrency for requests to R webservice API.

Maintainer

Jan Gorecki

Abgerufen von „https://wiki.emotouch.de/index.php?title=EmoTouch_R_Webservice_Dokumentation&oldid=4123“