.. highlightlang:: us

.. index:: nc_to_obj

.. _nc_to_obj:

nc_to_obj
=========

.. us.tag nc_to_obj NOTREADYENGLISH nc.tools New5147 Changed5506

:ref:`nc_to_obj` reads a netCDF file or a selection of channels of a netCDF file 
into a UniScript object.

.. function:: obj = nc_to_obj(ssFilename)
              obj = nc_to_obj(ncid)
              obj = nc_to_obj(ssFilename, svChannelNames)
              obj = nc_to_obj(ncid, svChannelNames)

.. us.return

**Return Value**

*obj* is an object containing the channels and three other objects: ``globals``,
``channel_info`` and ``order``. ``globals`` contains the global attributes of the
netCDF file, ``channel_info`` contains the channel attributes for each channel
and ``order`` contains the channel order of the netCDF file.

In case of an error, the function returns the value 0.

.. us.params

**Parameters**

.. uparam:: ssFilename

   *ssFilename* is the netCDF file name or any other data file. Other files
   will be converted to netCDF if possible.

.. uparam:: ncid

   *ncid* is the id of a UniPlot data file (see :ref:`nc_open` or 
   :ref:`nc_create`). Use :ref:`nc_close` to close the file. Instead of
   *ncid* the file name *ssFilename* can be used.

.. uparam:: svChannelNames

   *svChannelNames* is a string vector with channel names (optional). If set to
   0, a selection dialog box will be displayed.

.. us.example

**Example**

::

   * ssFile = GetRootDirectory() + "samples/test1.xls"; 
   * o = nc_to_obj(ssFile, ["EWGFAK", "Alpha"])
   * o
   [.
       Alpha = matrix 17 x 1 [88.7, 81.78, 82.76, 88.35, 88.7, ...]
       EWGFAK = matrix 17 x 1 [0.85, 0.86, 0.86, 0.87, 0.87, ...]
       channel_info = [.
           Alpha = [.
               C_format = "%.2lf"
               add_offset = 0
               datatype = "real4"
               long_name = "Alpha [-]"
               scale_factor = 1
               title = "Alpha"
               units = "-"
           ]
           EWGFAK = [.
               C_format = "%.2lf"
               add_offset = 0
               datatype = "real4"
               long_name = "EWGFAK [GRAD]"
               scale_factor = 1
               title = "EWGFAK"
               units = "GRAD"
           ]
       ]
       globals = [.
           Creator = "UniPlot Excel Converter v3"
           Origin = "d:\\uniplot_du\\samples/test1.xls"
           Source = "FEV Software and Testing Solutions GmbH (www.uniplot.de)"
           __XSort__ = 0
           columnseparator = "\\t"
           firstdatarow = 3
           missing_value = 1e+10
       ]
       order = [.
           [1] = "EWGFAK"
           [2] = "Alpha"
       ]
   ]
   object (obj at 0x3400C14)

**Example 2**

Calculates the mean value of all selected NC files.
The result is an NC file with mean channels.
All channels must have the same number of data points.
Only channel are calculated which are in the first 
data file.

::

   RegisterCommand("NC File", "NC_CalculateMean", "NC-Mean...");
   UserBar_Add("NC_CalculateMean");

   def NC_CalculateMean()
   {
      ssDir = "";
      bMultiselect = TRUE;
      bSortByDate = TRUE;
      bConvertToNC = TRUE;
      svFiles = GetOpenFileName_Data(ssDir, bMultiselect, bSortByDate, bConvertToNC)
      if (svFiles[1] == "") {
         return;
      }
      nFiles = len(svFiles);
   
      if (nFiles == 1) {
         return svFiles[1];
      }
      obj1 = nc_to_obj(svFiles[1]);
      svChannel = obj1.channel_info.keys("");
      obj1.globals.File1 = svFiles[1];
      for (i in 2:nFiles) {
         objn = nc_to_obj(svFiles[i]);
         for (ssChan in svChannel) {
            if (objn.has_key(ssChan)) {
               if (len(obj1[ssChan]) == len(objn[ssChan])) {
                  obj1[ssChan] = obj1[ssChan] + objn[ssChan];
                  obj1.channel_info[ssChan].nNC = obj1.channel_info[ssChan].nNC + 1;
               } else {
                  log_error("", "NC_CalculateMean", "Channel %s in file %s has different number of points", ssChan, svFiles[i]);
               }
            } else {
               log_error("", "NC_CalculateMean", "Channel %s in file %s not found", ssChan, svFiles[i]);
            }
         }
         obj1.globals[sprintf("File%d", i)] = svFiles[i];
      }
      for (ssChan in svChannel) {
         obj1.channel_info[ssChan].nNC = obj1.channel_info[ssChan].nNC + 1;
         n = obj1.channel_info[ssChan].nNC;
         if (n > 0) {
            obj1[ssChan] = obj1[ssChan] / n;
         }
      }
   
      svPath = SplitPath(svFiles[1]);
      ssNewFile =  sum(svPath[1:3]) + "_Mean.nc2"
      bRet = nc_from_obj(obj1, ssNewFile);
      log_info("", ssNewFile, "NC-Mean Result. Double Click to open");
      return;
   }

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - R2013.6
     - Description of parameter *ncid*.
   * - 5.14.7
     - New.

.. seealso::
   :ref:`overview-netcdf-files`,
   :ref:`nc_from_obj`,
   :ref:`NC_Edit`,
   :ref:`NC_GetVarNames`

:sub:`id-464946`