File Exchange

image thumbnail

X-13 Toolbox for Seasonal Filtering

version 1.33 (2.8 MB) by Yvan Lengwiler
Matlab toolbox providing access to X-13 seasonal adjustment programs of the US Census Bureau.

52 Downloads

Updated 05 Oct 2018

View License

The X-13 Toolbox for Matlab is a shell for interacting with the programs of the US Census Bureau, known as X-13ARIMA-SEATS, that perform seasonal filtering. The X-13 programs are the "industry standard" and are widely used by many statistical agencies and researchers. The toolbox ought therefore to be useful for statisticians or economists who use Matlab, and who lacked access to the standard seasonal adjustment method until now.

The toolbox contains a graphical user interface, called guix, that allows you to perform X-13 computations interactively. This can be useful for novice as well as expert users and is probably to best way to learn about the possibilities of X13.

The toolbox contains a documentation in a PDF as well as demo files that should help you understand how to use the toolbox. The X-13 program has a plethora of specifications one can fiddle around with. The best source to learn this is the original US Census Bureau documentation. Their website also has working papers devoted to this topic (see https://www.census.gov/srd/www/x13as/).

The toolbox supports the X-13ARIMA-SEATS and the X-12-ARIMA programs of the US Census Bureau. The older X-11 program is not supported, though. A simplified version of X-11 is implemented in Matlab as part of this toolbox. In addition, the toolbox contains some other programs that are independent of the Census programs. These programs (x11, fixedseas, seas, camplet) can be used with arbitrary frequencies, nit just monthly or quarterly data like the Census programs.

Note: To get the complete functionality the toolbox requires freely available executables from the US Census Bureau in order to run. It attempts to download these executables automatically for you whenever you need one that is not on your harddrive. Of course, that works only if you are online, and it is limited to Windows computers. Versions of these programs for other operating systems are available from the Census website, however, and can easily be installed manually.

Please comment below if you find this software useful.

Comments and Ratings (54)

Christopher,

Maybe one comment: CAMPLET is designed so that there are no revisions when the time series is extended with new data. This feature can be useful. It achieves this by using only backward looking filters, so there are no centralized or symmetric moving averages or kernels. As a result, the CAMPLET decomposition will feature an undesirable phase shift. This is, I believe unavoidable. But the flipside is that there are no revisions when new data come in.

Cheers, Yvan

Christopher,

I was struggling with that for a while, and I think I am not able to explain it with more authorrity than the inventors. I suggest you study the original article:

Barend Abeln and Jan P.A.M. Jacobs, "Seasonal adjustment with and without revisions: A comparison of X-13ARIMA-SEATS and CAMPLET," CAMA Working Paper 25/2015, Australian National University, July 2015.

Cheers, Yvan

Yvan, I don't really get how the Camplet program adjusts the series without any pretreatment. Can you explain the algorithm in a few words?

Thank you for your time!

Greetings,
Christopher

yvan becard

Thanks for your invaluable help Yvan, problem solved.

Yvan,
This problem is odd, and I cannot imagine that it has something to do with you changing Matlab versions. The code that determines the frequency of the data does not use version specific code.
You could, in principle, set the frequency manually by adding 'series','period',12 into the spec (for monthly data), or 'series','period',4 for quarterly data, respectively.
In oder to help you more I would need to see the data you use, in particular the dates vector you use. Could you send me this by email? I would be glad to analyze it.
Yours, Yvan

yvan becard

Hi, thanks for the nice toolbox. It was working perfectly well, until I changed my computer, I now have Matlab R2018a, and I get this error message:

Error using x13series/PrepareFiles (line 2183)
Automatic frequency detection failed. Please specify
the correct frequency of the data manually with
x13spec('series','period',value).

Do you how I solve this?

Dear Yunzhi,

I've added more complete error messages for the case when the download fails. The extended error messages instruct the user which URLs to use to download the files manually, and then what to do with them.

It will be part of the next update of the toolbox (probably when the next version of x13as is published by the Census Bureau).

Sincerely,
Yvan

Benlaron LU

Hi Yvan,

Thanks for your outstanding toolbox. However, some guys like me may fail to download x13as from Census Bureau directly by entering InstallMissingCensusProgram.m in command window. So, an instruction for manual installment would help a lot.

However, given that the organization of your code is pretty good, I follow your website list in InstallMissingCensusProgram.m and download files listed there via VPN manually. I also double check your Readme.txt in the "\exe" folder.

Anyway, I do appreciate your contribution.

Cheers,
Yunzhi

Duc Huy,
Maybe. How much of a beginner are you? Do you know some Matlab but are a beginner in seasonal adjustment? Or are you also a beginner in Matlab?
Yours, Yvan

Tran Huy

Hello,
Can you help me step by step because I am a beginner?
Thank you in advance!
Best,
Tran, Duc Huy

Yvan,

Thanks a lot! :)
Best,
Yannis

