X-13-Graph Java is designed to create graphs from X-13ARIMA-SEATS output files.
Updates in Version 3.0 include two new graph types (differenced original series graphs and sliding span comparison graphs), additional special seasonal graphs (irregular by month, original series by month, and month-to-month changes by month), additional SI ratio comparison graphs, new titles for some graphs to match the graphs of the batch version of the program, and various bug fixes.
X-13-Graph requires Java Version 8.0 or higher to run. It creates graphs from graphics files created using X-13ARIMA-SEATS or X-12-ARIMA Version 0.3; it is not compatible with earlier versions of X-12-ARIMA.
To start the program, double click on X13GraphJava.jar. If your computer cannot open executable jar files directly, then at the command prompt, enter
java -jar fullpath /x13graphjava.jar
Persons with visual difficulties who have trouble using this application should contact us for assistance.
Before you can create any graphs with X-13-Graph, you must run the series with X-13ARIMA-SEATS in graphics mode; see the X-13ARIMA-SEATS Reference Manual (U.S. Census Bureau, 2020) for details. When a series is run in graphics mode, files containing series components, adjustment information, and diagnostics are saved to the graphics directory, along with a .udg file containing diagnostic information and a .gmt file listing the graphics files which were saved.
To choose series to graph, press the Add Series button, and navigate to the directory containing the graphics files. A list of the .gmt files will appear. Select the series to be graphed; use the Ctrl key to select multiple series. Pressing Open will add the selected series to the list box directly below the Add Series button.
Highlight the series to be graphed. To create graphs comparing two series, use the Ctrl key to select two series. Note that the two series will be graphed in the order they were selected.
Selecting a series from the series list box will populate the drop-down box with all the types of graphs available for this series. When you select a graph type, all the graph elements of that type are added to the list box directly below the drop-down box. Select an element and press Graph to create the graph.
For most graph types, only one graph element can be selected at one time. However, for Overlay and Factor graphs, up to three elements can be plotted on one graph. Use the Ctrl key to select more than one element. They will be plotted in the order they were chosen.
If you select Overlay Graphs to Compare Two Models from the drop down box, two list boxes will appear below the drop-down box. Use the first to select up to three elements from the first series, and the second to select up to three elements from the second series. Similarly, if you select Seasonal Factor Overlay Graphs two list boxes will be shown; you can select an element from the first box for the first series and an element from the bottom box for the second series.
Once created, a graph is displayed in the panel to the top right, and a table of the graph's values is shown in the panel directly below it. You can display the previous graph by pressing the << button and the next graph with the >> button. Alternately, you can select the graph and table to view by selecting it from the drop-down box above the graph. This box contains the list of all graphs created; it gives the name of the series and the graph title.
For some graph elements, pressing the Graph button produces more than one graph. The graph created last will be displayed; use the << button to view the other graphs created.
You can view two graphs at once by choosing View Two Graphs from the Options menu. Then the table in the bottom panel will be replaced with another graph, with its own forward and backward navigation buttons and drop-down list of graphs.
Note that you cannot view the same graph in the top and bottom panels simultaneously. If the top panel is showing the second graph on the list and the bottom panel is displaying the first, then pressing the >> button will result in the bottom panel displaying the third graph.
When viewing two graphs at once, you can switch to the table view for the panel by pressing the Table button. The graph will be replaced by the table, and the button will change its text to Graph; press this button again to return to the graph view.
When a new graph is created while in View Two Graphs mode, the top panel will immediately display this graph. If the top panel is in table view, then the graph's table will appear.
Graphs can be saved to disk as PNG files, and tables saved as HTML files.
To save a graph, right click on the graph and choose Save As. Alternately, select Save Graph from the File menu; this will save the graph currently displayed in the top panel. In either case, choose the location and file name for the PNG file in the Save dialog box which appears.
Multiple graphs can be saved at once by choosing Save All Graphs from the File menu. In the window that appears, use the folder browser to select the directory to which to save the graphs.
A table of all graphs available is below the folder browser. The first column is composed of check boxes, and the second gives the series name and graph title, as they appear in the drop-down box listing the graphs.
By default, all graphs are checked; uncheck the box in the first column if you do not want that graph to be saved. The file name of the PNG file to be created is given in the third column.
By default, the file name is composed of the series name and a number in parentheses. You can edit the file names before saving the graphs. (The program captures the new value when you move to another cell in the table; if you change the value of "SeriesName (1).png" to "Original Series (SeriesName).png" and press the Save button without first clicking on another cell in the table, the graph will be saved as "SeriesName (1).png".)
The size of the saved graph will be that of the last view of the graph.
Individual tables can be saved by selecting Save Table as HTML from the File menu. This will save the table of the graph currently displayed in the top panel.
Choose Save All Tables as HTML from the File menu to save multiple tables at once; the window used to save the tables works just as that to save all graphs.
To change the graph and table settings, select the type of option you want to change from the Options menu. The options available for that setting will be shown in the panel to the bottom left.
You can choose whether each of the graph and table options is applied to the graph currently visible only, to all graphs created, to graphs made in the future, or to any combination of these three.
To set how the options are applied, select Applying Option Changes from the Optionsmenu.
In the window that appears, check the Visible graphs box in the option group to indicate that changes to the option should be applied to the graph in the top right panel.
Checking the All existing graphs box applies the option to all graphs that the program has produced thus far, and checking the All future graphs box applies the option to graphs created after the option has been changed.
By default, titles and subspans are applied only to the visible graph, while all other options are applied to all existing and future graphs.
When you select Restore Default Settings from the Options menu, the application of options reverts to this default.
If an option cannot be changed for a particular graph, the request is simply ignored. There is no error message indicating that the option could not be set.
Select Colors & Lines from the Options menu to change line color, line stroke, line width, and background colors.
The panel that appears in the bottom left shows a figure displaying the current settings, a drop-down box listing the elements that can be changed, a Color button, and a Stroke button.
To change the color of an element, select it from the drop-down box and press Color. A Color dialog box with three tab pages will appear.
Use the Swatches tab to select one of the colors displayed, the HSB tab to select a color by changing the hue, saturation, and brightness, or the RGBtab to choose a color by supplying the color's red, green, and blue make-up.
When you press Okay, the selected color is applied to the element in all graphs selected in the Colors & Lines group of the Applying Options window.
To change the stroke and width of the lines, select the line and press Stroke. In the Choose stroke drop-down box, select the pattern to be applied to the line. Your options are
Choose between narrow, normal, and wide lines in the Choose width drop- down box. The selected options can be previewed in the Preview box. Press Okay to apply the line change.
For most graphs, lines one through six represent the line that will be used to graph elements one through six, respectively. There are some exceptions, however.
The plot background is the area on which the graph itself appears; the chart background is the larger panel on which the titles and the plot are placed.
By default, the main title of the graph names the element being graphed. The subtitle uses the title of the series, as given in the series spec when the series was run in X-13ARIMA-SEATS.
If you did not supply a title, the name of the series output files is used.
To change the title and subtitle of the graph, select Graph titles from the Options menu. Two tab pages appear in the bottom left panel. Use the Main Title tab to choose whether to use the graph type or the series title as the main title, to use another option, which you can specify in the text box on this page, or whether to remove all titles.
On the Subtitle page, you can similarly specify whether to use the graph type, the series title, or an alternate option as the subtitle, or to remove the subtitle.
Make your selections for both the title and the subtitle, and press Apply.
When you select Graph Fonts from the Options menu, four buttons appear in the bottom left panel.
Use the Change Font (all text) button to change the font family for all titles and labels. (Text inside the plot itself is not changed.) You can also change the font family, font size, or font style of a single text element. Change Title Font applies font changes only to the main title, while Change Subtitle Font does the same only to the subtitle. Change Label Font changes the font of the x- and y- axis labels and tick mark labels, as well as the text in any footnotes.
Select Subspans from the Options menu to change the span of data being displayed in the graph. The subspan option applies only to graphs displaying time series (in some configuration), not to spectrum graphs or ACF graphs. It also does not apply to First Difference Graphs or to History Graphs to Compare Two Models.
To change the span of data, select the year and month or quarter for the beginning and end of the required span from the four spin boxes, and press Apply. To change only the beginning date, keep the End Year spin box set to "Series End"; to change only the end date, keep the Start Year spin box set to "Series Start." Alternately, use a date after the end date of the series, or before the start date, respectively.
Press Reset to request the graph show all available data.
To show an overlay graph or a year-on-year graph on the log scale, select Y-Axis Options from the Options menu, and check the View logs box. If all data values are above zero, then the graph will be shown on the log scale. If the series' spec file supplied a "constant" argument in the transform spec, then this constant will be added to the data value before attempting to take the log; the fact that a constant was added will be indicated in the footnote of the graph.
You can scale the y-axis by selecting Y-Axis Options from the Options menu, and choosing the number by which to divide the y-axis values from the drop-down box.
Available values are powers of ten between one thousand and one trillion. When a value is selected, all values in the graph are divided by this number, and a label giving the scale appears alone the y-axis. Values in the table are also divided by this number.
If the graph is on the log scale, the y-axis will not be scaled. ACF, spectrum, outlier t-value, first difference, and some factor graphs are also not scaled, as their y values are generally small.
To select a specific range for the y-axis, choose Y-Axis Options from the Options menu. Type the minimum y-value into the Y-Min box and the maximum y-value into the Y-Max box, and press Apply Range.
Some graphs do not have this option enabled.
You can add gridlines at a specific period to highlight the values of a particular month or quarter.
To do this, select More Options from the Options menu, and select the period from the drop-down box.
The line and line stroke used to draw the line can be changed; see Colors & Lines for details.
By default, the program includes horizontal and vertical gridlines along each tick mark. You can turn off these gridlines by selecting More Options from the Options menu and un-checking the Show vertical gridlines and Show horizontal gridlines boxes.
When the cursor hovers over a point in the graph, a pop-up box will appear giving the x- and y- value of the point, and, in some cases, the graph element the point represents. These item labels can be turned off by selecting More Options from the Options menu and un-checking the Show item value as tooltip box.
You can change the format of the numbers in the table by selecting Number Format from the Options menu.
In the panel which appears in the bottom left, choose 1,234,567.89 or 1234567.89 to show the numbers in general format, with or without commas, or 1.23456789E6 to show the number in scientific notation.
From the spin-box, you can choose how many decimal places to show; "Default" shows all available decimal places.
If the number has fewer decimal places than you select from this box, you can check the Pad decimal places with zeroes box to fill out the extra decimal places with zeroes.
To change the size of the graph, you can manually resize the program window using the mouse or the maximize button.
You can alternately set the exact pixel height and width by selecting Size Graphs from the File menu.
Controls for selecting the height and width in pixels will appear in the options panel in the bottom left.
Select the appropriate sizes and click Resize.
With overlay graphs you can view the series and its adjustments - the seasonally adjusted series, the trend, the outlier adjusted series, etc.
You can select up to three graph elements to plot above a single axis.
The order in which the elements are selected determines the order of the names in the title and legend. It also determines the color and line of each element.
To view logs of the series, check the "View Logs" box in the "Y-Axis Scale" option box.
Use factor graphs to view the factors used to adjust the series.
You can choose up to three factors to view at once. Each factor will appear in its own plot, with the same y-axis scale for easy comparisons.
If you requested that backcasts and forecasts be appended to the graphics file when you ran X-13ARIMA-SEATS, they will appear on these graphs as dotted lines.
Spectrum graphs are used to identify seasonal and trading day effects in the series. Vertical lines identify the amplitudes at seasonal and trading day frequencies.
Cleveland and Devlin (1980) identified the trading day frequencies of this graph as the frequencies most likely to have spectral peaks if a flow series has a trading day component.
The lines used to identify seasonal frequencies are drawn using the color and stroke of Line 3, while the trading day frequencies use Line 4. An "S" at a seasonal frequency or a "T" at a trading day frequency indicates that the frequency is visually significant.
Graphs of the autocorrelation function and the partial autocorrelation function are available for both the residuals and for the original series.
If X-13ARIMA-SEATS estimated a regARIMA model for the series, you can create ACF and PACF plots of the residuals or an ACF plot of the squared residuals.
If you included the identify spec, you can create ACF and PACF plots from the original series. The program will create an ACF and a PACF graph for each combination of differencing and seasonal differencing that was given in the identify spec.
You can create graphs to view many series components by period. These include graphs of the seasonal factors (D10 table), the combined factors (D16 table, includes adjustments for trading day and moving holidays), or the original series by month or quarter. Each of these graphs includes a line representing the monthly mean.
The irregular component can be graphed as box plots to show the spread or as a needle graph centered around the period's mean.
Graphs of the SI ratios (the detrended series values), superimposed with the replaced SI ratios for extreme points, the seasonal factors, and the period's mean of the seasonal factors, are available either with all months/quarters on one graph, as pictured above, or with each month or quarter graphed individually. The SI graphs are due to Cleveland and Terpenning (1982).
The program graphs the original series, the forecasts, and the confidence intervals for the forecasts. If you chose a transformation in the X-13ARIMA-SEATS run, you can graph the series and forecasts on the transformed scale. Confidence intervals for graphs on the original scale are at the level chosen with the probability argument in the forecast spec when X-13ARIMA-SEATS was run. Graphs on the transformed scale always use 95% probability intervals.
You can create graphs to study the revisions for the seasonal adjustment, seasonal factors, trend, and forecasts of a series.
To create these graphs, you must have run X-13ARIMA-SEATS with the appropriate option in the estimates statement of the history spec. Including the line estimates=(sadj sadjchng trend trendchng seasonal aic fcst) in the history spec will allow all history graphs to be created. See the X-13ARIMA-SEATS documentation for a full description of these options.
You can create the following four types of history graphs:
If you request a graph of the "Seasonal Adjustment Values", "Indirect Seasonal Adjustment Values", or "Trend Values," you will get two graphs. The first is a graph of the initial and the final estimates of that value overlaid with the original series. The second includes estimates from any other lags from which you requested history information when running X-13ARIMA-SEATS.
Percent Change Graphs
Three graphs are created when "Percent Changes in the Seasonal Adjustment Values" or "Percent Changes in the Trend Values" are requested. Each graph plots two of the following for each observation: the percent change (from the previous observation) of the final estimate, the percent change of the initial estimate, and the percent change of the original series. Each is plotted as a circle or square, with a vertical line connecting them.
Special Trend Graphs
If you request graphs for "All Trend Revisions" or "Trend Revisions for the Ending Date" the program produces graphs that connect the estimates for trend from the lags requested (via the trendlags argument) when X-13ARIMA-SEATS was run. This shows the direction a trend was taking for a particular date. Each graph has a continuous line representing the final trend estimate. There is a shorter line connecting all the estimates for a particular date from the requested lags. That is, if lags 1, 2, 3, and 4 were requested, then for December 1999, the initial trend estimate is connected to the Lag 1 estimate from November, the Lag 2 estimate from October, the Lag 3 estimate from September, and the Lag 4 estimate from August to see where the trend was heading.
The graph "for the ending date" shows the trend lags only for the last date on the graph, and the graph for "all trend revisions" shows the trend lags for all dates.
Concurrent Forecasts and Forecast Errors
Graphs for "Concurrent Forecasts" plot the original series and the within-sample forecasts for the lags specified in the history spec. Graphs for "Concurrent Forecast Errors" plot the difference between the original series and the within-sample forecasts for the specified lags.
Outlier T-Value Graphs allow you to compare the maximum absolute t-values from the automatic outlier procedure.
We've been using the graphs for research into ways for finding regARIMA outliers, with only limited success. For more information on our research, please see McDonald-Johnson and Hood (2001).
Information for the Outlier T-Value graphs comes from the automatic outlier procedure from the final t-value table. By default, X-13ARIMA-SEATS only looks for AO and LS outliers, but you can also request that it search for temporary change outliers in the outlier spec.
The t-value graphs will plot the maximum absolute t values for each data point. That is, if for one particular month, say June 1989, X-13ARIMA-SEATS calculates an AO t-value of 3.1, an LS t value of 2.2, and a TC t value of 2.7, at June 1989 the graph shows only the AO t-value at 3.1. Another helpful feature of the maximum absolute t-value plot is that X-13ARIMA-SEATS assigns a t-value of 0 to any identified outlier. That is, if X-13ARIMA-SEATS identifies a particular month, say August 1998, as an LS, then the August 1998 LS t-value would be 0, although X-13ARIMA-SEATS would calculate valid t-values for the AO and TC effects. The greater (in absolute value) of the AO and TC t-values would appear on the graph.
If you select "Maximum Outlier T-Values" the actual value of the maximum absolute t-value will be plotted, with the correct sign. If you select "Maximum Absolute Outlier T-Values" then the absolute value of the maximum absolute t-value will be plotted.
The program graphs the first differences of the selected element by period.
The form of the first difference graphs was developed by Stuart Scott at the Bureau of Labor Statistics, where it has been used to detect outliers in the original time series. See Scott (1987) and Buszuwski and Scott (1988) for examples of using first difference graphs to identify different types of outliers.
Graphs of the original or log transformed original series can be graphed after applying various orders of nonseasonal and seasonal differencing.
The graph is centered around the mean of the selected subspan. When a subspan is selected, the differencing is applied to the data in that span, so the graph shown will start d+D*s periods after the subspan start date, where d is the order of nonseasonal differencing, D the order of seasonal differencing, and s the seasonal period.
Year on Year graphs plot the requested element by year in order to look for seasonal patterns in the data.
There are two options for the line colors. In the graph above, the first six years use the six line colors and the line stroke of line one; the next six years re-use the six line colors but use the line stroke of line two; and so on. Alternately, the graph can use the color of line one but start with a light shade for the first year and darken for every successive year. Additionally, the width of the line increases slightly for each year. An example of this color scheme follows.
Four types of sliding spans graphs can be created, each for the seasonal factors or seasonal adjustment and for the period-to-period changes in the seasonal adjustment. The first is an overlay graph of the seasonal factors or period-to-period changes of each of the spans, along with indicators of the maximum and minimum value for those points where the maximum percent difference is greater than the cut-off (usually 3). The maximum percent differences themselves can be graphed along with a horizontal line indicating where the cut-off is. The maximum percent differences can also be graphed by month/quarter or by year.
To create these SEATS graphs, the series must be run in X-13ARIMA-SEATS with the option finite=yes in the seats spec. In X-13-Graph Java, SEATS graphs can be found under four graph types.
SEATS Diagnostic Graphs include the fully differenced SEATS seasonally adjusted series and trend and a plot of the seasonal period length sums of the SEATS seasonal factors.
Under SEATS Filter Graphs you can create graphs of the concurrent and symmetric seasonal adjustment and trend filters used to adjust the series. The squared gain of these four filters can be found under SEATS Squared Gain Graphs, and the time shift of the concurrent filters can be found under SEATS Time Shift Graphs.
Overlay graphs of two series can be produced to compare the adjustments. Up to three elements can be chosen for each series. Use the top list box to select elements for the first series and the bottom list box to select elements for the second series.
When you request a factor graph to compare two series, the program creates up to two graphs: the plots of the factor for each series on one graph, and, if the adjustment mode and period are the same for the two series, either the difference or the ratio between the values of the factor for each series. The ratio is graphed when the adjustment is multiplicative, and the difference when the adjustment is additive.
The spectrum graphs of two models can be overlaid for comparison. Significant seasonal peaks are marked with an "S" and significant trading day peaks with a "T", with the color of the letter matching the color of the graph(s) which is significant.
History graphs allow you to compare two models by looking at differences in the AICC over time or differences of the cumulative squared forecast error. To create these graphs, X-13ARIMA-SEATS must be run with the option aic or fcst, respectively, in the estimates statement of the history spec. For the Sum of Squared Forecast Error Differences graph, the program superimposes all available forecast lags on a single graph.
These history graphs are discussed in Findley, Monsell, Bell, Otto and Chen (1998) and are related to diagnostics presented in Findley (1990, 1991).
If you request a graph of the "Percent Difference of the Seasonally Adjusted Series," two graphs are created. One shows the month-to-month percent change of concurrent seasonal adjustment value for both models, joined together by a line to highlight how large the change is. The second graph does the same thing for the month-to-month change in the final seasonal adjustment values. These graphs can also be created for the percent difference of the trend. In order to create these graphs, you must run X-13ARIMA-SEATS with the options sadjchng and trendchng in the estimates statement of the history spec.
Use RSI comparison graphs to see the differences in the SI ratios and their replacement values for two models. You can create a graph of the original SI ratios, the SI ratios with replaced values, or the replaced SI ratios with the original SI ratio. These plots are also available by period.
You can compare the forecasts of two models by creating a forecast comparison graph. This graph shows the original series and its forecast for both models.
These graphs overlay the seasonal factors by month plots for two adjustments. Select the seasonal factor type to graph for the first series from the top list box, and for the second series from the bottom list box.
For each time point for which there were at least two sliding spans created, sliding spans comparisons graphs plot a square for the maximum percent difference of the spans for series one; a dot for the maximum percent difference of the spans for series two; and a line connecting them.
These graphs can be created to compare the seasonal factors, seasonally adjusted series, or the period-to-period change in the seasonally adjusted series.
Please report all problems or provide any feedback to Demetra Lytras either by email (firstname.lastname@example.org) or telephone at (301) 763-7426.
This program is a translation into Java of a SAS program written by Catherine C. Harvill Hood, with help from Brian Monsell, Kellie C. Wills, and Kathy McDonald-Johnson.
Thanks to Chris Blakely, who provided some Java code upon which the graphs are based, and to Nikki Czaplicki, who contributed to the programming.
This program uses the JFreeChart and JCommon libraries, (C)opyright 2000-2020 by Object Refinery Limited and Contributors.
The libraries are covered by the Lesser General Public License.
Buszuwski, J.S. and S. Scott (1988), "On the Use of Intervention Analysis in Seasonal Adjustment," Proceedings of the Business and Economic Statistics Section, American Statistical Association, Alexandria, VA, 337-342.
Cleveland, W.S. and I. Terpenning (1982), "Graphical Methods for Seasonal Adjustment," Journal of the American Statistical Association, 77, 52-72.
Findley, D.F. (1990), "Making Difficult Model Comparisons Graphically," Proceedings of the Section on Survey Research Methods, American Statistical Association, Alexandria, VA.
Findley, D.F. (1991), "Model Selection for Multi-Step-Ahead Forecasting," Proceedings of the Business and Economic Statistics Section, American Statistical Association, Alexandria, VA.
Findley, D.F., B.C. Monsell, W.R. Bell, M.C. Otto and B.-C. Chen (1998), "New Capabilities and Methods of the X-13ARIMA-SEATS Seasonal Adjustment Program," Journal of Business and Economic Statistics, 16, 127-177 (with discussion).
Hood, C.C. (2001), "User's Guide for X-13-Graph Interactive for PC/Windows, Version 1.2," U.S. Census Bureau, U.S. Department of Commerce.
McDonald-Johnson, K. and C.C. Hood (2001), "Outlier Selection for RegARIMA Models," Proceedings of the Business and Economic Statistics Section, American Statistical Association, Alexandria, VA.
Scott, S. (1987), "On the Impact of Outliers on Seasonal Adjustment," Proceedings of the Business and Economic Statistics Section, American Statistical Association, Alexandria, VA, 469-474.
U.S. Census Bureau (2020), X-13ARIMA-SEATS Reference Manual, Washington, DC.