% ERROR_ELLIPSE  plot an error ellipse, or ellipsoid, defining
% confidence region
% ERROR_ELLIPSE(C22)  Given a 2x2 covariance matrix, plot the
% associated error ellipse, at the origin. It returns a graphics handle
% of the ellipse that was drawn.
%
% ERROR_ELLIPSE(C33)  Given a 3x3 covariance matrix, plot the
% associated error ellipsoid, at the origin, as well as its projections
% onto the three axes. Returns a vector of 4 graphics handles, for the
% three ellipses (in the XY, YZ, and ZX planes, respectively) and for
% the ellipsoid.
%
% ERROR_ELLIPSE(C,MU)  Plot the ellipse, or ellipsoid, centered at % MU, a vector whose length should match that of C (which is 2x2
% or 3x3).
%
% ERROR_ELLIPSE(...,'Property1',Value1,'Name2',Value2,...) sets
% the values of specified properties, including:
% 'C'  Alternate method of specifying the covariance matrix
% 'mu'  Alternate method of specifying the ellipse (oid) center
% 'conf'  A value betwen 0 and 1 specifying the confidence interval.
% the default is 0.5 which is the 50% error ellipse.
% 'scale'  Allow the plot the be scaled to difference units.
% 'style'  A plotting style used to format ellipses.
% 'clip'  specifies a clipping radius. Portions of the ellipse, oid,
% outside the radius will not be shown.
%
% NOTES: C must be positive definite for this function to work
% properly.
AJ Johnson (2021). error_ellipse (https://www.mathworks.com/matlabcentral/fileexchange/4705error_ellipse), MATLAB Central File Exchange. Retrieved .
Inspired: Gaussian Mixture Probability Hypothesis Density Filter (GMPHD)
Find the treasures in MATLAB Central and discover how the community can help you!
Start Hunting!Create scripts with code, output, and formatted text in a single executable document.
Awesome work. Would be convenient if you could use this just to compute the xy coordinates of the ellipse instead of plotting. Would also be nice to output the radii information.
I stumbled across another little thing today, it´s a rather subtle error but occured in a kind of typical situation:
I was trying to export a plot that contained my sample data plotted using the scatter function and the according error ellipse using hold on + error_ellipse.
However, exporting to svg file format resulted in very poor quality and I was not able to adjust single elements of the plot as I would be normally able to.
Exporting to any other file format or changing renderer/ resolution/ etc didnt help.
Plotting only the ellipse without scattered sample data didnt produce the problem.
In the end commenting out line 137 set(h1,'zdata',z+1) solved the problem. Not quite sure why. My guess is the plot may became 3d and the renderer couldnt handle that.
Any other solution to this?
Works just fine. However the documentation is misleading/ incomplete. For the new version it seems confidence intervals are defined directly (i.e. for 95% CI put 'conf' .95). From the attached document it seems you would have to specify a "k" value. Also an example for style would have been nice. Basicly works same as for plot command, eg 'k.' will give you a black color dotted line.
Hello AJ Johnson Thanks for this. I am having this error...... ''Don't know what to do with 0x0 matrix''..... after I entered the values for C, mu, scale, conf and clip.
@Matthias Y The confidence intervals are different depending on the number of dimensions. For twodimensional data, try changing 0.68 to 0.3934. (A useful table is provided on page 3 of the documentation.)
In your example, error_ellipse(covm,'conf',0.3934) should produce a circle (or rather, nearcircle) with a radius equal to the standard deviation.
Thanks a Lot you saved me time, Appreciate Sir.AJ Johnson
Thank you so much!!
Is the way the confidence interval is plotted correct?
Take the 2D example. Isn't the stddev the distance from the origin to the outermost points of the ellipse for each axis. If I do this:
samples = randn(200,2);
covm = cov(samples);
error_ellipse(covm,'conf',0.68);
std_devx = sqrt(covm(1));
My stddev for the x axis (std_devx) is somehow not matching the error_ellipse for 0.68% confidence.
works, easy
Perfect. Saved me hours of reading and code writing.
works fine. thank you!
Nice piece of code.
Thank you, good for learning
Thanks AJ! Delicious BSD license :)
What's the license on this submission, anyone know?
Should the second argument to qchisq not be the degrees of freedom, rather than the number of parameters?
This was excellent for learning about Kalman filters.
Thank you,it was useful!
I have a question about the k value since I'm not familiar with statistics: why do you get it from a k square distribution and not from a normal distribution?
Really very helpful. But did not understand how to calculate k value from conf "k = sqrt(qchisq(conf,r))" Does anybody know how this relation holds? Thanks..
Thanks. Saved a lot of my time.
Very helpful and easy to use.
thanks for conf. interval comment phil fox
Ooops, there's an obvious mistake in my area/volume calculation from above. I forgot to factor in the quantile for the desired percentile, i.e., you have to multiply the area/volume with the quantile of the desired confidence interval (conf). You can use the embedded functions from error_ellipse to calculate Pconf (for the default of conf=0.5, Pconf(2D)=1.1774/Pconf(3D)=1.5382). The formular for area (volume accordingly) should read:
area=prod(sqrt(eig(C)))*pi*Pconf
@Jenn Risk & @me: Finally got a solution for area/volume. It's all based on the eigenvalues of the CovMatrix (the prerequisite for error_ellipse).
Area (2D): area=prod(sqrt(eig(C)))*pi
Volume (3D): volume=prod(sqrt(eig(C)))*4/3*pi
Hope that helps. Cheers!
Worked just great for me and saved a LOT of time writing my own code. Thanks!
I'm currently working on a area/volume calculation. @Ahmed Fasih: det(covMatrix) may definately be used as a measure, however, it's not the actual area/volume.
Jenn Risk: just use det(CovMatrix) for area/volume.
M ChC, Volkan Ozturk:
figure; handle(1)=error_ellipse(A); hold on; handle(2)=error_ellipse(B); handle(3)=error_ellipse(C); set(handle(2), 'color','r', 'linestyle',':'); set(handle(3), 'color','k', 'linestyle','');
Perfect piece of code! I am using it alot. Had to change the API though to make it a bit more flexible in terms of plot properties (e.g. passing it a parent axes handle).
??? function h = error_ellipse(varargin)