Yannis,

I believe your syntax is wrong. The first argument should be a column vector containing dates, the second argument should be an equally long column vector containing the data. Alternatively, you can also use a T x 2 array with the left column containing the dates and the right column containing the data. The next argument must be a x13spec object, which contains the specification passed on to the X-13 procedure. If you do not provide a specification, a default can be used. The default specification can also be had by saying makespec(). Any arguments after that are optional. You set 'x-13'. I suppose you want to force x-13 instead of x-12. But x-13 is the default anyway, so this argument is not required.

So, assuming that gdp' is a T x 2 array, consider this

x = x13(gdp')

or alternatively

x = x13(gdp',makespec())

or yet more specific

x = x13(gdp',makespec(),'x-13')

All three variants should produce the same outcome.

Hi,
I tried to run the toolbox by using the following code:

x = x13(gdp','x-13');

And got this error:

Undefined function or variable 'compositeSpec'.

Error in x13 (line 745)
x.specgiven = [spec,{compositeSpec}];

Could anyone helps me with that?
Thank you in advance!
Best,
Yannis

Fabian, It's not completely clear. Maybe you have missing values at the send of your data? I cannot say without seeing your date and HICP-ExEnergy data. You seem to have quarterly data, is that correct? What is surprising is that the last year of your data appears to be the year 117. Is this intended?

It might also have something to do with the fact that date has a meaning in Matlab. Maybe you could try using a different variable name for the vector containing the dates.

Hi, I tried to run the program with:

Test = x13([date,HICP_ExEnergy])

But I get the Error:

Warning:
ERROR: Model span not within the span of available data.
ERROR: model span end date, 117.2, must end on or before
span end date, 117.1.

Not sure, how to read this. Is it in obvious mistake anyone can help me with?
Thanks!
Fabian

Stephen,
Sure, I can try to help you. But I do not have access to a Mac, so my possibilities are limited.
The first step, I guess, is to download the source from here: https://www.census.gov/ts/x13as/unix/x13assrc_V1.1_B39.tar.gz

Hi Yvan - I experienced same problem as Christian trying to get this to run on a Mac. I noticed you had said you might be able to run using source code, but he opted out. Would you be willing to help me take this route?

Christian

Christian,

Do you use quarterly data? In that case, remove the 'SPECTRUM' from the specification, because spectra are only computed with monthly data. This will get rid of some of the errors, but not all of them.

Missing variable s11, s12, s13, s16 actually means that the seasonal adjustment is, for some reason, not performed. This can have several reasons, I could try to walk you through it. But honestly, I think it's easier if you could just send me the offending series (yvan.lengwiler-at-unibas.ch) and I'll take a look at it.

Christian

Yvan,

thanks for your replies. I made some progress: I found out that some series produce s.a. output if I remove leading NaNs. Still, even without any NaNs, no s.a. output is produced in some cases. That is quite mysterious. I've got the following error message: "MISSING VARIABLES: ''s1s'', ''s2s'', ''ser'', ''sp0'', ''spr'', ''st0'', ''str'', ''t1s'', ''t2s'', ''ter'', ''s10'', ''s11'', ''s12'', ''s13'', ''s16'', ''ao'', and ''td'' were requested but are not available.'"...

Christian,

By the way: the seasonally adjusted series is in d11 only if you use X-11. If you use SEATS, the corresponding variable is called s11.

Actually, maybe you want to check out the GUI I made for this toolbox. Just run guix from the Matlab prombt, enter the names of your variables containing the dates and the data, and then you can clic trough all options and run the adjustment in the GUI. That should help you find a working specification.

Cheers, Yvan

Christian,

The Census bureau program has the TRAMO-SEATS algorithm built in, so you should be able to use that as well.

I don't know what the default parameters of the Banco d'Espagna are, but you could try the following:

spec = makespec('TD', 'EASTER', 'AO', 'LS', 'AUTO', 'TRAMO', 'SEATS', 'ACF', 'SPECTRUM');
x = x13(dates,data,spec);

This will use TRAMO to identify the times series model and SEATS to do the seasonal adjustment. It will also automatically identify additive outliers (AO) and level shifts (LS), use dummies for trading days (TD) and the location of Easter in the year, and will choose an additive or multiplicative model automatically (AUTO).

Please let me know if that works for you.

Yvan

Christian

Yvan,
Sorry for having been absent for a while. In the meantime, I have found a windows machine. So that might be the easier solution.

I have to admit that the program is somewhat of a black box to me. I previously used TRAMO-SEATS from the Bank of Spain. I just used their default setting and the program was reasonably fast.
When I re-run the code with your program (I basically used your demo code for the GDP example, but used some CPI data), I face 2 problems:
1. The code is somewhat slow.
2. For some countries, I do not find any d11 series, even though the input series of data cover >10 years of quarterly data.

I'm less concerned about the first problem, but I'd like to fix the second problem. In particular, I wonder whether there is a robust default option that gives me a reasonable seasonal adjustment, maybe similar to the TRAMO-SEATS program offered by the Bank of Spain.

Thanks!

Christian,

Actually, I just saw that the source of the x13as program is available from the Census website. So, if you feel confident to recompile it on the Mac, we could make it run :-)

Yvan

Christian,

Actually, it seems that Linux programs do not run on a Mac unless you have access to the source code (which isn't public in this case) and can recompile. Alternatively, you can use a Linux virtual machine on your Mac, but that would require to run Matlab also in this VM, so ...

See for instance here, https://unix.stackexchange.com/questions/212754/is-there-a-way-to-run-a-linux-binary-on-os-x

If all of that is true, it probably means that you cannot use the Census programs on a Mac. You can still use the fixedseas and camplet methods of the toolbox, because they do not rely on the Census programs, but of course, the quality of seasonal filtering is not comparable to what the genuine X-13ARIMA-SEATS provides.

Christian,

Your're the first user I know of who uses this toolbox on anything but a Windows computer.

The Census Bureau offers their X13 programs in a DOS, ind a Windows, and in a Linux version. This Matlab toolbox uses the DOS versions by default. I don't know if the Linux version runs on the Mac (given that the MacOS is, I believe, closely related to Unix). If the Linus version does run, we might be able to fix the toolbox so that it will work on a Mac :-)

In any case, the x12diag03.exe is an addition to the main x13as.exe that is not really important. This program is also available from the Census website, but if that doesn't work that is almost inconsequential. Just comment out that portion in the X13DemoGDP file.

The only crucial part is to know if the Linux version of the Census program works on the Mac. I cannot test that because I do not have access to a Mac. Maybe you can test that? You can download the Linux versions from here: https://www.census.gov/srd/www/x13as/x13down_unix.html If you've downloaded the DOS versions, just delete them. They will be of no use on your computer. After placing the Linux version of x13as (and possibly of x12diag03 as well), you could try again and tell me if it works. I expect some iterations of this before it might finally work...

Let me know how it goes,
Yvan

Christian

Thanks for your reply, Yvan. I've got the directory structure the way you say it should be. I think one problem was / is that macs like to use slashes instead of backslashes. Your program doesn't find x13tbx\exe\ because it's x13tbx/exe/ on a mac. That's why it creates a folder with the name 'x13tbx\exe\', I think. Anyway, I adjusted that in your code and now it no longer creates that folder.

But I still get the same error message that it can't fin the field x2d. I try to find the place the place where that field is supposed to be created, and it seems to be in x13composite.m, line 710. The resulting 'console' variable that I get says:
'/bin/bash: /Users/hansschlemmer/Desktop/x13tbx/exe/x12diag03.exe: cannot execute binary file'

That doesn't sound good...

I'm sorry to hear about your trouble, Christian. The directory structure must be as follows: x13tbx, x13tbx\exe, x13tbx\@x13series, x13tbx\@x13composite, x13tbx\@x13spec, x13tbx\doc, x13tbx\demo, x13tbx\tools (this last one is optional).

The program uses the exe-files in the folder x13tbx\exe (so, for instance, x13tbx\exi\x13as.exe and x13tbx\exe\x12diag03.exe).

Could you please try to adapt your directory structure in this fashion and tell me if that helps?

Christian

Thank you, Yvan!

I can't get the demos to run. For instance, for the GDP demo file, I get the following error:

No appropriate method, property, or field 'x2d' for class 'x13series'.
Error in X13DemoGDP (line 97)
strOUT = xgdp.(allseries{c}).x2d;

I manually downloaded the .exe files, and put them into the .exe folder. Strangely, your code also seems to create an additional .exe folder, called x13tbx\exe\, in the same location as the x13tbx folder.

In which variable do I find the s.a. series?

Thanks!

Roger Zhu

Thank you, Bugme, for these words. I am glad that my work has proven useful for you ... and thanks for pointing out this mistake. It will be corrected in the next release. :-)

Dear Yvan,

a million times thank you for this great work! You spared me hundreds of hours of work to interface the X-13 Applications. And your Demos: Outstanding, thank you for that!

Hint: In your Demo-File X13DemoFIXED.m (Line 153), there is an typo; it should be:

c_20 = corrcoef(resid(ok_20),s.ir.ir_20(ok_20));

Best,
Jonathan

Wayne Zhang

Dear Yvan,
Thanks for your help and I have made it work. It is really a good Toolbox.
Best
Wayne

Wayne,

It should be easy to download. If the Matlab program cannot doenload it automatically, you should be able to find the programs on the Census website. However, I just sent you the files my email. That is probably even easier.

Let me know how it goes.

Cheers, Yvan

Wayne Zhang

Dear Yvan,

Tht CensusProgram can not be downloaded, could you send me by email. My email address is javey115@gmail.com

Best

The new version 1.20.2 addresses the bug discovered by Carlos.

Carlos

Thank you!! I made it work!

Thank you, Carlos. You have uncovered a bug. Could you please change the following lines in x13.m:

line 636: 'toolbox (''%s'').'], 'omegav03.zip', progloc);

line 655: 'toolbox (''%s'').'], theZIP, progloc);

