1 | #Plotly Node API
|
2 | [![Circle CI](https://circleci.com/gh/plotly/plotly-nodejs/tree/master.svg?style=svg)](https://circleci.com/gh/plotly/plotly-nodejs/tree/master)
|
3 | > Analyze and Visualize Data, Together
|
4 |
|
5 |
|
6 | If you have a question about streaming let us know or open an issue!
|
7 |
|
8 | `ben@plot.ly` && `alexandre@plot.ly`
|
9 |
|
10 | ## Streaming Plot Examples
|
11 | - [mock sensor stream](http://plot.ly/~streaming-demos/6/)
|
12 | - [math bar fight](http://plot.ly/~streaming-demos/44/)
|
13 |
|
14 | ##Installation
|
15 | ```javascript
|
16 | npm install plotly
|
17 | ```
|
18 |
|
19 | ##Usage
|
20 | ```javascript
|
21 | var plotly = require('plotly')('username','apiKey');
|
22 |
|
23 | var data = [{x:[], y:[], stream:{token:'yourStreamtoken', maxpoints:200}}];
|
24 | var graphOptions = {fileopt : "extend", filename : "nodenodenode"};
|
25 |
|
26 | plotly.plot(data,graphOptions,function() {
|
27 | var stream = plotly.stream('yourStreamtoken', function (res) {
|
28 | console.log(res);
|
29 | });
|
30 | someReadableStream.pipe(stream);
|
31 | });
|
32 | ```
|
33 |
|
34 | ####Full REST API Documentation can be found here: [https://plot.ly/api/rest/](https://plot.ly/api/rest/)
|
35 |
|
36 | Sign up for plotly here: [https://plot.ly/](https://plot.ly/) and obtain your API key and Stream Tokens in your plotly settings: [https://plot.ly/settings](https://plot.ly/settings).
|
37 |
|
38 | #Methods
|
39 | ##var plotly = require('plotly')(username, apiKey)
|
40 | `username` is a string containing your username
|
41 | `apiKey` is a string containing your API key
|
42 | ```javascript
|
43 | var plotly = require('plotly')('username', 'apiKey');
|
44 | ```
|
45 |
|
46 | ##plotly.plot(data,graphOptions[, callback])
|
47 | Plotly graphs are described declaratively with a data JSON Object and a graphOptions JSON Object.
|
48 | `data` is an array of Objects and with each object containing data and styling information of separate graph traces. Docs: [https://plot.ly/api/rest](https://plot.ly/api/rest)
|
49 | `graphOptions` is an Object containing styling options like axis information and titles for your graph. Docs: [https://plot.ly/api/rest](https://plot.ly/api/rest)
|
50 | `callback(err,msg)` where `err` is an error Object, and `msg` is the return response Object
|
51 |
|
52 | The `msg` object has the following attributes : `msg.url`,`msg.filename`,`msg.message`,`msg.warning`,`msg.error`
|
53 | ```javascript
|
54 | // examples/rest-example.js
|
55 |
|
56 | var plotly = require('plotly')('username','apiKey');
|
57 |
|
58 | var data = [{x:[0,1,2], y:[3,2,1], type: 'bar'}];
|
59 | var graphOptions = {fileopt : "extend", filename : "nodenodenode"};
|
60 |
|
61 | plotly.plot(data, graphOptions, function (err, msg) {
|
62 | console.log(msg);
|
63 | });
|
64 | ```
|
65 | ##var stream = plotly.stream(token[, callback])
|
66 | `token` accepts a token string
|
67 | `callback(res)` where `res` is a the response object with the following attributes : `res.msg`, `res.statusCode`
|
68 |
|
69 | ```javascript
|
70 | // examples/streaming-example.js
|
71 | var plotly = require('plotly')('username','apiKey');
|
72 |
|
73 | var initData = [{x:[], y:[], stream:{token:'token', maxpoints:200}}];
|
74 | var initGraphOptions = {fileopt : "extend", filename : "nodenodenode"};
|
75 |
|
76 | plotly.plot(initData, initGraphOptions, function (err, msg) {
|
77 | if (err) return console.log(err)
|
78 | console.log(msg);
|
79 |
|
80 | var stream1 = plotly.stream('token', function (err, res) {
|
81 | console.log(err, res);
|
82 | clearInterval(loop); // once stream is closed, stop writing
|
83 | });
|
84 |
|
85 | var i = 0;
|
86 | var loop = setInterval(function () {
|
87 | var streamObject = JSON.stringify({ x : i, y : i });
|
88 | stream1.write(streamObject+'\n');
|
89 | i++;
|
90 | }, 1000);
|
91 | });
|
92 | ```
|
93 |
|
94 | [Live Streaming Example](https://plot.ly/~Streaming-Demos/6/)
|
95 | ```javascript
|
96 | // examples/signal-stream.js
|
97 |
|
98 | /* If you have not signed up for Plotly you can do so using https://plot.ly
|
99 | * or see the example signup.js. Once you do, populate the config.json in this
|
100 | * example folder!
|
101 | */
|
102 | var config = require('./config.json')
|
103 | , username = config['user']
|
104 | , apiKey = config['apiKey']
|
105 | , token = config['token']
|
106 | , Plotly = require('../.')(username, apiKey)
|
107 | , Signal = require('random-signal')
|
108 |
|
109 |
|
110 | // build a data object - see https://plot.ly/api/rest/docs for information
|
111 | var data = {
|
112 | 'x':[] // empty arrays since we will be streaming our data to into these arrays
|
113 | , 'y':[]
|
114 | , 'type':'scatter'
|
115 | , 'mode':'lines+markers'
|
116 | , marker: {
|
117 | color: "rgba(31, 119, 180, 0.96)"
|
118 | }
|
119 | , line: {
|
120 | color:"rgba(31, 119, 180, 0.31)"
|
121 | }
|
122 | , stream: {
|
123 | "token": token
|
124 | , "maxpoints": 100
|
125 | }
|
126 | }
|
127 |
|
128 | // build your layout and file options
|
129 | var graphOptions = {
|
130 | "filename": "streamSimpleSensor"
|
131 | , "fileopt": "overwrite"
|
132 | , "layout": {
|
133 | "title": "streaming mock sensor data"
|
134 | }
|
135 | , "world_readable": true
|
136 | }
|
137 |
|
138 | /*
|
139 | * Call plotly.plot to set the file up.
|
140 | * If you have included a streaming token
|
141 | * you should get a "All Streams Go!" message
|
142 | */
|
143 |
|
144 | Plotly.plot(data, graphOptions, function (err, resp) {
|
145 | if (err) return console.log("ERROR", err)
|
146 |
|
147 | console.log(resp)
|
148 |
|
149 | var plotlystream = Plotly.stream(token, function () {})
|
150 | var signalstream = Signal({tdelta: 100}) //
|
151 |
|
152 |
|
153 | plotlystream.on("error", function (err) {
|
154 | signalstream.destroy()
|
155 | })
|
156 |
|
157 | // Okay - stream to our plot!
|
158 | signalstream.pipe(plotlystream)
|
159 | })
|
160 | ```
|
161 |
|
162 |
|
163 | ##plotly.getFigure(fileOwner, fileId[, callback])
|
164 | `file_owner` accepts a string of the file owner's name
|
165 | `fileId` is an integer, representing the graph ID
|
166 | `callback(figure)` where `figure` is a the JSON object of the graph figure
|
167 |
|
168 | ```javascript
|
169 | var plotly = require('plotly')('username','apiKey');
|
170 |
|
171 | plotly.getFigure('fileOwner', 'fileId', function (err, figure) {
|
172 | if (err) console.log(err);
|
173 | console.log(figure);
|
174 | });
|
175 | ```
|
176 |
|
177 | ##plotly.getImage(figure[, options, callback])
|
178 | `figure` is a JSON object of the graph figure
|
179 | `options.format` | `jpg`, `png`, `pdf`, `eps`, `webp`
|
180 | `options.width` | width in `px` (default : 700)
|
181 | `options.height` | height in `px` (default : 500)
|
182 |
|
183 | `callback(err, imageData)`
|
184 |
|
185 | `err` is an Error Object
|
186 | `imageData` is a `base64`-encoded string
|
187 |
|
188 | ```javascript
|
189 | var plotly = require('plotly')('username','apiKey');
|
190 | var fs = require('fs');
|
191 |
|
192 | var trace1 = {
|
193 | x: [1, 2, 3, 4],
|
194 | y: [10, 15, 13, 17],
|
195 | type: "scatter"
|
196 | };
|
197 |
|
198 | var figure = { 'data': [trace1] };
|
199 |
|
200 | var imgOpts = {
|
201 | format: 'png',
|
202 | width: 1000,
|
203 | height: 500
|
204 | };
|
205 |
|
206 | plotly.getImage(figure, imgOpts, function (error, imageData) {
|
207 | fs.writeFile('1.png', imageData, 'base64');
|
208 | });
|
209 | ```
|
210 |
|
211 | You can also use `getFigure()` and `getImage()` together!
|
212 | ```javascript
|
213 | var plotly = require('../.')('username','apiKey');
|
214 |
|
215 | // grab the figure from an existing plot
|
216 | plotly.getFigure('fileOwner', 'fileId', function (err, figure) {
|
217 | if (err) return console.log(err);
|
218 |
|
219 | var imgOpts = {
|
220 | format: 'png',
|
221 | width: 1000,
|
222 | height: 500
|
223 | };
|
224 |
|
225 | plotly.getImage(figure, imgOpts, function (error, imageData) {
|
226 | fs.writeFile('1.png', imageData, 'base64');
|
227 | });
|
228 | });
|
229 | ```
|