NonstationaryExtremeValueAnalysis(NEVA)SoftwarePackage

UserGuide

Update:10/23/2014

NonstationaryExtremeValueAnalysis(NEVA)SoftwarePackage

UserGuide

Center for Hydrology & Remote Sensing

University of California, Irvine

Authors:

LinyinCheng

and

AmirAghaKouchak

Disclaimer:TheNonstationaryExtremeValueAnalysis(NEVA)softwarepackageisprovided'asis'withoutany endorsement made and without warranty of any kind, either express or implied. While we strive toensurethatNEVAisaccurate,noguaranteesfortheaccuracyofthecodes,outputinformationandfiguresaremade.NEVAcodesandoutputscanonlybeusedatyourowndiscretionandriskandwithagreementthatyouwill be solely responsible for any damage and that the authors and their affiliate institutions accept noresponsibilityforerrorsoromissionsinNEVAcodes,outputs,figures,anddocumentation.Innoeventshallthe authors, developers or their affiliate institutions be liable to you or any third parties for any special,direct, indirect or consequential damages and financial risks of any kind, or any damages whatsoever,resultingfrom,arisingoutoforinconnectionwiththeuseofNEVA.TheuserofNEVAagreesthatthecodesandalgorithmsaresubjecttochangewithoutnotice.

NonstationaryExtremeValueAnalysis(NEVA)SoftwarePackage:

UserGuide

LinyinCheng,andAmirAghaKouchak

UniversityofCalifornia,Irvine

Abstract

TheNonstationaryExtremeValueAnalysis(NEVA)softwarepackagehasbeendevelopedtofacilitateextremevalueanalysisunderbothstationaryandnonstationaryassumptions.InaBayesianapproach,NEVAestimatestheextremevalueparameterswithaDifferentialEvolutionMarkovChain(DE‐MC)approachforglobaloptimizationovertheparameterspace.NEVAincludesposteriorprobabilityintervals(uncertaintybounds)ofestimatedreturnlevelsthroughBayesianinference,withitsinherentadvantagesinuncertaintyquantification.Thesoftwarepresentstheresultsofnon‐stationaryextremevalueanalysisusingvariousexceedanceprobabilitymethods.Weevaluatebothstationaryandnon‐stationarycomponentsofthepackageforacasestudyconsistingofannualtemperaturemaximaforagriddedglobaltemperaturedataset.TheresultsshowthatNEVAcanreliablydescribeextremesandtheirreturnlevels.

Thesourcecodecanbedownloadedfromhere:http://amir.eng.uci.edu/neva.phpMainreferencepublication:Cheng L., AghaKouchak A., Gilleland E., Katz R.W., 2014, Non‐stationary Extreme ValueAnalysisinaChangingClimate,ClimaticChange,doi:10.1007/s10584‐014‐1254‐5.http://amir.eng.uci.edu/publications/14_NEVA_CC.pdf

TableofContents

1  Overview of NEVA Components ........................................................................................... 1 

2  Run NEVA GEV..................................................................................................................... 2 

2.1  Open NEVA.m in MATLAB ........................................................................................... 2 

2.2  Specify the path to the package in NEVA.m ................................................................... 3 

2.3  Navigate to ReadData folder in NEVA_GEV .................................................................. 3 

2.4  Configure NEVA GEV .................................................................................................... 3 

2.4.1.  Edit GEV_sta_nonsta.txt to set the model parameters (ReadData folder): .............. 4 

2.4.2.  Edit input data file si1.txt (ReadData folder): ........................................................... 4 

2.4.3.  Edit names.txt (ReadData folder) ............................................................................ 5 

2.4.4.  Edit prior.txt (ReadData folder) ............................................................................... 5 

2.5  Read the ReadMe File (zreadme.txt in NEVA_GEV) ..................................................... 5 

2.6  Run NEVA GEV .............................................................................................................. 5 

3  Run NEVA GPD ..................................................................................................................... 6 

3.1  Open NEVA.m in MATLAB .......................................................................................... 6 

3.2  Specify the path to the package in NEVA.m ................................................................... 6 

3.3  Navigate to ReadData folder in NEVA_GPD .................................................................. 6 