So in both cases, the p must be replaced by progloc. I will upload a bugfix in the next few days.

But this will not solve your problem (it will only make the error come out correctly).

It appears that your computer is unable to download or install the software from the US Census Bureau. You will need to do this manually.

Browse to https://www.census.gov/srd/www/x13as/ and click on the link on the left 'Download X-13 (PC)' if you use a windows computer, or 'Download X-13 (Linux)' if you're working on a Linus computer.

On the next page, locate the link to 'x13as_V1.1_B26.zip' (or 'x13ashtml_V1.1_B26.zip' if you plan on using the 'accessible version'), unzip this archive and copy the x13as.exe file conteined in this archive to the exe subdirectory of your Matlab X-13 Toolbox.

After this, you should be able to run with the 'noflags' option,

x = x13([dateX,data_.HICP],'noflags')

'noflags' is necessary because otherwise an additional program from the US Census Website is required (x12diag.exe), and it is very likely that your computer will be unable to install that as well.

Please let me know if all of this helps to resolve the issue or not.

Carlos

Hi! First, thank you very much for coding this! I am trying to run it, but I always get the following error:

x = x13([dateX,data_.HICP])
Downloading 'x13as_V1.1_B26.zip' from US Census Bureau website ...
Undefined function or variable 'p'.

Error in x13 (line 650)
err = MException('X13TBX:X13:ProgramMissing', ...

dateX is a column vector with numerical Matlab dates, and data_.HICP is the vector of data. Could you please help me? Thanks!

Carlos

Esmail

Dear Yvan,

I sincerely thank you very much for your kind help to install your toolbox. I appreciate your efforts and Patience helping a matlab beginner.

An amazing toolbox!!

Best,
Esmail

Grace, Could you please send me your email to yvan.lengwiler-at-unibas.ch?

Grace,

I'm sorry to hear about these troubles. The url works fine on my computer. Have you tried to browse to this link (https://www.census.gov/ts/x13as/pc/x13as_V1.1_B26.zip) sing your browser? If that doesn't work, the problem must be in your interne connection or maybe the website is blocked for some reason.

In any case, I have recently made some changes to InstallMissingCensusProgram, but not yet released the new version. I send you the beta version of this program by email. Please let me know, first, if the link works, and second, if the problem goes away with the appended beta version.

Sincerely,
Yvan

Grace

Hi, I followed the steps to install the toolbox but still failed to get it installed. I am getting the following error message:

InstallMissingCensusProgram()
Downloading 'x13as_V1.1_B26.zip' from US Census Bureau website ...
Warning: Download from url 'https://www.census.gov/ts/x13as/pc/x13as_V1.1_B26.zip' failed.
> In InstallMissingCensusProgram>InstallMissingPiece (line 254)
In InstallMissingCensusProgram (line 226)

Dear Halil,
I'm glad it works. Let me know if you encounter other problems :-)

Dear Yvan, I can resolve the problem. When I install toolbox and then I reopen Matlab. Thank you very much for your helpful comments.

Thank you very much Yvan, I can do it with your directions :D

But I have also some questions when I run your toolbox, I have receieved this messages:

" We start our demonstration of fixedseas with some artificial data. These data
consist of a linear trend, two sinus cycles with periodicity of 14 and 20,
and some noise. We will try to identify these periods (as if we didn't know
them already) and then filter them out.

Error using plot (line 249)
First or second arg must be an x13series object.

Error in plot (line 799)
plot(ax(cntAx),dates,toplot, ...

Error in X13DemoFIXED (line 92)
plot(s);

Error in run (line 96)
evalin('caller', [script ';']);"

Dear halil,
I'm glad you like the toolbox and I will try to help you resolve the problems you have encontered. To install the toolbox, you need to do the following:

1) Download the ZIP-File from the FEX.

2) Extract the ZIP. This will create a directory called x13tbx which contains files and several subdirectories.

