MATLAB users can run the research apps offered on this site directly from their own scripts: the official MATLAB API wrapper sends your input files to our research API, runs the calculation on our servers, and downloads the finished result files. For readers who want to understand the mechanics behind an abnormal return calculation, the original MATLAB implementation is described at the end of this page.
The MATLAB API wrapper
The matlab-wrapper repository provides the EventStudyAPI class. It is written in pure MATLAB on top of matlab.net.http, requires no toolboxes, and works on MATLAB R2016b or newer.
Installation
Clone or download the repository and add it to your MATLAB path:
addpath('path/to/matlab-wrapper')API key
Running an analysis requires an API key. Free academic keys, valid for one month, are available to researchers and students: request yours with your university email address on the API access page. General (non-academic) key access is currently paused. Pass the key to the constructor or set the EST_API_KEY environment variable.
Quickstart
api = EventStudyAPI('YOUR_API_KEY');
files = struct( ...
'request_file', '01_RequestFile.csv', ...
'firm_data', '02_FirmData.csv', ...
'market_data', '03_MarketData.csv');
results = api.run(EventStudyAPI.arcParams(), files, 'results');
caar = readtable('results/caar_results.csv', ...
'FileType', 'text', 'Delimiter', ';');run() wraps all steps from authentication to result download. EventStudyAPI.arcParams() accepts name-value options such as the benchmark model and the result file type, and avcParams() and avycParams() configure the abnormal volume and abnormal volatility analyses in the same way. Sample data and a runnable script are included in the repository's examples/ folder. The full request parameters and the underlying API protocol are documented on the API documentation page.
Input data format
The wrapper works with three semicolon-separated CSV files without header rows, with dates formatted as dd.mm.yyyy:
- Request file: each record represents one firm-event to be analyzed, described by an event ID, the firm and market identifiers, the event date, a grouping variable, and the parameters of the estimation window and the event window.
- Firm data: closing prices of the company stocks (firm ID, date, closing price).
- Market data: closing values of the reference indices (market ID, date, index value).
How the abnormal return calculation works
For readers who want to understand what happens behind the API call, the following describes the market model calculation as implemented in the original MATLAB code.
The function transforms each input file into arrays of structures. At the same time, each date is transformed from a text format into a single identifying number, and the prices are replaced with calculated returns. An index marking the beginning of each company record is created to speed up the analysis. The function then loops through the records of the request file. For each event, it finds all the records for the event window in the dataset for companies and the dataset for index data. It calculates a regression between the returns of the company and the index in the estimation window and applies the coefficients of this regression to calculate the expected returns of the company in the event window, based on the value of the index return in this time period. The differences between the actual and expected returns yield the abnormal returns for each day within the event window.