Adding more documentation, and fixing resample

docs/source/index.rst

@@ -18,6 +18,6 @@ PyDIVIDE's Documentation
     plotting_l2
     manipulate_kp
     manipulate_model
-    miscellaneous
+    tplot
     insitu_kp
     iuvs_kp

docs/source/introduction.rst

@@ -2,7 +2,6 @@ Introduction
 ===================
 
 
-
 What is PyDIVIDE?
 ------------------
 

docs/source/manipulate_kp.rst

@@ -0,0 +1,13 @@
+Manipulating KP Data
+=====================
+
+Resample
+---------
+
+.. autofunction:: pydivide.resample
+
+
+Bin
+----
+
+.. autofunction:: pydivide.bin

docs/source/miscellaneous.rst

@@ -1,23 +1,5 @@
-Miscellaneous Functions
-========================
-
-This page will describe how to obtain and read in the data.  For reading/loading Level 2 files, PySPEDAS is currently required.  
-
-Download Data
----------------
-
-.. autofunction:: pydivide.download_files
-
-
-Read KP Data
---------------
-
-.. autofunction:: pytplot.read
-
-
-Read Model Results
---------------------
-
-.. autofunction:: pytplot.read_model_results
+Miscellaneous
+==============
 
 
+.. autofunction:: pydivide.cleanup_files

pydivide/bin.py

@@ -22,7 +22,43 @@ def bin(kp,
         density=False,
         median=False,
         unittest=False):
+    '''
+    Bins insitu Key Parameters by up to 8 different parameters, specified within
+    the data structure. Necessary that at least one of avg, std, median, or
+    density be specified.
 
+    Parameters:
+        kp: struct
+            KP insitu data structure read from file(s).
+        parameter: str
+            Key Parameter to be binned. Only one may be binned at a time.
+        bin_by: int, str
+            Parameters (index or name) by which to bin the specified Key Parameter.
+        binsize: int, list
+        Bin size for each binning dimension. Number of elements must be equal to those in bin_by.
+        mins: int, list
+            Minimum value(s) for each binning scheme. Number of elements must be equal to those in bin_by.
+        maxs: int, list 7
+            Maximum value(s) for each binning scheme. Number of elements must be equal to those in bin_by.
+        avg: bool
+            Calculate average per bin.
+        std: bool
+            Calculate standard deviation per bin.
+        density: bool
+            Returns number of items in each bin.
+        median: bool
+            Calculate median per bin.
+
+    Returns:
+        This procedures outputs up to 4 arrays to user-defined variables, corresponding to avg, std, median, and density.
+
+    Examples:
+    >>> # Bin STATIC O+ characteristic energy by spacecraft latitude (1° resolution) and longitude (2° resolution).
+    >>> output_avg = pydivide.bin(insitu, parameter='static.oplus_char_energy', bin_by=['spacecraft.geo_latitude', 'spacecraft.geo_longitude'], avg=True,binsize=[2,1])
+
+    >>> # Bin SWIA H+ density by spacecraft altitude (10km resolution), return average value and standard deviation for each bin.
+    >>> output_avg,output_std = pydivide.bin(insitu, parameter='swia.hplus_density', bin_by='spacecraft.altitude', binsize=10,avg=True,std=True)
+    '''
     # ERROR CHECKING
     if not isinstance(bin_by, list):
         bin_by = [bin_by]

pydivide/cleanup_files.py

@@ -14,13 +14,7 @@ def cleanup_files():
     """
     CLEANUP_FILES
     Searches code directory for .tab files, keeps latest versions/revisions, asks to delete old versions
-
     x = cleanup_files()
-
-    REQUIREMENTS
-    ***************
-    All .tab files must be named with the format "mvn_kp_insitu_YYYYMMDD_vXX_rXX.tab"
-    Any extraneous characters or formatting changes will break the regexing for this function.
     """
     # Pull directory path preferences from mvn_toolkit_prefs.txt
     dir_path = get_root_data_dir()

pydivide/resample.py

@@ -12,7 +12,28 @@
 
 
 def resample(kp, time, sc_only=False):
-
+    '''
+    Modifies KP structure index to user specified time via interpolation.
+
+    Parameters:
+        kp: struct
+            KP insitu data structure read from file(s).
+        time: list
+            Specifies subset of insitu KP data for resampling. time must be expressed in the format ‘YYYY-MM-DD HH:MM:SS’.
+
+    Examples:
+        >>> # Resample insitu time to 2016-06-20 coarse survey 3D file time.
+        >>> swi_cdf = cdflib.CDF('<dir_path>/mvn_swi_l2_coarsesvy3d_20160620_v01_r00.cdf')
+        >>> newtime = swi_cdf.varget('time_unix')
+        >>> insitu_resampled = pydivide.resample(insitu, newtime)
+
+        >>> # Resamples an entire day of data to just 3 points
+        >>> import pytplot
+        >>>insitu, iuvs = pydivide.read(input_time=['2016-02-18', '2016-02-19'])
+        >>> x = pydivide.resample(insitu, [pytplot.tplot_utilities.str_to_int('2016-02-18T05:00:00'),
+        >>>                      pytplot.tplot_utilities.str_to_int('2016-02-18T10:00:00'),
+        >>>                      pytplot.tplot_utilities.str_to_int('2016-02-18T15:00:00')])
+    '''
     new_total = len(time)
     start_time = time[0]
     end_time = time[new_total - 1]
@@ -65,7 +86,7 @@ def resample(kp, time, sc_only=False):
     spacecraft = kp['SPACECRAFT']
     io_flag = kp['IOflag']
     orbit = kp['Orbit']
-    time = kp['TimeString']
+    time_orig = kp['TimeString']
     timeunix = kp['Time']
 
     # Set up instrument list to make it easy to loop through the next parts
@@ -98,13 +119,13 @@ def resample(kp, time, sc_only=False):
     spline_function = interpolate.interp1d(old_time.values, orbit.values)
     # In order for the spline_function to work, need to make sure that we're working with the integer form of time,
     # in seconds since the epoch, not datetime times
-    if not isinstance(time.values[0], int):
-        time_int = [tplot.tplot_utilities.str_to_int(t) for t in time.values]
+    if not isinstance(time[0], int):
+        time_int = [tplot.tplot_utilities.str_to_int(t) for t in time]
         temp_series = pd.Series(spline_function(time_int))
-    elif isinstance(time.values[0], int):
-        if not isinstance(time.values, list):
-            time.values = list(time.values)
-        temp_series = pd.Series(spline_function(time.values))
+    elif isinstance(time[0], int):
+        if not isinstance(time, list):
+            time.values = list(time)
+        temp_series = pd.Series(spline_function(time))
 
     temp_df = temp_series.to_frame('Orbit')
     temp_df['Time Index'] = new_time_series

pydivide/tplot_varcreate.py

@@ -7,8 +7,26 @@
 
 
 def tplot_varcreate(insitu, instruments=None, observations=None):
-    """Creates tplot variables from the insitu variable
     """
+    Can turn an insitu object from the pydivide.read procedure into pytplot variables.
+
+    Parameters:
+        insitu: dict
+            The dictionary object that gets created from an insitu read procedure
+        instruments: str
+            Specific instruments to be loaded into pytplot
+        observations: str
+            Specific observations to be loaded into pytplot
+
+    Returns:
+        A string list of the created tplot variables
+
+    Examples:
+        >>> # Load MAG and NGIMS data into PyTplot
+        >>> tvars = pydivide.tplot_varcreate(insitu, instruments=['MAG', 'NGIMS'])
+
+    """
+
     # initialize each instrument
 
     for obs in insitu["SPACECRAFT"]: