.. Quick

Quick Start
-----------

This section provides a quick overview of how to work with PseudoNetCDF. Each
quick example is cumulative. If you don't understand something, look at the 
previous sections.

Import PseudoNetCDF
~~~~~~~~~~~~~~~~~~~

First, PseudoNetCDF should be imported as `pnc` for brevity.

.. code-block:: python

  import PseudoNetCDF as pnc

Open a File
~~~~~~~~~~~

:func:`~PseudoNetCDF.pncopen` helps PseudoNetCDF open many types of files, but
is most well tested with Air Quality related files including models (e.g.,
CAMx, CMAQ, GEOS-Chem) and observations (e.g., woudc sondes, AQS, aircraft
icartt). These examples are from publicly available data.

.. code-block:: python

  # from CAMx Test Case v6
  camxpath1 = 'CAMx.v6.40.midwest.36.12.noMPI.20020603.avrg.grd02'
  camxf = pnc.pncopen(camxpath1, format='uamiv')

.. code-block:: python

  # from CMAQ Test Case v5.2
  cmaqpath1 = 'CCTM_ACONC_v52_cb6r3_intel17.0_SE52BENCH_20110701.nc'
  cmaqf = pnc.pncopen(cmaqpath1, format='ioapi')

.. code-block:: python

  # from the GEOS-Chem benchmark v12
  gcpath1 = 'ctm.bpch'
  gcf = pnc.pncopen(gcpath1, format='bpch')

.. code-block:: python

  # from the INTEX-NA NASA campaign
  ictpath = 'HOX_DC8_20040626_R0.ict'
  ictf = pnc.pncopen(ictpath, format='ffi1001')

.. code-block:: python

  # from the woudc.org
  woudcpath = 'bu20170609.b18.csv'
  wdcf = pnc.pncopen(woudcpath, format='woudcsonde')

Don't know the format of your file... leave out the format keyword and
PseudoNetCDF will try to figure it out for you.

Get Help
~~~~~~~~

Most objects have are documented, so use help if you want to know more. For
example, if you wanted to learn more about opening a file
:func:`pnc.pncopen`, use :func:help

.. code-block:: python

  help(pnc.pncopen)

Subset on Dimension
~~~~~~~~~~~~~~~~~~~

:func:`~PseudoNetCDF.PseudoNetCDFFile.sliceDimensions` is one of the most basic jobs of PNC. The sliceDimensions method will
extract just the selected elements on one or more dimensions (e.g., LAY). This
method works with `slice` objects, integers, and arrays.

.. code-block:: python

  lay1f = camxf.sliceDimensions(LAY=0)  

Apply Function on a Dimension
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:func:`~PseudoNetCDF.PseudoNetCDFFile.applyAlongDimensions` applies functions
on dimensions and is the second most basic jobs of PNC. Functions can be numpy
array method names (e.g., 'mean', 'std', 'sum') or any function.

.. code-block:: python

  timeavgf = camxf.applyAlongDimensions(TSTEP='mean')  


Make a plot
~~~~~~~~~~~

The :func:`~PseudoNetCDF.PseudoNetCDFFile.plot` interface tries to make some
simple plotting easy. It also allows keyword configuration and object-based
interaction with the created plot by returning the axes that was plotted on.

.. code-block:: python

  ax = lay1f.plot('O3')
  ax.figure.savefig('O3.png')

Derive Variables
~~~~~~~~~~~~~~~~

The :func:`~PseudoNetCDF.PseudoNetCDFFile.eval` is very like `pandas.DataFrame.eval`. It requires the non-derived
variables to be in the file or calculated earlier in a multi-line script.

.. code-block:: python

  noxf = lay1f.eval('NOx = NO + NO2')

Stack Files on Dimensions
~~~~~~~~~~~~~~~~~~~~~~~~~

The :func:`~PseudoNetCDF.PseudoNetCDFFile.stack` method allows files to be
concatenated on a dimension. All other dimensions must be of the same length.

.. code-block:: python

  camxpath1 = 'CAMx.v6.40.midwest.36.12.noMPI.20020603.avrg.grd02'
  camxpath2 = 'CAMx.v6.40.midwest.36.12.noMPI.20020604.avrg.grd02'
  camx1f = pnc.pncopen(camxpath1, format='uamiv')
  camx2f = pnc.pncopen(camxpath2, format='uamiv')
  camxf = camx1f.stack(camx2f, 'TSTEP')

Extract Coordinates
~~~~~~~~~~~~~~~~~~~

The :func:`~PseudoNetCDF.PseudoNetCDFFile.ll2ij` converts longitude and
latitude to indices (0-based) and the 
:func:`~PseudoNetCDF.PseudoNetCDFFile.time2t` function converts datetime
objects to time indices (0-based). This makes it easy to extract time and space
elements from a file. Currently, there is not a comparable vertical method.

.. code-block:: python

  from datetime import datetime
  
  obslon = [-100, -90]
  obslat = [30, 40]
  obsdatstrs = [
    datetime(2002, 6, 3, 8, tzinfo=timezone.utc),
    datetime(2002, 6, 3, 9, tzinfo=timezone.utc),
  ]
  
  i, j = camxf.ll2ij(obslon, obslat)
  k = i * 0
  t = camxf.time2t(obstimes)
  
  atobsf = camxf.sliceDimensions(TSTEP=t, LAY=k, ROW=j, COL=i)


Copy a File to Memory
~~~~~~~~~~~~~~~~~~~~~

Finally, it is often nice to make an in-memory copy of a file. Sometimes it can
be as a template or other times it helps methods work more efficiently.

.. code-block:: python

  inmemf = camxf.copy()