3.4  Configure NEVA GPD ..................................................................................................... 6 

3.4.1.  Edit GPD_sta_nonsta.txt to set the model parameters (ReadData folder): ............... 7 

3.4.2.  Edit input data file si1.txt (ReadData folder): ........................................................... 8 

3.4.3.  Edit names.txt (ReadData folder) ............................................................................ 8 

3.4.4.  Edit prior.txt (ReadData folder) ............................................................................... 8 

3.4.5.  See ReadMe File (zreadme.txt in NEVA_GPD) ...................................................... 8 

3.5  Run NEVA_GPD ............................................................................................................. 8 

4  Save Outputs ........................................................................................................................... 9 

5  Errors and Warnings ............................................................................................................... 9 

ReferencesandRelevantLiterature .......................................................................................... 10 

P a g e | 1

1 Overview of NEVA Components

NEVAincludestwocomponents:

(1) The Generalized Extreme Value (GEV) distribution for analysis of annualmaxima(blockmaxima).(2) TheGeneralizedParetoDistribution(GPD)foranalysisofextremesaboveacertainthreshold(i.e.,peak‐over‐threshold(POT)approach).

Both NEVA GEV and NEVA GPD can be used for stationary (time‐independent) andnonstationary(transient)extremevalueanalysis.

P a g e | 2

Thepackageincludesthefollowingfilesandfolders:

1‐FolderNEVA_GEV: Includes source codes for stationaryandnonstationaryGeneralizedExtremeValue(GEV)distributionforanalysisofannualmaxima(blockmaxima).

2‐FolderNEVA_GPD: Includessourcecodes forstationaryandnonstationaryGeneralizedPareto Distribution (GPD) for analysis of extremes above a certain threshold (i.e., peak‐over‐threshold(POT)approach).

3‐FileDisclaimer.txt: By using NEVA users agreewith this disclaimer. Please read thedisclaimerbeforeusingNEVA.

4‐NEVA_ReferencePublication.pdf:ReferencepublicationofNEVA.

5‐NEVA_User_Guide.pdf:Thisdocument

2 Run NEVA GEV

FollowthebelowstepstorunNEVA:

2.1 Open NEVA.m in MATLAB

Note that both NEVA_GEV, andNEVA_GPD include NEVA.m. Forannual maxima analysis, selecttheone inNEVA_GEVfolder.ForPOT analysis, open the one inNEVA_GPDfolder(seeSection3).

P a g e | 3

2.2 Specify the path to the package in NEVA.m

Forexample:dirr= 'C:\Users\Amir\Google Drive\AMIR\MySoftware\NEVA_GEV';

2.3 Navigate to ReadData folder in NEVA_GEV

2.4 Configure NEVA GEV

YoucanconfigureNEVAGEVbyeditingthefilesinReadDatafolder. Therefourfilesthatcanbeedited:GEV_sta_nonsta.txt, names.txt, si1.txt, prior.txt

GEV_sta_nonsta.txt:includesmodelparameters

names.txt:includesfiguretitlesandaxeslabels(theyappearintheoutputfigures)

prior.txt:includepriorparameters(rangesofmodelparametersusedforsampling)

si1.txt:includesinputdata

In GEV_sta_nonsta.txt make sure the stationary and nonstationary assumptions arecorrectlyconfigured:

Nonsta=0indicatesstationary

Nosta=1representsnonstationarywithtimevaryinglocationparameter

Nosta=2representsnonstationarywithtimevaryinglocationandscale

P a g e | 4

2.4.1. Edit GEV_sta_nonsta.txt to set the model parameters (ReadData folder):

da: endyearoftheobservations

evl: numberofrandomsamplesforparameterestimation

bur: numberofburnedsamples

cha: chainnumber(5isreasonable)

sts: afterburnin,ifwanttofurtherreducesamplesizeeditsts

siteNO: numberofsites/gauges

Nonsta: 0:stationarysimulation;

1:nonstationarityinlocationparameter;

2:nonstationarityinlocationandscaleparameters

tt: Simulationtimeorreturnperiod

done: Notifybyemailwhensimulationiscomplete:0:No;else:Yes

