update the changelog, add some (minimal) tutorial examples

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to this project will be documented in this file.
 ## [Unreleased]
 
 ### Added
+- A new HDF5 file format for calibration solutions called `calh5`, which supports
+writing out all types of UVCal objects and supports partial reads (select on read).
 - A `UVCal.get_time_array` method that either returns the mean of the start and stop
 time for each time range or the time_array (if there's a time_array and no time_range).
 - A new `freq_interp_kind` parameter to `UVBeam.interp`, `UVBeam._interp_az_za_rect_spline`

docs/uvcal_tutorial.rst

@@ -97,8 +97,8 @@ UVCal: Reading/writing
 ----------------------
 Calibration files using UVCal.
 
-a) Reading a cal fits gain calibration file.
-********************************************
+a) Reading a CalFITS gain calibration file.
+*******************************************
 .. code-block:: python
 
   >>> import os
@@ -147,8 +147,8 @@ a) Reading a cal fits gain calibration file.
 .. image:: Images/abs_gains.png
     :width: 600
 
-b) FHD cal to cal fits
-***********************
+b) FHD cal to CalFITS
+*********************
 .. code-block:: python
 
   >>> import os
@@ -180,6 +180,21 @@ b) FHD cal to cal fits
   >>> fhd_cal.write_calfits(os.path.join('.', 'tutorial_cal.fits'), clobber=True)
 
 
+b) CalFITS to CalH5
+*******************
+.. code-block:: python
+
+  >>> import os
+  >>> from pyuvdata import UVCal
+  >>> from pyuvdata.data import DATA_PATH
+  >>> filename = os.path.join(DATA_PATH, 'zen.2457698.40355.xx.gain.calfits')
+  >>> # Here we use the ``from_file`` class method, can also use the ``read`` method.
+  >>> # Can optionally specify the ``file_type`` to either method
+  >>> cal = UVCal.from_file(filename, use_future_array_shapes=True)
+
+  >>> cal.write_calh5(os.path.join('.', 'tutorial_cal.calh5'), clobber=True)
+
+
 UVCal: Initializing from a UVData object
 ----------------------------------------
 The :meth:`pyuvdata.UVCal.initialize_from_uvdata` method allows you to initialize a UVCal