Manual for the use of the Astronomical Component Estimation Model version 1 (ACE v.1)
(Last update 22-08-2016)

Sinnesael, M., Zivanovic, M., De Vleeschouwer, D., Claeys, P., and Schoukens, J.
"Astronomical component estimation (ACE v.1) by time-variant
sinusoidal modeling", submitted to Geoscientific Model Development. 
--------------------------------------------------------------------------------------

GENERAL INFO:

----------

ACE v.1 is designed in a MATLAB environment. 

It includes a mainscript and three functions: 

(0) "ACEv1_MAINSCRIPT"

which is the script that can be run to load data, specify model parameters, call the 
functions for the calculations and provide basic graphic output.

(1) "OrbitalComponentEstimation"

which estimates waveforms from astronomical components.

(2) "SedimentationRateEstimation"

which estimates the instaneous frequencies and associated sedimentation rates based 
on the output of function (1)

(3) "UncertaintyAnalysis"

which gives a measure for uncertainty (one standard deviation using the covariance 
matrix and Monte Carlo simulations) for the estimations of the instaneous frequency 
and sedimentation rate.

----------

REQUIRED INPUT DATA:

((0) "ACEv1_MAINSCRIPT": a data file (see input function 1) and setting the model parameters

((1) "OrbitalComponentEstimation"): a nx2 matrix containing the stratigraphic series with in 
the first column the m-levels and in the second the data. !!! Uniform sampling is assumed.!!!

This can for example be done by reading a text file into MATLAB

e.g. data = load('datacontainingtextfile.txt');


((2) "SedimentationRateEstimation"): the ouput of function (1).

((3) "UncertaintyAnalysis"): the ouput of function (1) and (2).

----------

PROVIDED OUTPUT:

The functions are designed to export the raw data (.mat) which then can be used for various
purposes according to the users wish (e.g. plotting).

(0) The output of all used functions (1-3) with additionally basic graphs plotting the
    input data, estimated waveforms, instaneous frequencies, sedimentation rates and their 
    uncertainties (standard deviations, default one standard deviation)

(1) "EstimatedComponents.mat" wich contains the waveforms of the n estimated components

(2) "InstanteousFrequecyEstimates.mat " wich contains the estimated instaneous frequencies
 of the n estimated components

    "SedimentationRateEstimates.mat" wich contains the estimated sedimentation rates of 
the n estimated components

(3) "freqInstStd.mat" which contains the standard deviation on the estimated instaneous frequency

    "SRStd.mat" which contains the standard deviation on the estimated sedimentation rate

-------------------------------------------------------------------------------------
DETAILED USERS INSTRUCTIONS:

THE MATLAB SCRIPTS THEMSELVES ARE ALSO COMMENTED TO PROVIDE INSTRUCTIONS

(0) "ACEv1_MAINSCRIPT"

% About:
%   This script is part of the complementary material for the manuscript
%   entitled "Astronomical component estimation (ACE v.1) by time-variant
%   sinusoidal modeling", submitted to Geoscientific Model Development
%   (Sinnesael et al., 2016).(Last update: 22/08/2016).
%
%   This mainscript contains four main parts:
%
%   1) DATA INPUT: load your data, for example as a text file
%
%   2) PARAMETER SPECIFICATION: specify the model parameters
%
%   3) CALCULATIONS: run three functions "OrbitalComponentEstimation",
%   "SedimentationRateEstimation" and "UncertaintyAnalysis" with the
%   specified model parameters (2) and return numerical output.
%
%   4) BASIC GRAPHICAL OUTPUT: basic plots plotting per estimated component 
%   in function of depth: the estimated waveform, instantaneous frequency 
%   changes, estimated sedimentation rate and the corresponding 
%   uncertainties. The user is free to make customize the plotting 
%   statements or to export the variables and plot them elsewhere. 

(1) "OrbitalComponentEstimation"

function OrbitalComponentEstimation(data,Nsources,bands,windowsize,Porder)