3) Put the new x13tbx as well as x13tbx\demo into Matlab's path.

You should now be able to run the demos.

The Toolbox needs some files from the US Census Bureau website and attempts to download them on demand. To install all necessary files from the Census website, run InstallMissingCensusProgram once from the Matlab prompt.

Please let me know if this helps.

This is very useful toolbox thanks to Yvan Lengwiler. But, could I ask some questions?
1) Must I install all m.files in a one file?
2) I cannot run demo files :(
3) How can I install this toolbox in matlab?

Thanks and kind regards

YSS

Yvan, thanks for your program and the adaption to Matlab 2012b.

YSS

smw

Great program and great timing for me - I only looked for an X13 tool for MATLAB yesterday.

Yvan has developed a very comprehensive and user-friendly tool, and with the updates all demos run smoothly on my system running R2014b.

Thanks Yvan!

Stephen

Updates

1.33

Several programs have been added that do seasonal filtering independently of the Census programs, seas subdirectory. The graphical user interface guix has been thoroughly improved as well.

1.32.1.0

bugfix in yqmd.m

1.32.0.0

Support for datetime class. New auxiliary functions, such as addCDT, addASC, and preadjustOnePeriod; see documentation for fill description.

1.31.0.0

Adaptation to new US Census Version, X-13ARIMA-SEATS Version 1.1 Build 39.

