Series and Comparisons

Adding a series to your chart is easy.

If you have your data ready to go in an array,just call stxx.addSeries("GE",{color:"red", data:yourDataArrayHere});

If you are using the library's quoteFeed ,just call stxx.addSeries("GE",{color:"red", data:{useDefaultQuoteFeed:true}});

If the data is already a field in your masterData array, just call stxx.addSeries("OPEN",{color:"red"});

addSeries(field, parameters) will return a reference to the series. field should be the name of your new series and parameters is an object that describes how to display the series including the data to use.

See STXChart#addSeries for a complete list of parameters and a variety of examples.

To remove a series call stxx.removeSeries("GE"); .

Example:

Note on legacy requirements: Versions prior to 04-2015 need to explicitly call createDataSet() and draw() to activate the series. This is not required on version 04-2015 and above.

Example of legacy method:

 stxx.addSeries("T", {
    color: "blue",
    data: getDataFromServer("T"),
    chartType:'line',
    width:4
});
stxx.createDataSet();
stxx.draw();

Internals

Internally, when you include the 'data' parameter, the method embeds a new element on each masterData object for each series you add. If you want to add a series for an element that is already part of the masterData, the 'data' parameter can be excluded. The following is an example of what one of the masterData elements would look like if you wanted to display additional series for "IBM' and 'GE':

Date: "201504161135"
GE: 34.56
High: 155.33
IBM: 184.32
Low: 141.09
Open: 154.54
Volume: 14732

Additionally, each series is linked to a renderer which can be further customized to group series together in a specific fashion. If a color is defined when the series is added, then a default renderer will be created and used to quickly and simply render your series immediately. Otherwise if you need to further define rendering settings, you can add a series without a color definition and it will simply be prepared and set, but will need a renderer to be manually linked to it to be displayed. This is desirable when you want to have multiple series share the same structure, as in a stacked histogram, where each bar on the histogram can be composed by multiple elements, each one belonging to a different series, but rendered together as one stacked bar. See STXChart#addSeries and Renderers for full details.

Series legend

If you want a legend to appear when a series is added to the chart, you must first define the location in stx.chart.legend. This is done by providing the x and y coordinates for the first element in the legend as follows:

stxx.chart.legend={
    x: yourXlocation,
    y: yourYlocation
};

Once set, a legend item for each series you add will be added as defined by your STXChart.Chart#legendRenderer function, which by defaults draws legend items horizontally, but you can customize to render any way you prefer. stxx.chart.legendRenderer

legend

Input Data format

If you are using the quoteFeed and set the data:{useDefaultQuoteFeed:true} parameter, all the data fetching and formatting will be automatically done for you, as well as any updates required to keep the series in sync with the primary symbol.

If you are manually pushing your own data, you must create an array of objects; each containing the following elements:

DT – A JavaScript Date() object. Either DT or Date is required.
Date – A date or datetime string . Either DT or Date is required.
Value – The value of the data point

Note 1: As an alternative to Value, Close can be used since your quote feed may already be returning the data using this element name.

Note 2: Value and Close must be integers, not strings! Use parseFloat() if your data server provides strings.

Note 3: Date format must follow 'US style' rather than 'European style'. As such the year or the month must lead the date instead of the day. Examples:'yyyymmddhhmm','yyyymmdd','yyyy-mm-dd'T'hh:mm:ss.SSS','mm-dd-yyyy'T'hh:mm:ss.SSS','yyyy-mm-dd hh:mm:ss','mm-dd-yyyy hh:mm:ss','yyyy-mm-dd hh:mm:ss AM/PM','yyyy-mm-dd','mm-dd-yyyy' ('-' or '/' are permitted)

Data Example:

[{Date:'yyyy-mm-dd hh:mm:ss', Value: 100.00},{Date:'yyyy-mm-dd hh:mm:ss', Value: 101}...]

or

[{Date:'yyyy-mm-dd hh:mm:ss', Close: 100.00},{Date:'yyyy-mm-dd hh:mm:ss', Close: 101}...]

Manual load example:

stxx.addSeries("GE", {
    color: "red",
    data: [
        {Date:'10/4/2012',Value:42.68},
        {Date:'10/5/2012',Value:41.33},
        {Date:'10/6/2012',Value:40.21},
        {Date:'10/7/2012',Value:43.76},
        {Date:'10/8/2012',Value:42.17},
        {Date:'10/9/2012',Value:41.75}
    ]
});

Adding a series for existing data

Imagine you want to draw a series based on the 'Close' price which is already pat of the masterData , you jut call:

stxx.addSeries("Open", { color: "black" });

and leave out the 'data' parameter since it is already in the masterData for the series to use.

See it working here:

Example:

Advanced settings

The series library will accommodate continuous or sporadic data points. If the data for the series can be measured in the same interval as the primary symbol, the series will render as be a continuous line. In contrast, a "dividend" payment for example, would only occur on a quarterly basis (sporadic). Sporadic data points are automatically connected with continuous lines, however if type="step" is selected in parameters, then the line will be drawn horizontally between sporadic points and then step vertically to the next point, like stairsteps. You can alternatively set sporadic points to connect using dashed lines by defining a color and pattern in parameters.gaps . You can also have the series lined to the default y axis or create a new axis on the other side of the chart. See STXChart#addSeries and Renderers for full details