Error: Function definitions are not permitted at the prompt or in scripts.
I get the above error, can anyone help ? I am using MATLAB 7.6.0(2008a). Thanks
Very helpful optically  but can it calculate the area of the error ellipse? I couldn't easily get it to adapt to this. Any help would be great!
Sorry, but my previous comment contained some errors:
 C = [1 2; 2; 4]. This is not a valid covariance matrix.
 "positive semidefinite symmetric (that is, they may include negative values off the diagonal)." This is not true.
What is true, is that C must be a positive semidefinite matrix. But that is just a minor comment, because the implementation allows for that.
Conclusion:
This Matlab function works. Thanks!
% NOTES: C must be positive definite for this function to
% work properly.
This is quite a strange restriction, because covariance matrices are positive semidefinite symmetric (that is, they may include negative values off the diagonal). For example, it is not possible to visualize the following very simple, and valid, covariance matrix: C = [1 2; 2; 4].
Does anybody know of a Matlab function which is capable of visualizing all kinds of covariance matrices (both 2D and 3D)? Thanks!
function works great and is easy to use. thank you
Delightful tool, easy to use and worked straight away
Did the job flawlessly.
re: change color, multiple ellipses on same plot
To have multiple ellipses, just type 'hold on' in the command window before calling error_ellipse. You can change the color once you've plotted the ellipse in the property editor (open pe in view>property editor)
precisely what i needed! hooray.
how do I change the color of the ellipse?
excellent, thanks.
Thank you very much!!! Excellent!
very useful. thank you
Be aware that the default confidence interval is 0.5 rather than more standard values such as 0.683, 0.9 etc.. Use the 'conf' parameter to change.
How can i see two plots on the same graphics. I have to do some comparison.
Regards
handy
Excellent.
perfect! works great AND easy to use.
Great code, very useful. Saved me lots of time.
Great code, thanks.
You just saved me a day and most of my hair :)
Amazing. Good work! Thanks a lot!
Very Useful!
worked perfectly! Thanks!
Excellent
Works perfectly
It works excellent
There is NOT an error at line 117.
works fabulously.
There is an error at line 117. The line reads: XYZ = [X(:),Y(:),Z(:)]*sqrt(eigval)*eigvec'; but should be: XYZ = [X(:),Y(:),Z(:)]*eigvec*sqrt(eigval)*eigvec';
Doesn't run. I get an error...
??? Undefined command/function 'getopt'.
Error in ==> error_ellipse at 61
prop = getopt(default_properties, varargin{:});
Now it's working fine.
Thanks again!
U.
It doesn't work on my matlab platform (6.1).