% OrbitalComponentEstimation - Extracts principal orbital components from
%   cyclostratigraphic data.
%
% About:
%   This script is part of the complementary material for the manuscript
%   entitled "Astronomical component estimation (ACE v.1) by time-variant
%   sinusoidal modeling", submitted to Geoscientific Model Development.
%
% Input:
%   data              Stratigraphic series: first column should be depth 
%                     (in meters), second column should be data value.
%                     Uniform sampling is assumed.
%   Nsources          Number of orbital components to extract
%   bands             (Nsources x 2)-matrix where each row encompasses
%                     the lower and upper frequency bound (in Hz) for a 
%                     given component.
%                     These frequency ranges can be determined using for
%                     example spectral anlysis (Periodogram, MTM etc.)
%   windowsize        length of the analysis frame in meters
%                     See Chapter 2.3 in Sinnesael et al., 2016, 
%                     Geoscientific Model Development for instructions
%   Porder            number of terms for the polynomial approximation.
%                     See Chapter 2.3 in Sinnesael et al., 2016, 
%                     Geoscientific Model Development for instructions%
%
% Description:
%   Estimates the spatial-domain waveforms of orbital compnents by means of
%   non-stationary polyinomial-based sinusoidal modeling. Key reference: 
%   Zivanovic, M., and Schoukens, J. "On The Polynomial Approximation for 
%   Time-Variant Harmonic Signal Modeling", IEEE Transactions on Audio, 
%   Speech, and Language Processing, 19, 458-467, 2011.
%
% Example:
%   OrbitalComponentEstimation(data,2,[0.01 0.07; 0.18 0.25],80,2)

(2) "SedimentationRateEstimation"

function SedimentationRateEstimation(fileName,windowsize,Porder,Tnominal)

% InstantaneousFrequencyEstimation - Estimates the sedimentation rate from 
% the estimated waveforms of the orbital components. 
%
% About:
%   This script is part of the complementary material for the manuscript
%   entitled "Astronomical component estimation (ACE v.1) by time-variant
%   sinusoidal modeling", submitted to Geoscientific Model Development.
%
% Input:
%   fileName          *.mat file containing the estimated orbital
%                     component waveforms
%   windowsize        length of the analysis frame in meters
%                     See Chapter 2.3 in Sinnesael et al., 2016, 
%                     Geoscientific Model Development for instructions
%   Porder            number of terms for the polynomial approximation.
%                     See Chapter 2.3 in Sinnesael et al., 2016, 
%                     Geoscientific Model Development for instructions%
%   Tnominal          nominal orbital component period in kyr
%                     Predicted periods for precession and obliquity can be
%                     found in Berger et al., (1992) or Laskar et al.,
%                     (2004)
% Description:
%   From spatial-domain waveforms it estimates the instantaneous frequency
%   and sedimentation rate for orbital components.
% Example:
%   SedimentationRateEstimation('EstimatedComponents',60,2,[41 23])

(3) "UncertaintyAnalysis"

function UncertaintyAnalysis(fileName,windowsize,Porder,Tnominal)

% SedimentationRateEstimationPlusUncertainty - Estimates the sedimentation rate from 
% the estimated waveforms of the orbital components, together with
% corresponding uncertainties (one standard deviation).
%
% About:
%   This script is part of the complementary material for the manuscript
%   entitled "Astronomical component estimation (ACE v.1) by time-variant
%   sinusoidal modeling", submitted to Geoscientific Model Development.
%
% Input:
%   fileName          *.mat file containing the estimated orbital
%                     component waveforms
%   windowsize        length of the analysis frame in meters
%   Porder            number of terms for the polynomial approximation.
%   Tnominal          nominal orbital component period in kyr
%
% Description:
%   From spatial-domain waveforms it estimates the instantaneous frequency
%   and sedimentation rate for orbital components. By means of Monte Carlo
%   simulations it provides the uncertainties on the sought instantaneous
%   frequency and sedimentation rate (one standard deviation).
% Example:
%   SedimentationRateEstimationPlusUncertainty('EstimatedComponents',25,3,[100 41])


--------------------------------------------------------------------------------------

REFERENCES:

Sinnesael, M., Zivanovic, M., De Vleeschouwer, D., Claeys, P., and Schoukens, J.
"Astronomical component estimation (ACE v.1) by time-variant
sinusoidal modeling", submitted to Geoscientific Model Development. 

Estimates the spatial-domain waveforms of orbital compnents by means of
non-stationary polyinomial-based sinusoidal modeling. Key reference: 

Zivanovic, M., and Schoukens, J. "On The Polynomial Approximation for 
Time-Variant Harmonic Signal Modeling", IEEE Transactions on Audio, 
Speech, and Language Processing, 19, 458-467, 2011.