njtbx-icon
Netcdf-Java Toolbox
previous Quick Tutorial
NJ Functions Next

 
 
User Guide
In the segments below, you will find help on how to create dataset and variable objects, extract data and grid information, and much more. There are three different ways user can extract data and grid information using NJ toolbox (njTBX). First, making calls to njTBX API, second, accessing data using subscripted refrencing, and third, using high level convenience functions based on njTBX API. The scenarios shown below describe different ways of using NJ toolbox.

Scenarios


  • Create a Dataset (mDataset) object and check available methods. 
    • Specify data location. The data location can be local or remote (e.g http, thredds, dods). Note: If working offline, then set 'ncRef' to use file 'examples/data/bora_feb.nc'.
    • >> ncRef = 'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
    • Call mDataset class contructor.
    • >> ncObj =  mDataset(ncRef) 
      ncObj = 
                    URI:  'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
               numGrids: 19
          numDimensions: 12
           numVariables: 80
    • Use 'whos' command to see class type for 'njObj' dataset object.
    • >> whos                  
          Name        Size            Bytes  Class        Attributes
          ncObj       1x1               934   mDataset              
          ncRef       1x72              144   char 
    • Check available methods.
    • >> methods(ncObj)
       Methods for class  mDataset:
       close   display   getAttributes  getGeoGridVar   getInfo   getJDataset    getVar    mDataset       numel    subsref
      See functions nj_varget  nj_tslice nj_grid_varget

  • Create a grid variable (mGeoGridVar) object, extract data and grid infromation. 
    • Specify data location. The data location can be local or remote (e.g http, thredds, dods). Note: If working offline, then set 'ncRef' to use file 'examples/data/bora_feb.nc'.
    • >> ncRef = 'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
    • Call mDataset class contructor to create mDataset object.
    • >> ncObj =  mDataset(ncRef) 
      ncObj = 
                    URI:  'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
               numGrids: 19
          numDimensions: 12
           numVariables: 80
    • Set variable 'var = temp'. Call mDataset method 'getGeoGridVar' to create a grid variable object 'mGeoGridVar'.
    • >> var = 'temp';
      >> gVarObj = getGeoGridVar(ncObj, var) 
      gVarObj = 
            Variable: 'temp'
          Dimensions: '[   ocean_time = UNLIMITED;   // (8 currently),    s_rho = 20;,    eta_rho = 60;,    xi_rho = 160;]'
    • Use 'whos' command to see class type for 'gVarObj' grid variable object.
    • >> whos                  
          Name        Size            Bytes  Class        Attributes
         gVarObj      1x1               660  mGeoGridVar              
         ncObj        1x1               934  mDataset                 
         ncRef        1x72              144  char                     
         var          1x4                 8  char
    • Check available methods.
    • >> methods(gVarObj)
      Methods for class mGeoGridVar:
      display           getAttributes     getData           getShape          subsetGeoGridVar  
      end               getCoordSys       getGrid           mGeoGridVar       subsref
    • Extract data for 1st time step.
    • >> timeStep = 1;
      >> varData = getData(gVarObj, timeStep);
      >> whos varData
        Name          Size                 Bytes  Class     Attributes
        varData      20x60x160            768000  single
    • Get associated grid data (i.e lat, lon and time)
    • >> varGrid = getGrid(gVarObj);
      >> varGrid
      varGrid = 
           lat: [60x160 double]
           lon: [60x160 double]
             z: [4-D double]
          time: [7.3162e+005 7.3162e+005 7.3163e+005 7.3163e+005 7.3163e+005 7.3163e+005 7.3163e+005 7.3163e+005]
      >> whos varGrid
        Name         Size               Bytes  Class     Attributes
        varGrid      1x1             12442160  struct
      See functions  nj_grid_varget   nj_subsetGrid

  • Create a variable (mVar) object, and get atttributes associated with the variable. 
    • Specify data location. The data location can be local or remote (e.g http, thredds, dods). Note: If working offline, then set 'ncRef' to use file 'examples/data/bora_feb.nc'.
    • >> ncRef = 'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
    • Call mDataset class contructor to create mDataset object.
    • >> ncObj =  mDataset(ncRef) 
      ncObj = 
                    URI:  'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
               numGrids: 19
          numDimensions: 12
           numVariables: 80
    • Set variable 'var = temp'. Call mDataset method 'getVar' or use subscripted reference to create a variable object 'mVar'.
    • >> var = 'temp';
      >> varObj = getVar(ncObj, var) 
      or
      >> varObj = ncObj{var}
      
      varObj = 
         float temp(ocean_time=8, s_rho=20, eta_rho=60, xi_rho=160);
           :long_name = "averaged potential temperature";
           :units = "Celsius";
           :time = "ocean_time";
           :coordinates = "lat_rho lon_rho";
           :field = "temperature, scalar, series";
    • Use 'whos' command to see class type for 'varObj' variable object.
    • >> whos                  
          Name        Size            Bytes  Class        Attributes
         gVarObj      1x1               660  mGeoGridVar              
         ncObj        1x1               934  mDataset                 
         ncRef        1x72              144  char                     
         var          1x4                 8  char
         varObj       1x1               652  mVar
    • Check available methods
    • >> methods(varObj)
      Methods for class mVar:
      display     end     getAttributes  getData        getShape       getTimes       isGridded      mVar    subsref
    • Use method 'getAttributes' to retrieve variable attributes.
    • >> varAttr = getAttributes(varObj)
      varAttr = 
                field: 'temperature, scalar, series'
                 time: 'ocean_time'
            long_name: 'averaged potential temperature'
          coordinates: 'lat_rho lon_rho'
                units: 'Celsius'
      See functions nj_varget  nj_attget

  • Create a grid coordinates (mGridCoordinates) object. 
    • Specify data location. The data location can be local or remote (e.g http, thredds, dods). Note: If working offline, then set 'ncRef' to use file 'examples/data/bora_feb.nc'.
    • >> ncRef = 'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
    • Call mDataset class contructor to create mDataset object.
    • >> ncObj =  mDataset(ncRef) 
      ncObj = 
                    URI:  'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
               numGrids: 19
          numDimensions: 12
           numVariables: 80
    • Set variable 'var = temp'. Call mDataset method 'getGeoGridVar' to create a grid variable object 'mGeoGridVar'.
    • >> var = 'temp';
      >> gVarObj = getGeoGridVar(ncObj, var) 
      gVarObj = 
            Variable: 'temp'
          Dimensions: '[   ocean_time = UNLIMITED;   // (8 currently),    s_rho = 20;,    eta_rho = 60;,    xi_rho = 160;]'
    • Call method 'getCoordSys'.
    • >> gridCoordObj = getCoordSys(gVarObj) 
      gridCoordObj = 
                  Grid: 'temp'
              TimeAxis: 'Yes'
          VerticalAxis: 'Yes'
              DateTime: 'Yes'
      >> whos gridCoordObj
        Name              Size            Bytes  Class               Attributes
        gridCoordObj      1x1              1316  mGridCoordinates

  • Quick display of netcdf data information. 
    • Specify data location. The data location can be local or remote (e.g http, thredds, dods). Note: If working offline, then set 'ncRef' to use file 'examples/data/bora_feb.nc'.
    • >> ncRef = 'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
    • Call mDataset class contructor.
    • >> ncObj =  mDataset(ncRef) 
      ncObj = 
                    URI:  'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
               numGrids: 19
          numDimensions: 12
           numVariables: 80
    • Call method 'getInfo'.
    • >> info = getInfo(ncObj)
      info =
      Gridset 0 coordSys=(ocean_time lat_v lon_v) t=ocean_time,y=lat_v,x=lon_v,  Projection: LatLon LLbb= ll: 40.04N 11.48E+ ur: 46.05N 20.12E
      Name___________Unit___________hasMissing_____Description
      AKs            meter2 second-1 false    averaged salinity vertical diffusion coefficient
      AKt            meter2 second-1 false    averaged temperature vertical diffusion coefficient
      .......
      .......
      GeoReferencing Coordinate Axes
      Name___________Len__Unit________________Type___Description
      lat_psi 9381 degree_north type=Lat latitude of PSI-points
      lat_rho 9600 degree_north type=Lat latitude of RHO-points
      ........
      ........
      netcdf dods://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc {
       dimensions:
         ocean_time = UNLIMITED;   // (8 currently)
         s_w = 21;
         eta_rho = 60;
         xi_rho = 160;
      .....
      ......
      
      See functions nj_info

  • Extract variable data using matlab subscripted referencing. 
    • Specify data location. The data location can be local or remote (e.g http, thredds, dods). Note: If working offline, then set 'ncRef' to use file 'examples/data/bora_feb.nc'.
    • >> ncRef = 'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
    • Call mDataset class contructor to create mDataset object.
    • >> ncObj =  mDataset(ncRef) 
      ncObj = 
                    URI:  'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
               numGrids: 19
          numDimensions: 12
           numVariables: 80
    • Set variable 'var = temp'. Call mDataset method 'getVar' or use subscripted reference to create a variable object 'mVar'.
    • >> var = 'temp';
      >> varObj = getVar(ncObj, var) 
      or
      >> varObj = ncObj{var}
      
      varObj = 
         float temp(ocean_time=8, s_rho=20, eta_rho=60, xi_rho=160);
           :long_name = "averaged potential temperature";
           :units = "Celsius";
           :time = "ocean_time";
           :coordinates = "lat_rho lon_rho";
           :field = "temperature, scalar, series";
    • Check variable shape, and apply subscripted referencing on the variable object to get data as shown below.
    • >>  shape = getShape(varObj)
      shape =
           8    20    60   160
      
      >> varData = varObj(1,2:2:20,1:59,4:end);
      >> whos varData
        Name          Size                 Bytes  Class     Attributes
        varData      10x59x157            370520  single              
      
    • One can also extract variable data by directly applying the subcripted referecing on 'mDataset' object as well. Follow scenario-1 to create mDataset object. i.e. ncObj. Apply subscripting reference as shown below.
    • >> var = 'temp';
      >> varData = ncObj{var}(1,2:2:20,1:59,4:end);
      >> whos varData
        Name          Size                 Bytes  Class     Attributes
        varData      10x59x157            370520  single  
      

  • Extract gridded-variable data and grid information using matlab subscripted referencing without creating geogrid variable object. 
    • Specify data location. The data location can be local or remote (e.g http, thredds, dods). Note: If working offline, then set 'ncRef' to use file 'examples/data/bora_feb.nc'.
    • >> ncRef = 'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
    • Call mDataset class contructor.
    • >> ncObj =  mDataset(ncRef) 
      ncObj = 
                    URI:  'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
               numGrids: 19
          numDimensions: 12
           numVariables: 80
    • Set variable 'var = temp'. Apply subscripted referencing as shown below to get a subset of variable data and grid.
    • >> var='temp';
      >> varData = ncObj{var}(1,2:2:20,1:59,4:end).data;
      >> whos varData
        Name          Size                 Bytes  Class     Attributes
        varData      10x59x157            370520  single             
      
      >> varGrid = ncObj{var}(1,2:2:20,1:59,4:end).grid 
      >> varGrid
      varGrid = 
      
           lat: [59x157 double]
           lon: [59x157 double]
             z: [10x59x157 double]
          time: 7.3162e+005      
      
    • In order to read the entire dataset and grid information, use the syntax shown below.
    • >> varData = ncObj{var}(:).data;
      >> whos varData
        Name         Size              Bytes  Class     Attributes
        varData      4-D             6144000  single               
      
      >> varGrid = ncObj{var}(:).grid;
      >> varGrid
      varGrid = 
      
           lat: [60x160 double]
           lon: [60x160 double]
             z: [4-D double]
          time: [7.3162e+005 7.3162e+005 7.3163e+005 7.3163e+005 7.3163e+005 7.3163e+005 7.3163e+005 7.3163e+005]  
      

  • Retrieve specific global and variable attribute value using matlab subscripted referencing. 
    • Specify data location. The data location can be local or remote (e.g http, thredds, dods). Note: If working offline, then set 'ncRef' to use file 'examples/data/bora_feb.nc'.
    • >> ncRef = 'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
    • Call mDataset class contructor.
    • >> ncObj =  mDataset(ncRef) 
      ncObj = 
                    URI:  'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
               numGrids: 19
          numDimensions: 12
           numVariables: 80
    • Retrieve value for global attribute 'title'.
    • >> globalAttr = ncObj.title
      globalAttr =
      ROMS/TOMS 2.2 - Adria02 Uber Run
      
    • Specify var='temp'. Retrieve variable attribute 'long_name'.
    • >> var = temp;
      >> varAttr = ncObj{var}.long_name
      varAttr =
      averaged potential temperature
      
    • One can also retrieve variable attribute value from 'mVar' object. See scenario-3 to create mVar object i.e. varObj.
    • >> varAttr = varObj.long_name
      varAttr =
      averaged potential temperature
      

  • Subset a grid variable based on start, count and stride specifications. 
    • Specify data location. The data location can be local or remote (e.g http, thredds, dods). Note: If working offline, then set 'ncRef' to use file 'examples/data/bora_feb.nc'.
    • >> ncRef = 'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
    • Call mDataset class contructor to create mDataset object.
    • >> ncObj =  mDataset(ncRef) 
      ncObj = 
                    URI:  'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
               numGrids: 19
          numDimensions: 12
           numVariables: 80
    • Set variable 'var = temp'. Call mDataset method 'getGeoGridVar' to create a grid variable object 'mGeoGridVar'.
    • >> var = 'temp';
      >> gVarObj = getGeoGridVar(ncObj, var) 
      gVarObj = 
            Variable: 'temp'
          Dimensions: '[   ocean_time = UNLIMITED;   // (8 currently),    s_rho = 20;,    eta_rho = 60;,    xi_rho = 160;]'
    • Call method 'subsetGeoGridVar'.
    • >> subGrid = subsetGeoGridVar(gVarObj, [1 1 1 1],[1 1 20 inf],[1 1 2 1]);
      >> whos subGrid
        Name         Size            Bytes  Class          Attributes
        subGrid      1x1               660  mGeoGridVar              
      
      >> varData = getData(subGrid);
      >> whos varData
        Name          Size             Bytes  Class     Attributes
        varData      10x160             6400  single              
      
      >> varGrid = getGrid(subGrid)
      varGrid = 
           lat: [10x160 double]
           lon: [10x160 double]
             z: [10x160 double]
          time: 7.3162e+005
      
    • You can also use subscripted referencing to subset a grid and get data.
    • >> subGrid = gVarObj(1:3,1:3,2:10,2:2:end);    %shape[8 20 60 160]
      >> whos subGrid
        Name         Size            Bytes  Class          Attributes
        subGrid      1x1               660  mGeoGridVar              
      
      >> varData = getData(subGrid);
      or
      >> varData = subGrid.data;
      >> whos varData
        Name         Size            Bytes  Class     Attributes
        varData      4-D             25920  single
                      
      
      >> varGrid = getGrid(subGrid)
      or
      >> varGrid = subGrid.grid
      varGrid =
           lat: [9x80 double]
           lon: [9x80 double]
             z: [4-D double]
          time: [7.3162e+005 7.3162e+005 7.3163e+005]
      

  • Extract time values for a variable in matlab datenum format. 
    • Specify data location. The data location can be local or remote (e.g http, thredds, dods). Note: If working offline, then set 'ncRef' to use file 'examples/data/bora_feb.nc'.
    • >> ncRef = 'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
    • Call mDataset class contructor to create mDataset object.
    • >> ncObj =  mDataset(ncRef) 
      ncObj = 
                    URI:  'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
               numGrids: 19
          numDimensions: 12
           numVariables: 80
    • Set variable 'var = temp'. Call mDataset method 'getVar' or use subscripted reference to create a variable object 'mVar'.
    • >> var = 'temp';
      >> varObj = getVar(ncObj, var) 
      or
      >> varObj = ncObj{var}
      
      varObj = 
         float temp(ocean_time=8, s_rho=20, eta_rho=60, xi_rho=160);
           :long_name = "averaged potential temperature";
           :units = "Celsius";
           :time = "ocean_time";
           :coordinates = "lat_rho lon_rho";
           :field = "temperature, scalar, series";
    • Call method 'getTimes'.
    • >> times = getTimes(varObj);
      >> whos times
        Name       Size            Bytes  Class     Attributes
        times      1x8                64  double              
      
      >> times
      times =
        1.0e+005 *
          7.3162    7.3162    7.3163    7.3163    7.3163    7.3163    7.3163    7.3163
      
    • You can also get time values from a grid variable object. Follow scenario-2 to create mGeoGridVar object i.e. gVarObj.
    • Call method 'getGrid'.
    • >> varGrid = getGrid(gVarObj);
      >> varGrid
      varGrid =
           lat: [60x160 double]
           lon: [60x160 double]
             z: [4-D double]
          time: [7.3162e+005 7.3162e+005 7.3163e+005 7.3163e+005 7.3163e+005 7.3163e+005 7.3163e+005 7.3163e+005]
      
      >> times = varGrid.time
      times =
        1.0e+005 *
          7.3162    7.3162    7.3163    7.3163    7.3163    7.3163    7.3163    7.3163
      
      See functions nj_time   nj_grid_varget

  • Get global and variable attributes. 
    • Specify data location. The data location can be local or remote (e.g http, thredds, dods). Note: If working offline, then set 'ncRef' to use file 'examples/data/bora_feb.nc'.
    • >> ncRef = 'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
    • Set variable 'var = temp'. Call nj_attget function to retrieve attributes.
    • >> var = 'temp';
      >> attr = nj_attget(ncRef,'global','title')  % global attribute
      attr =
      ROMS/TOMS 2.2 - Adria02 Uber Run
      
      >> attr = nj_attget(ncRef,var,'long_name') %variable attribute
      attr =
      averaged potential temperature
    • The parameter 'ncRef' can also be an 'mDataset' object.

  • Get time values for a variable from any CF-compliant file. 
    • Specify data location. The data location can be local or remote (e.g http, thredds, dods). Note: If working offline, then set 'ncRef' to use file 'examples/data/bora_feb.nc'.
    • >> ncRef = 'http://coast-enviro.er.usgs.gov/cgi-bin/nph-dods/models/test/bora_feb.nc'
    • Set variable 'var = temp'. Call function 'nj_time'.
    • >> var = 'temp';
      >> [times] = nj_time(ncRef,var) % all times
      times =
        1.0e+005 *
          7.3162    7.3162    7.3163    7.3163    7.3163    7.3163    7.3163    7.3163
      
      >> [times] = nj_time(ncRef,var,3) % 3rd time step
      times =
        7.3163e+005
    • The parameter 'ncRef' can also be an 'mDataset' object.

previous Quick Tutorial
NJ Functions Next
© 2006-2009   Mississippi State University   • License Terms   • Credits