1.30.0.0

New seasonal adjustment CAMPLET algorithm by Abeln and Jacobs provides an alternative to X-13. Also, new function addspectrum, addacf, addpcf for computing correlation functions and spectra in Matlab and adding the results to an x13series object.

1.21.1.0

Further bug fix. (Getting better only incrementally :-)

1.21.0.0

New utility (x13toxls) for exporting a x13series variable into an Excel sheet. Bugfix in x13spec causing entries in regression-user to be sorted (they should not be sorted).

1.20.2.0

Version 1.20.1 had a wrong title in the FEX description. Sorry.

1.20.1.0

Carlos, a user of FEX, has found a small bug that prevents an error message to display correctly. This has been fixed. Also, InstallMissingProgram.m has been extended to cover more tools offered by the US Census Bureau.

1.20.0.0

Better support for user-defined variables to be used in regression ('regression','file' spec). Double precision in reading from and writing to data files.

1.19.0.0

Several improvements here and there.

1.18.1.0

I bad bug has slipped into guix. This is fixed now. Sorry for any inconvenience.

1.18.0.0

Better support for user-defined exogenous variables in regressions. Support for 'byperiod' and 'separate' plots for data that are neither quarterly not monthly.

1.17.6.0

guix provides now access to command line switches for the Census program.

