File Exchange

image thumbnail


version (13.2 KB) by Andrew Roberts
Quiver (vector) with a reference vector or color code on a map or Cartesian axes.


Updated 23 Feb 2015

View Version History

View License

This function is a substitute for the standard versions of quiver and quiverm available using a vanilla release of matlab. This version assumes a 2D vector field is being plotted using a gridded flow field from a numerical model. It is primarily intended for Earth System Model analysis.
The function enables the scaling of vectors according to a reference vector plotted in the lower right hand corner of the plot axes. The function works for both map and Cartesian axes and allows the color of vectors to be changed.

If a reference value is not provided, the reference value is calculated by rounding the median or maximum magnitude of the quiver vectors. Scaling of vectors still occurs even if the reference vector plotting is switched off. This enables different subplots to share identical scaling so that the relative magnitude of vectors can be compared between subplots (provided they share the same grid).

The function also includes the ability to plot color vectors, all of equal length but color coded according to their magnitude. In this case, a colorbar is provided, complete with units, and no scaling vector is plotted.

Vectors are centered on the grid points they represent, rather than the tail of the arrow being positioned on the grid point as is the case for the vanila Matlab quiver and quiverm versions.

Cite As

Andrew Roberts (2021). ncquiverref (, MATLAB Central File Exchange. Retrieved .

Comments and Ratings (48)

zk Zhao

Kefei Wang

This function is easier to use than the original Matlab quiverm, and it's great to have a reference vector.
But the fixed position of reference vector(text/patch) is not suitable for all cases I needed, and can be overlapped by meridian label.
Can the reference label be adjusted as legend function, I mean it has location / fontname / fontsize to be modified?

Alexandra Narizhnaya

I could not quite understand whether i could use your function to change the visualising the lon-step of vector - For ex, i want to decrease it twice for easier wind interpretation.
Do you know how can i do it?

Andrew Roberts

Hello Jelena,

You are on the right thought path by changing lz, except that will only change the z-coordinate of the reference vector in the code available here. For your particular case, I would like to suggest that you change the following lines in the code:


changed to:

lz = 2*ones(size(ly));



changed to:

lz = 2*ones(size(ly));

This sould set the vectors above the surface you plotting. Please note that I've not tested this before writing, but I'm confidant it will work, providing you wave height surface falls be beneath a z-coordinate of 2.


Jelena Janjic


Great function! Thanks for sharing! I am having a bit of an issue with this function though. I want my wind speed vectors to be on top of a layer (a colour map produces with trisurf) that represents wave height. Unfortunately, the vectors end up being underneath. This is similar to this question for quiver3 ( I just don't know how to apply it in this function. I tried changing lz but that didn't help.

Please help :)


John Mayfield

Can you please do a wind barb program as well?

Muhammad Usman Saleem

there is not any example about how to use this code. Please add example to this beautiful code in order to batter and more use for community

Muhammad Usman Saleem

many thanks..

Andrew Roberts

The code plots a vector for every data point you give it. If you would like to thin your vectors, then either generate an input field that sub-samples your data (e.g. plotting every second point), or that averages your data (e.g. averaging the positions and data for a 4x4 mat of your data, using this derived field as your input). If you wish to plot pressure-latitude plots, then simply use the Cartesian axis option, as described in the documentation.
- Andrew

Kai Melamed-Turkish

As well, do you have a suggestion for how to use this code to generate a vertical cross-section (pressure-latitude) of wind direction and magnitude?

Thanks again,


Kai Melamed-Turkish

Hi Andrew,

This is some really good code! I am just wondering how I might ba able to modify the spacing between the vectors plotted? I am using the very high resolution NARR dataset which I interpolated to a 0.25x0.25 latitude (~30 km), longitude grid. I feel like this could be the issue, though it seems like the vectors are being plotted even more frequently than the grid-spacing, but that could just be my eyes. Regardless, is there a way to specify the vector spacing without changing the resolution of the data?

Thanks very much,



Andrew Roberts

The link for the code is at the top right under "Download Zip". If, however, you are asking for the particular data used to produce these figures, I am unfortunately not at liberty to release it to Matlab Central at this time.
- Andrew

can zu

Dear sir,

Where is the code of the example figure?
I want to run the example code and learn the ncquiverref function better.


Ruth Cerezo

Andrew Roberts


You can change the size of the vector with the 'reftype' argument. See the documentation at the head of the file for more information.

Caiwang ZHENG

I have a question: how to change the size of arrow?

Andrew Roberts

Hi Gino,

In order to make the vector plotting efficient, this routine in fact plots all vectors as one continuos line, separated by NaNs between vectors. Therefore changing the width of individual vectors will require a modification to the code, and of course would require input of a humidity field to guide the line width of the vectors. Plotting vectors individually will, of course, slow down the routine as the vector plotting will need to be placed in some kind of for loop, but it can be done. If you would like to proceed, this is the code that needs to be in the for loop, plotting each vector one at a time:

% Center vectors over grid points
[u,v] = pol2cart(th(mask),scalelength);

% Get x coordinates of each vector plotted
lx = [xstart; ...
xstart+(1-arrow/3)*(xend-xstart); ...
xend-arrow*(u+arrow*v); ...
xend; ...
xend-arrow*(u-arrow*v); ...
xstart+(1-arrow/3)*(xend-xstart); ...

% Get y coordinates of each vector plotted
ly = [ystart; ...
ystart+(1-arrow/3)*(yend-ystart); ...
yend-arrow*(v-arrow*u); ...
yend; ...
yend-arrow*(v+arrow*u); ...
ystart+(1-arrow/3)*(yend-ystart); ...

% Plot the vectors

When you use the "line" function, set a linewidth scaled by your humidity field.

- Andrew


Dear Andrew,

Thanks for the amazing code. I would like to highlight the arrows plotted on top Relative Humidity WRF model output. For these, I would like to change the width of ALL the arrows (change the 'LineWidth'), and being able to play with it in other to highlight the encounter of dry and moist air with the wind vectors.

Any suggestions will be greatly appreciated.

Thank you very much,



Dear Andrew,
Now the code works fine. Thank you so much! Looking forward to the release of the new analysis package:)


Andrew Roberts


Please package up a test case with data, and send it to me so I can take a look. Before doing this, please try:


I am assuming that in your original message you meant:

12 1
20 1
12 20
size(v_ch) <--- note change from latt in your message
12 20

- Andrew


Hi Andrew.
Thanks. My matlab is 2010b version. and I still have the same problem with new version.


Andrew Roberts

Dear Ada, AS et al.,

I have uploaded a new version of this file so that it now works with the graphics changes introduced in R2014b. The appearance is slightly different from the attached figure. I hope this helps. This is an interim measure before the aforementioned package is released this year.


Andrew Roberts

Hello Ada,

Sorry you are having problems using this with R2014b. ncquiverref is part of a Matlab analysis package for Earth System Models that I have written and will be released in 2015.

In the interim, I believe switching the line:




will work.

ncquiverref posted here is an early developmental version, and my current version is vastly different from this posting, and takes advantage of many of the graphics changes in R2014b. It includes callbacks for the colorbar and vector key that allows them to be placed in multi-panel figures using an optimized fit routine not available in the vanilla MATLAB release. As a result, the latest version of ncquiverref is not a stand-alone routine, but an integral part of a larger package primarily focused on analyzing sea ice, ocean and atmosphere models, and the Los Alamos Sea Ice Model, in particular. For this reason I have not provided updates to ncquiverref here, but will be releasing the full package later this year.



I tried to use this function to plot vectors along with ref vector as:

12 1
20 1
12 20
12 20

It plotted the vectors in the map but did not print reference vector and got error as follows:

??? Error using ==> text
Invalid parameter/value pair arguments

Error in ==> ncquiverref at 397

Can anyone hep me.


Hi Andrew,
Great code and thanks for sharing! but I get a few error messages when running the code to get coloured vectors.
In Matlab version R2014b, colorbars and legends do not contain handles to underlying objects in their Children properties. Which results in error messages for all the colorbar properties you define. At least for me...

Error using patch
While setting the 'Parent' property of Patch:
Patch cannot be a child of ColorBar.

Error in ncquiverref (line 292)

Any suggestions how to fix this problem?



Andrew Roberts

Hello Preeti,

The example I provided in June 17 2014 was simply to give a square matrix of four (u,v) pairs and their geolocation. Note that the second row is lat = [1 1] (degrees North), lon=[0 1] (degrees east), u=[-1 0] (in specified units), v=[-1 1] (in specified units.

Apologies for the delay in my response.

preeti rajput

hello sir
I was trying to plot my current vectors using your code i.e. ncquiverref. I have a query regarding the dataset:
lat=[41.1700 -73.1300; 1.0000 1.0000];
lon=[35.2200 -75.6200; 0 1.0000];
u=[30.3800 -84.3500; -1.0000 0];
v=[25.9000 -97.4200; -1.0000 1.0000];
which you have mention on 17june 2014 in your comment.

what does the second row represents(lat = [1 1]; lon=[-1 0]; u=[-1 0]; v=[-1 1]);
Sir, your advice will be very useful for me.




Dang, you are right of course. In my excitement to see something that would plot geographic-coordinate vectors I failed to internalize the very clear statement that the code assumes a gridded field. Guess I'll keep looking and/or work on writing some code to do what I need.

Thanks for your prompt response. It's much appreciated.

Andrew Roberts

Hello "K",

The documentation clearly states that "This version assumes a 2D vector field being plotted using a gridded flow field from numerical models with a regular geometry".

If you set:

lat=[41.1700 -73.1300; 1.0000 1.0000];
lon=[35.2200 -75.6200; 0 1.0000];
u=[30.3800 -84.3500; -1.0000 0];
v=[25.9000 -97.4200; -1.0000 1.0000];

You will find that you get output, and the function works as designed and documented.

If your inputs are not on a grid, then this is not the function for you. Alternatively, if your inputs are on a 2D grid, but are organized into a vector, then you will need to reorganize your data back onto the 2D grid.

- Andrew


This code looks like it'll do what I want it to do, which is plot vectors (or straight-up direction arrows) in geographic coordinates. Thanks! Unfortunately I'm getting an error at line 151:

[u,v] = pol2cart(th+deg2rad(thproj),z);

The problem is that in my application th is a vector (n rows, one column) but thproj is an array (n rows, n columns). Perhaps I'm just misinterpreting the input variables?

%Clear and close all files, windows, etc.
close all;

%Open Excel Data File
filename=input('enter filename: ','s');
lat=data(:,1); %create latitude vector
lon=data(:,2); %create longitude vector
u=data(:,3); %create u-component vector;
v=data(:,4); %create v-component vector;

%Create a map
ax = usamap('conus');
set(ax, 'Visible', 'off')
latlim = getm(ax, 'MapLatLimit');
lonlim = getm(ax, 'MapLonLimit');
states = shaperead('usastatehi',...
'UseGeoCoords', true, 'BoundingBox', [lonlim', latlim']);
geoshow(ax, states,'FaceColor','white')
grid off;

%Plot arrows

Here's my test data file (lat, lon, u, v):
41.1700 -73.1300 1.0000 1.0000
35.2200 -75.6200 0 1.0000
30.3800 -84.3500 -1.0000 0
25.9000 -97.4200 -1.0000 1.0000

Chad Greene

This function is an incredible improvement over quiverm for two key reasons:

1. quiverm confoundingly thinks insists that u is a meridional component and v is a zonal component, but ncquiverref gets it right.

2. quiverm scales relative to lats and lons, so if you're plotting an absolute field such as surface wind velocity, vectors shrink near the poles using quiverm whereas ncquiverref gets it right.

The only two changes I'd make are 1. switch to a more intuitive name for the function (quite trivial and users can easily do this on their own) and 2. add an option to easily switch between centering arrows over their reference points or starting them at the reference points, because which the user prefers may depend on the data being plotted.

Overall a fantastic, adaptable, and robust script. Thanks for sharing, Andrew.

Andrew Roberts

Hi Nelson,

It's almost impossible to understand what you are doing without an example. Most problems with ncquiverref result from the data not being prepared as specified in the documentation, so check this carefully. If you are unable to resolve the problem, please send me your script and some sample data so that I can check on what you are doing, and then I'll let you know if I can help.

Andrew Roberts


My u,v vector in quiverm is strange.....
Do I have to translate to another coordinate or do something else?

Eowyn Baughman

An enormous improvement on quiver when working with geophysical model data. If you want to chance the color of the reference scale vector, change line 440 to line(lx,ly,lz,'Color','k');

This way you can overplot white vectors on a colored figure but have a visible reference vector.

Boris Mifka

Dear Matlab users. Does anyone use ncquiverref function? I have a problem because it has error due to 208 line , index exceeds matrix dimensions. I didn t manage to find out what is the problem , and i need this referent arrow on my plot

Thanks a lot. It is a great work.


I am having trouble running this code.. just to be double sure, what should I specify in contours?

I'm getting this error message:
??? Index exceeds matrix dimensions.

Error in ==> ncquiverref at 208

I would be very thankful if any suggestions are made.


Is there any way to get this to plot vectors over a pcolor plot? I can get the vectors on just fine, but as soon as I plot the reference vector it whites everything out. Modification ideas?

Josh Jones

Thibaut Leroy

Andrew Roberts

Hi Hamed,

If you have tested using "max" instead of "median" for reftype, or your color vectors are too long, it is easy to adjust the variable "scalelength" to a fraction of its current value in the code. Change line 186 to:
where 0<X<1.
The main reason you may have to make this manual adjustment is if your vector magnitudes are strongly negatively skewed.


Great code, just a question,

how to scale vector field as it is in quiver command, the default size of vectors is too much for my application.


Chong Zhou

Genius work! It gives amazing visualisation of large amount of vectors, which is common in the data post-processing in article image velocimetry (PIV). The author also improved the code to better adapt to the application in PIV, where 'axis ij' is a must to plot pixel coordinate.

Again, great work and I strongly suggest people using PIV try this code!

Many thanks!

Jason Sippel

Great code! After chatting with the author, I have found that the below addendum is useful for plotting a small subdomian of model output. This would be useful if, for example, you are tracking a tropical cyclone in a Lagrangian system with ilat,flat,ilon, and flon sampled from your model grid based on the number of grid points from the storm center.

If you don't do something similar to this, the physical size of the map frame on the screen may not match from one figure to the next.

Here's the code:


cutfactor = 1.3;
set(gca,'Xlim',[xcenter-cutfactor*xoffset xcenter+cutfactor*xoffset]);
set(gca,'Ylim',[ycenter-cutfactor*yoffset ycenter+cutfactor*yoffset]);

Jason Sippel

Ibrahim M

This is genius!

For it to work in multiple colors, you make sure your x and y are produced with/as meshgrid. Also specify your colors according to your choice of colorbar. Eg if your caxis ([15 30]) for SST, then you should have the function as:

ncquiverref(x,y,xx,yy, 'DegC','mean',0,'col',[15 20 25 30]);

Nice work Andrew!

Thank you very much for sharing!!


MATLAB Release Compatibility
Created with R2014b
Compatible with any release
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!