plottrend:plottrendlines;0:No;else:Yes

GEVQQ: generateQQplotstoevaluateifdatafitsGEV;0:No;else:Yes

wait: Simulationbasedonthewaitingtimetheory

lir: likelihoodratiotest;0:No;else:Yes

BF: Bayesfactorcalculation;0:No;else:Yes

Quic: likelihoodprofileestimation;0:No;else:Yes(the default Quic=0 offers parameter estimation and uncertainty boundsbasedonthemethodoutlinedinChengetal.,2014.Forfastersimulation,theusercanchoosethemaximumlikelihoodmethodQuic=1.Thelatterrequirestheoptimizationtoolbox.

2.4.2. Edit input data file si1.txt (ReadData folder):

Lastcolumn: year

Othercolumns: Block maxima (annual maxima) from stations/gauges/modelsimulations

P a g e | 5

2.4.3. Edit names.txt (ReadData folder)

Thisfileonlychangestitlesandlabelsintheoutputfigures:

Firstline: titlethatappearsintheoutputfigure.Usethefirstlineforstationaryplots

Secondline:title that appears in the output figure. Use the first line for nonstationaryplots

Thirdline: xlabel(labelofx‐axis)

Fourthline: ylabel(labelofy‐axis)

2.4.4. Edit prior.txt (ReadData folder)

Thedefaultvaluesshouldbereasonableformostapplications:

SIGMA: therangeofthescaleparameterinGEVdistribution

K: therangeoftheshapeparameterinGEVdistribution

Apha: therangeoftheslopeforthelocationparameterundernonstationary

Beta: therangeoftheinterceptforthelocationparameterundernonstationary

Asig: therangeoftheslopeforthescaleparameterundernonstationary

Bsig: therangeoftheinterceptforthescaleparameterundernonstationary

2.5 Read the ReadMe File (zreadme.txt in NEVA_GEV)

See the readme file to learn more about the input variables and parameters inGEV_sta_nonsta.txt,names.txt,si1.txt,prior.txt

2.6 Run NEVA GEV

RunNEVA.minMatlab(NEVA_GEVfolder).

P a g e | 6

3 Run NEVA GPD

FollowthebelowstepstorunNEVA:

3.1 Open NEVA.m in MATLAB

3.2 Specify the path to the package in NEVA.m

Forexample:dirr= 'C:\Users\Amir\Google Drive\AMIR\MySoftware\NEVA_GPD';

3.3 Navigate to ReadData folder in NEVA_GPD

3.4 Configure NEVA GPD

YoucanconfigureNEVAGPDbyeditingthefilesinReadDatafolder. Therefourfilesthatcanbeedited:GPD_sta_nonsta.txt,names.txt,si1.txt,prior.txt

GPD_sta_nonsta.txt:includesmodelparameters

names.txt: includesfiguretitlesandaxeslabels(appearintheoutputfigures)

prior.txt: includepriorparameters(rangesofmodelparameters

Note that both NEVA_GEV, andNEVA_GPD include NEVA.m. Forannual maxima analysis, selectthe one in NEVA_GEV folder(Section 2). For POT analysis,open the one in NEVA_GPDfolder.

P a g e | 7

si1.txt: includesinputdata

In GPD_sta_nonsta.txt make sure the stationary and nonstationary assumptions arecorrectlyconfigured:

Nonsta=0 indicatesstationarysimulation

Nonsta=1 representsnonstationarysimulation

3.4.1. Edit GPD_sta_nonsta.txt to set the model parameters (ReadData folder):

da: endyearoftheobservations

evl: numberofrandomsamplesforparameterestimation

bur: numberofburnedsamples

cha: chainnumber(5isreasonable)

sts: afterburnin,ifwanttofurtherreducesamplesizeeditsts

siteNO: numberofsites/gauges

Nonsta: 0:stationarysimulation;1:nonstationaritysimulation;

tt: Simulationtimeorreturnperiod

done: Notifybyemailwhensimulationiscomplete:0:No;else:Yes

plottrend:plottrendlines;0:No;else:Yes

GPQQ: generateQQplotstoevaluateifdatafitsGPD;0:No;else:Yes

thp: GPDthreshold

lir: likelihoodratiotest;0:No;else:Yes

BF: Bayesfactorcalculation;0:No;else:Yes

Quic: likelihoodprofileestimation;0:No;else:Yes(the default Quic=0 offers parameter estimation and uncertainty boundsbasedonthemethodoutlinedinChengetal.,2014.Forfastersimulation,theusercanchoosethemaximumlikelihoodmethodQuic=1.Thelatterrequirestheoptimizationtoolbox.

P a g e | 8

3.4.2. Edit input data file si1.txt (ReadData folder):

Lastcolumn: year

Othercolumns: Block maxima (annual maxima) from stations/gauges/modelsimulations

3.4.3. Edit names.txt (ReadData folder)

Thisfileonlychangestitlesandlabelsintheoutputfigures:

Firstline: titlethatappearsintheoutputfigure.Usethefirstlineforstationaryplots

Secondline:title that appears in the output figure. Use the first line for nonstationaryplots

Thirdline: xlabel(labelofx‐axis)

Fourthline: ylabel(labelofy‐axis)

3.4.4. Edit prior.txt (ReadData folder)

Thedefaultvaluesshouldbereasonableformostapplications:

SIGMA: therangeofthescaleparameterinGPD

K: therangeoftheshapeparameterinGPD

Apha: therangeoftheslopeforthescaleparameterundernonstationary

Beta: therangeoftheinterceptforthescaleparameterundernonstationary

3.4.5. See ReadMe File (zreadme.txt in NEVA_GPD)

Read the readme file to learn more about the input variables and parameters inGPD_sta_nonsta.txt,names.txt,si1.txt,prior.txt.

3.5 Run NEVA_GPD

RunNEVA.minMatlab.

P a g e | 9

4 Save Outputs

InbothNEVA_GEVandNEVA_GPD,allthesampledparametersareautomaticallysavedintosaveDatafolderattheendofthesimulation.Forexample,

smp1.mat: includes sampled parameters for station 1 under stationaryassumption;

nonsmp1.mat: includes sampled parameters for station 1 under nonstationaryassumptionwithtime‐varyinglocationparameter;

non5smp1.mat includes sampled parameters for station 1 under nonstationaryassumptionwithtime‐varyinglocationandscaleparameters;

acceptanceR.mat summarize theR_hat values to check themodel convergenceunderstationaryassumption(seeChengetal.,2014).

nonacceptanceR summarize the R_hat values to check themodel convergence undernonstationaryassumption(seeChengetal.,2014).

5 Errors and Warnings

In both NEVA_GEV and NEVA_GPD, errors and warnings are automatically saved inreport.txt(stationary)andreportNON.txt(nonstationary).

P a g e | 10

ReferencesandRelevantLiterature

AghaKouchak,A.,D.Easterling,K.Hsu,S.Schubert,andS.Sorooshian(2013)ExtremesinaChangingClimate,Springer,SpringerNetherlands.

Cheng L., AghaKouchak A., Gilleland E., Katz R.W., (2014), Non‐stationary Extreme ValueAnalysisinaChangingClimate,ClimaticChange,doi:10.1007/s10584‐014‐1254‐5.

Cooley, D. (2009) Extreme value analysis and the study of climate change. ClimaticChange,97,77‐83.

Gilleland,E.,Katz,R.W. (2011)”Newsoftware toanalyzehowextremeschangeover time”Eos,92(2),13—14.

Katz,R.(2010),Statisticsofextremesinclimatechange,ClimaticChange,100(1),71‐76.

Katz,R., etal., (2002)Statisticsofextremes inhydrology,AdvancesinWaterResources,25,1287‐1304.

Renard,B.,etal.(2006)AnapplicationofBayesiananalysisandMarkovchainMonteCarlomethods to the estimation of a regional trend in annual maxima. Water resourcesresearch,42.

Renard, B., et al. (2013) Bayesian methods for non‐stationary extreme value analysis,ExtremesinaChangingClimate,SpringerNetherlands.

P a g e | 11

Formoreinformationvisit:

http://amir.eng.uci.edu/neva.php