1.17.4.0

Significant improvement of guix. It is now possible to load existing x13series objects and their specifications into guix. There, you can conveniently experiment with the specification, and then send the result back to the main (no-guix) workspace.

1.17.3.0

Buttons for accessing documentation from guix. Bug fix in x13series related to fixedseas.

1.17.2.0

Significant improvement of guix (select the date-range with sliders). Furthermore, be advised that I have slightly altered the definition of the 'X11' in makespec.

1.17.1.0

Improvements to guix.

1.17.0.0

Graphical user interface GUIX for performing seasonal adjustments interactively. Several smaller improvements and some minor bug fixes.

1.16.0.0

Update to Version 1.1 Build 26 of the Census program. Small bugfixes.

1.15.0.0

Significant speed improvement. Series will now be mapped to the first day of month if this is the case for the original data as well. New 'spline' and 'polynomial' options for fixedseas. Improvement of .arima, bugfix in .isLog.

1.14.0.0

Improved backward compatibility. Overloaded version of seasbreaks for x13composite. Several smaller bugfixes and improvements.

1.13.2.0

Sorry. The new seasbreaks program was missing in the last distribution (my bad). I have also added a new property .coef to the x13series class. (Try it out to see what it is.)

1.13.1.0

Correction of a mistake in a demo file. No changes to the programs.

1.13.0.0

New seasbreaks program to identify seasonal breaks. Better support for PICKMDL model files. Integration of fixedseas into x13spec, with fore-/backcast extension before computing trend for simple seasonal adjustment. Various other improvements.

1.12.0.0

Several improvements: Ensuring backward compatibility back to 2012b (possibly farther); Added 'seasma' option to x13; Added RunsSeasma to x13series; other improvements throughout.

1.11.0.0

No change of code. Only change to list of required products (no products besides Matlab are required).

1.10.0.0

Support of 'accessible version' (i.e. tables in HTML) of the x13as.exe program. Several bug fixes. Improved help.

1.9.0.0

Support for the new version 1.1 build 19 of the Census X-13 software of April 2, 2015.

1.8.0.0

Sorry, another bugfix.

1.7.0.0

small bugfix

1.6.0.0

Tables from .out property are more reliably extracted. seasma has more options.

1.5.0.0

seasma now supports fractional periods and multiplicative decomposition

1.4.0.0

major bugfix in x13composite

1.3.0.0

correction of list of required products

1.2.0.0

typo

1.1.0.0

Compatibility issue related to ML 2014b resolved.
Automatic extraction of X-13 tables.
Several smaller bug fixes and improvements.

MATLAB Release Compatibility
Created with R2012b
Compatible with any release
Platform Compatibility
Windows macOS Linux