libDirectionalisalibraryfordirectionalstatisticsaswellasrecursiveestimationondirectionalmanifolds.Thesupportedmanifoldsinclude
unitcircleunithyperspherecomplexunithyperspheretorusSE(2)Foreachofthesemanifolds,thelibrarycontainscertainprobabilitydistributionsaswellasrecursivefilteringalgorithms.
InstallationRequirements:
Matlab2021aorlaterasuitablecompiler(VisualStudio2015,VisualStudio2017,MinGW64,gcc4.7orlater,XCode)TouselibDirectional,addtheentirelib-folderincludingsubdirectoriestoMatlab'ssearchpath.Then,changetothelib-folderandrunthecompileAll.mscript.Thisscriptshouldcompileallmex-filesusedbylibDirectional.
Ifyouexperienceanyissues,runmex-setupandmex-setupC++toensurethatyouhaveselectedthecorrectcompiler.Incaseyouhavetroublecompilingwithgcc,makesurethatyouareusingaversionthatisofficiallysupportedbyMATLAB.
ThefollowingtoolboxesarerecommendedforlibDirectional:
image_toolboxoptimization_toolboxstatistics_toolboxsymbolic_toolboxThestatisticstoolboxandtheoptimizationtoolboxarefairlywidelyused,buttheothertoolboxesareonlyrequiredforcertainveryspecificfeatures.
Example:PlottingProbabilityDensityFunctionsForexample,wecangenerateatwo-dimensionalplotofthepdfofawrappednormaldistributionwithparametersmu=2andsigma=1.3simplybytypingthefollowingtwocommands.
>>wn=WNDistribution(2,1.3);>>wn.plot2d();Wecanthensetthelabelsandaxisusingthefollowingcode:
>>setupAxisCircular('x');>>xlabel('x');ylabel('f(x)');Similarly,wecancreateplotsofotherdistributions.Athree-dimensionalplotofthepdfofavonMisesdistributionwithparametersmu=6andkappa=0.5couldbegeneratedusingthefollowingcode.
>>vm=VMDistribution(6,0.5);>>vm.plot3d('color','red');>>holdon;vm.plotCircle('color','black');holdoff;>>xlabel('cos(x)');ylabel('sin(x)');zlabel('f(x)');Example:NumericalandAnalyticalCalculationLetusagainconsiderthewrappednormaldistributiondefinedinthepreviousexample.Supposewewanttocalculatethefirsttrigonometricmoment,i.e.,E(exp(ix)),ofthisdistribution.Forthispurpose,wesimplycallthecorrespondingfunction:
>>wn.trigonometricMoment(1)Thisproducestheoutput
ans=-0.1788+0.3906iInthecaseofthewrappednormaldistribution,trigonometricMomentisafunctioninsidetheclassWNDistributionthatimplementsananalyticcalculationofthetrigonometricmoment.Ifnoanalyticsolutionwasimplemented,thefunctiontrigonometricMomentinthebaseclassAbstractCircularDistributionwouldautomaticallyfallbacktoanalgorithmbasedonnumericalintegration.Eventhoughananalyticalsolutionisavailableforthewrappednormaldistribution,wecanstillcallthenumericalalgorithmasfollows.
>>wn.trigonometricMomentNumerical(1)Weobtaintheresult
ans=-0.1788+0.3906iThiscan,forexample,beusedtocomparethenumericalandanalyticalresultsinordertoensurecorrectnessoftheanalyticalimplementation.Inthiscase,bothresultsmatchuptothedisplayednumberofdigits,butincertaincases,analyticalandnumericalsolutionsmaydiffermoresignificantly.
Example:NonlinearCircularFilteringLetusconsiderasystemwithcircularstatex_kin[0,2pi)anddynamics
x_{k+1}=a(x_k)+w_ka_k(x_k)=x+0.1cos(x_k)mod2piwherew_kisdistributedaccordingtoWN(x;0,0.4)IfweassumethatthecurrentstateisdistributedaccordingtoWN(x;2,0.5),wecanperformthepredictionstepwiththeWN-assumedfilterusingthefollowingcommands.
>>filter=WNFilter();>>filter.setState(WNDistribution(2,0.5));>>a=@(x)mod(x+0.1*cos(x),2*pi);>>filter.predictNonlinear(a,WNDistribution(0,0.4));>>filter.getEstimate()Thisproducestheoutput
ans=WNDistributionwithproperties:mu:1.9623sigma:0.6092Asyoucansee,thepredicteddensityisreturnedasawrappednormaldistribution.Nowweconsiderthemeasurementmodel
z_k=h_k(x_k)+v_kwith
h_k:[0,2pi)->R,h_k(x)=sin(x)wherev_kisadditivenoisedistributedaccordingtoN(x;0,0.7).Asyoucansee,wehaveacircularstate,butareal-valuedmeasurement,inthiscase.However,acircularmeasurement(orameasurementonacompletelydifferentmanifold)wouldbepossibleaswell.Ifweobtainameasurement,sayz=0.3,wecanperformthemeasurementupdateasfollows.
>>h=@(x)sin(x);>>measurementNoise=GaussianDistribution(0,0.7);>>likelihood=LikelihoodFactory.additiveNoiseLikelihood(h,measurementNoise);>>filter.updateNonlinearProgressive(likelihood,0.3)>>filter.getEstimate()Thisproducestheoutput
ans=WNDistributionwithproperties:mu:2.0030sigma:0.6414Onceagain,weobtaintheresultasawrappednormaldistribution.
UnitTestsTheunittestsforlibDirectionalarelocatedinthetestssubfolder.YoucanautomaticallyrunallunittestsbyexecutingrunLibDirectionalUnitTests.Teststhatareverycomputationallyexpensiveareskippedbydefault.YoucanenablecomputationallyexpensivetestsbyrunningrunLibDirectionalUnitTests(true),whichismorethoroughbuttakesmuchmoretime.
ExternalslibDrectionalreliesonthefollowingexternallibraries,whicharealsoincludedintheexternalsfolder.
Eigen(MPL2)fmath(BSD)mhg(GLPv2orlater)Faddeva(MIT)NonlinearEstimationToolbox(GPLv3),onlythenecessarysubsetisincludedinexternalsfolderTesselateS3(GPLv3)ModifiedversionsofSlepianAlphaandSlepianBravo(GPLv2orlater)Wigner3j(BSD)AmodifiedversionoftheRecursiveZonalEqualAreaSpherePartitioningToolbox(MIT)Furthermore,weusethescriptcircVMcdfbyShaiRevzen(GPLv3).WealsousesomecodefromlibBingham(BSD),butthislibraryisnotintheexternalsfolderasonlysmallpartsareused.
LicenselibDirectionalislicensedundertheGPLv3license.
CitationIfyouuselibDirectionalinyourresearch,pleasecitethelibraryusingasfollows.
@Article{libdirectional,author={GerhardKurzandIgorGilitschenskiandFlorianPfaffandLukasDrudeandUweD.HanebeckandReinholdHaeb-UmbachandRolandY.Siegwart},title={DirectionalStatisticsandFilteringUsing{libDirectional}},year={2019},journal={JournalofStatisticalSoftware},volume={89},number={4},pages={1--31},doi={10.18637/jss.v089.i04},}ContactLeadauthor:GerhardKurz
Mail:kurz.gerhard(at)gmail.com
Web:https://www.gerhardkurz.de
Contributors:
IgorGilitschenskiFlorianPfaffLukasDrude
评论