Here is an example of series using a left axis:

Users can delete a series the same way that they can delete an overlay, by hovering over it and right clicking (or tapping the trashcan icon on a touch device). To prevent users from deleting series set the permanent to true" :

var myseries = stxx.addSeries("SNE", {display:"Sony",data:{useDefaultQuoteFeed:true},width:4,color:"purple",permanent:true}); 

Sometimes it is desirable to display a series either on the top half, bottom half or centered on the screen. Positioning can be controlled using the marginTop and marginBottom parameters. Setting these to a whole number will control the margin or padding between the top or bottom of the series and the top or bottom of the chart. If you set these values to a number between 0 and 1 then the parameter will be interpreted as a percentage and automatically adjust to the size of the chart.

If you want to treat the series as a comparison to the main symbol, set the isComparison parameter to true (only available in Advanced package).

stxx.addSeries("GE",{color:"red", data:yourDataArrayHere, isComparison:true});

This turns on the comparison mode and displays the appropriate adjusted y-axis values determined by the STXChart#setTransform function. For comparisons, the y-axis will be 'transformed' from price mode to percentage mode.


The following sections are only applicable for implementations using the legacy STX.Comparison


Using the built in comparison interface

The advanced package of library includes a template with all of the infrastructure you will need to automatically add and remove comparisons to your chart as well as managing the UI to properly display them. You can find it in 'stx-advanced.html'

All you have to do is call the following method from your newChart callback function, and the new series will appear on your chart for the 'compareSymbol' of your choice.

STX.Comparison.add(chartObject, compareSymbol, callbackFunction,)

Example:

    stxx.newChart("IBM", null,null, function(){
        STX.Comparison.add(stxx, "SPY");    /// you can add multiple comparisons
        STX.Comparison.add(stxx, "DJI");
}

The library supports multiple comparison types:

  • compare - The UI defaults to "compare" which produces a y-axis with relative percentage changes.
  • overlay - Overlays the series so that the axis is not shared and instead just the 'shape' is maintained.
  • absolute - It renders each series on the exact y-axis values. This is not recommended for series that do not share a similar y-axis price range.

To set or reset the comparison type, assign the desired type to STX.Comparison.type.

Example:

    STX.Comparison.addComparison=function(){
      STX.Comparison.type="absolute"; // Shares the same scale between multiple series of data
      STXLoader(true);
      STX.Comparison.add(stxx, null, function(){
        STXLoader(false);
      });
    }

You would set these up before calling comparison function so it renders in the selected type. But, it can also be changed after comparisons have been rendered if desired. A button can be added to the UI to control the type, allowing users to dynamically change the comparison types at any time.

See STX.Comparison.type for more details.

Note: This method is driven from the UI but can also be called programatically only if the sample comparison UI HTML included in the advanced package is available in the page. If you are not using the sample stx-advanced.html sample template, you will need to override this method to exclude references to the UI HTML elements or use STXChart#addSeries and add your code to manage the data feed.

Manipulating the series style for the comparison.

STX.Comparison.add() calls addSeries(). So anything addSeries can take as a parameter, you can pass it in. See STXChart#addSeries and STX.Comparison.add

Example for using mountain charts with a gradient color for comparisons:

STX.Comparison.addComparison=function(){
  // Alternative comparison types. Set these using your UI if you want to support them
  //STX.Comparison.type="absolute"; // Shares the same scale between multiple series of data
  //STX.Comparison.type="overlay"; // Overlays a series of data

STXLoader(true); STX.Comparison.add(stxx, null, function(){ STXLoader(false); },null,{chartType:'mountain',fillStyle:'color'}); // For semi-opaque use rgba(R,G,B,.1) <<====== }

Modifying the default series renderer for comparisons (rendering to include a left y-axis)

If you want your comparisons to display a y-axis on the left with their corresponding values, for example, or have any other series customizations; you can create a custom series renderer instead of using the default.

To do this you must understand how the STXChart#addSeries method works, especially the fact that if a color is included in the parameters, the default renderer will be used.

To override this behavior and for the series to you your renderer, you must first delete the color parameter, and the series, and then replace it. Once this is done, you move on to customizing your renderer as needed.

Here is the code sample, which you would assing to the STX.Comparison.fetch function:

        STX.Comparison.fetch=function(stx, comparisonSymbol, parameters, cb){
            // if not using a quoteFeed, fetch comparison data here and set the parameters.data for the series as follows:
            // parameters.data= { your data array here };
            if(!parameters.data) parameters.data={useDefaultQuoteFeed:true};
            //
            // code to add the series without the color to prevent it from using the default renderer.
            var color = parameters.color;
            delete parameters.color;
            stx.addSeries(comparisonSymbol, parameters, cb);
            parameters.color=color;
            //
            // define your y axis
            var axis=new STXChart.YAxis();
            axis.position="left";
// // create your custom renderer and attach it to the series var r=stx.getSeriesRenderer("_custom_series"); if(!r){ r=stx.setSeriesRenderer(new STX.Renderer.Lines({ params:{type:"legacy", name:"_custom_series", overChart:true,yAxis:axis}, })); } r.attachSeries(comparisonSymbol,parameters).ready(); };