PyOPIA 2.4.0__tar.gz → 2.4.2__tar.gz

{pyopia-2.4.0 → pyopia-2.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PyOPIA
-Version: 2.4.0
+Version: 2.4.2
 Summary: A Python Ocean Particle Image Analysis toolbox.
 Home-page: https://github.com/sintef/pyopia
 Keywords: Ocean,Particles,Imaging,Measurement,Size distribution

pyopia-2.4.2/pyopia/__init__.py

@@ -0,0 +1 @@
+__version__ = '2.4.2'

{pyopia-2.4.0 → pyopia-2.4.2}/pyopia/background.py

@@ -8,13 +8,19 @@ def ini_background(bgfiles, load_function):
     '''
     Create and initial background stack and average image
 
-    Args:
-        bgfiles (list)                   : list of strings of filenames to be used in background creation
-        load_function (function object)  : this function should take a filename and return an image,
-                                           for example: :func:`pyopia.instrument.silcam.load_image`
-    Returns:
-        bgstack (list)              : list of all images in the background stack
-        imbg (array)                : background image
+    Parameters:
+    -----------
+    bgfiles : list
+        List of strings of filenames to be used in background creation
+    load_function : object
+        This function should take a filename and return an image, for example: :func:`pyopia.instrument.silcam.load_image`
+
+    Returns
+    -------
+    bgstack : list
+        list of all images in the background stack
+    imbg : array
+        background image
     '''
     bgstack = []
     for f in bgfiles:
@@ -33,14 +39,21 @@ def shift_bgstack_accurate(bgstack, imbg, imnew):
     The new background is calculated slowly by computing the mean of all images
     in the background stack.
 
-    Args:
-        bgstack (list)      : list of all images in the background stack
-        imbg (uint8)        : background image
-        imnew (unit8)       : new image to be added to stack
-
-    Returns:
-        bgstack (updated list of all background images)
-        imbg (updated actual background image)
+    Parameters:
+    -----------
+    bgstack : list
+        list of all images in the background stack
+    imbg : array
+        background image
+    imnew : array
+        new image to be added to stack
+
+    Returns
+    -------
+    bgstack : list
+        updated list of all background images
+    imbg : array
+        updated actual background image
     '''
     bgstack.pop(0)  # pop the oldest image from the stack,
     bgstack.append(imnew)  # append the new image to the stack
@@ -56,14 +69,21 @@ def shift_bgstack_fast(bgstack, imbg, imnew):
     adding the new image (both scaled by the stacklength).
     This is close to a running mean, but not quite.
 
-    Args:
-        bgstack (list)      : list of all images in the background stack
-        imbg (uint8)        : background image
-        imnew (unit8)       : new image to be added to stack
-
-    Returns:
-        bgstack (updated list of all background images)
-        imbg (updated actual background image)
+    Parameters:
+    -----------
+    bgstac : list
+        list of all images in the background stack
+    imbg : uint8
+        background image
+    imnew : unit8
+        new image to be added to stack
+
+    Returns
+    -------
+    bgstack : list
+        updated list of all background images
+    imbg : array
+        updated actual background image
     '''
     stacklength = len(bgstack)
     imold = bgstack.pop(0)  # pop the oldest image from the stack,
@@ -82,14 +102,17 @@ def correct_im_accurate(imbg, imraw):
     There is a small chance of clipping of imc in both crushed blacks and blown
     highlights if the background or raw images are very poorly obtained
 
-    Args:
-      imbg (float64)  : background averaged image
-      imraw (float64) : raw image
-      imbg (float64)  : background averaged image
-      imraw (float64) : raw image
-
-    Returns:
-      im_corrected (float64)   : corrected image, same type as input
+    Parameters:
+    -----------
+    imbg : float64
+        background averaged image
+    imraw : float64
+        raw image
+
+    Returns
+    -------
+    im_corrected : float64
+        corrected image, same type as input
     '''
 
     im_corrected = imraw - imbg
@@ -108,12 +131,17 @@ def correct_im_fast(imbg, imraw):
     There is high potential for clipping of imc in both crushed blacks an blown
     highlights, especially if the background or raw images are not properly obtained
 
-    Args:
-      imraw (float64) : raw image
-      imbg (float64)  : background averaged image
-
-    Returns:
-      im_corrected (float64)   : corrected image
+    Parameters:
+    -----------
+    imraw : array
+        raw image
+    imbg : array
+        background averaged image
+
+    Returns
+    -------
+    im_corrected : array
+        corrected image
     '''
     im_corrected = imraw - imbg
 
@@ -130,18 +158,27 @@ def shift_and_correct(bgstack, imbg, imraw, stacklength, real_time_stats=False):
 
     This is a wrapper for shift_bgstack and correct_im
 
-    Args:
-        bgstack (list)                  : list of all images in the background stack
-        imbg (float64)                  : background image
-        imraw (float64)                 : raw image
-        stacklength (int)               : unsed int here - just there to maintain the same behaviour as
-                                          shift_bgstack_fast()
-        real_time_stats=False (Bool)    : if True use fast functions, if False use accurate functions
-
-    Returns:
-        bgstack (list)                  : list of all images in the background stack
-        imbg (float64)                  : background averaged image
-        im_corrected (float64)          : corrected image
+    Parameters:
+    -----------
+    bgstack : list
+        list of all images in the background stack
+    imbg : float64
+        background image
+    imraw : float64
+        raw image
+    stacklength : int
+        unused int here - just there to maintain the same behaviour as shift_bgstack_fast()
+    real_time_stats : Bool, optional
+        True use fast functions, if False use accurate functions., by default False
+
+    Returns
+    -------
+    bgstack : list
+        list of all images in the background stack
+    imbg : float64
+        background averaged image
+    im_corrected : float64
+        corrected image
     '''
 
     if real_time_stats:

{pyopia-2.4.0 → pyopia-2.4.2}/pyopia/io.py

@@ -32,18 +32,24 @@ def write_stats(stats,
     Writes particle stats into the ouput file.
     Appends if file already exists.
 
-    Args:
-        datafilename (str)                      :   Filame prefix for -STATS.h5 file that may or may not include a path
-        stats (DataFrame or xr.Dataset)         :   STATS dataframe
-        export_name_len (int)                   :   Max number of chars allowed for col 'export name'
-        append (bool)                           :   Append all processed data into one nc file.
-                                                    Defaults to True.
-                                                    If False, then one nc file will be generated per raw image,
-                                                    which can be loaded using :func:`pyopia.io.combine_stats_netcdf_files`
-                                                    This is useful for larger datasets,
-                                                    where appending causes substantial slowdown
-                                                    as the dataset gets larger.
-        image_stats (xr.Dataset)                :   image_stats data
+    Parameters
+    ----------
+    datafilename : str
+        Filame prefix for -STATS.h5 file that may or may not include a path
+    stats : DataFrame or xr.Dataset
+        particle statistics
+    export_name_len : int
+        Max number of chars allowed for col 'export name'
+    append : bool
+        Append all processed data into one nc file.
+        Defaults to True.
+        If False, then one nc file will be generated per raw image,
+        which can be loaded using :func:`pyopia.io.combine_stats_netcdf_files`
+        This is useful for larger datasets,
+        where appending causes substantial slowdown
+        as the dataset gets larger.
+    image_stats : xr.Dataset
+        summary statistics of each raw image (including those with no particles)
     '''
 
     if len(stats) == 0:  # to avoid issue with wrong time datatypes in xarray
@@ -99,7 +105,7 @@ def make_xstats(stats, toml_steps):
 
     Returns
     -------
-    xarray.DataSet
+    xstats : xarray.Dataset
         Xarray version of stats dataframe, including metadata
     '''
     xstats = stats.to_xarray()
@@ -120,8 +126,8 @@ def load_image_stats(datafilename):
 
     Returns
     -------
-    xarray.DataArray
-        image_stats
+    image_stats : xarray.Dataset
+        summary statistics of each raw image (including those with no particles)
     '''
     with xarray.open_dataset(datafilename, engine=NETCDF_ENGINE, group='image_stats') as image_stats:
         image_stats.load()
@@ -138,7 +144,7 @@ def load_stats(datafilename):
 
     Returns
     -------
-    DataFrame
+    stats : DataFrame
         STATS DataFrame  / xarray dataset
     '''
 
@@ -170,8 +176,10 @@ def combine_stats_netcdf_files(path_to_data, prefix='*'):
 
     Returns
     -------
-    tuple
-        xstats STATS xarray dataset, image_stats dataset
+    xstats : xarray.Dataset
+        Particle statistics and metatdata from processing steps
+    image_stats : xarray.Dataset
+        summary statistics of each raw image (including those with no particles)
     '''
 
     sorted_filelist = sorted(glob(os.path.join(path_to_data, prefix + 'Image-D*-STATS.nc')))
@@ -234,7 +242,7 @@ def steps_from_xstats(xstats):
 
     Returns
     -------
-    dict
+    steps : dict
         TOML-formatted dictionary of pipeline steps
     '''
     steps = toml.loads(xstats.__getattr__('steps'))
@@ -251,7 +259,7 @@ def load_stats_as_dataframe(stats_file):
 
     Returns
     -------
-    DataFrame
+    stats : DataFrame
         stats pandas dataframe
     '''
     # obtain particle statistics from the stats file
@@ -269,8 +277,10 @@ def show_h5_meta(h5file):
     '''
     prints metadata from an exported hdf5 file created from pyopia.process
 
-    Args:
-        h5file              : h5 filename from exported data from pyopia.process
+    Parameters
+    ----------
+    h5file : str
+        h5 filename from exported data from pyopia.process
     '''
 
     with h5py.File(h5file, 'r') as f:
@@ -286,20 +296,26 @@ class StatsToDisc():
 
     Replaces the old StatsH5 class
 
-    Args:
-        output_datafile (str): prefix path for output nc file
-        dataformat (str): either 'nc' or 'h5
-        append (bool): if to allow append to an existing STATS file. Defaults to True
-        export_name_len (int): max number of chars allowed for col 'export name'. Defaults to 40
-        append (bool):          Append all processed data into one nc file.
-                                Defaults to True.
-                                If False, then one nc file will be generated per raw image,
-                                which can be loaded using :func:`pyopia.io.combine_stats_netcdf_files`
-                                This is useful for larger datasets, where appending causes substantial slowdown
-                                as the dataset gets larger.
-
-    Returns:
-        data (dict): data from pipeline
+    Parameters
+    ----------
+    output_datafile : str
+        prefix path for output nc file
+    dataformat : str
+        either 'nc' or 'h5
+    export_name_len : int
+        max number of chars allowed for col 'export name'. Defaults to 40
+    append : bool
+        Append all processed data into one nc file.
+        Defaults to True.
+        If False, then one nc file will be generated per raw image,
+        which can be loaded using :func:`pyopia.io.combine_stats_netcdf_files`
+        This is useful for larger datasets, where appending causes substantial slowdown
+        as the dataset gets larger.
+
+    Returns
+    -------
+    data : dict
+        data from pipeline
 
     Example config for pipeline useage:
 

{pyopia-2.4.0 → pyopia-2.4.2}/pyopia/pipeline.py

@@ -84,11 +84,15 @@ class Pipeline():
     def run(self, filename):
         '''Method for executing the processing pipeline.
 
-        Args:
-            filename (str): file to be processed
+        Parameters
+        ----------
+        filename : str
+            file to be processed
 
-        Returns:
-            stats (DataFrame): stats DataFrame of particle statistics associated with 'filename'
+        Returns
+        -------
+        stats : DataFrame
+            particle statistics associated with 'filename'
 
         Note: the returned stats from this function are single-image only and not appended
         if you loop through several filenames! It is recommended to use this step in the pipeline
@@ -259,11 +263,15 @@ class Data(TypedDict):
 def steps_to_string(steps):
     '''Deprecated. Convert pipeline steps dictionary to a human-readable string
 
-    Args:
-        steps (dict): pipeline steps dictionary
+    Parameters
+    ----------
+    steps : dict
+        pipeline steps dictionary
 
-    Returns:
-        str: human-readable string of the types and variables
+    Returns
+    -------
+    steps_str : str
+        human-readable string of the types and variables
     '''
 
     steps_str = '\n'

{pyopia-2.4.0 → pyopia-2.4.2}/pyopia/plotting.py

@@ -9,12 +9,14 @@ import numpy as np
 
 
 def show_image(image, pixel_size):
-    '''
-    Plots a scaled figure (in mm) of an image
-
-    Args:
-        image (float) : Image (usually a corrected image, such as im_corrected)
-        pixel_size (float) : the pixel size (um) of the imaging system used
+    '''Plots a scaled figure (in mm) of an image
+
+    Parameters
+    ----------
+    image : float
+        Image (usually a corrected image, such as im_corrected)
+    pixel_size : float
+        the pixel size (um) of the imaging system used
     '''
     r, c = np.shape(image[:, :, 0])
 
@@ -31,10 +33,12 @@ def montage_plot(montage, pixel_size):
     '''
     Plots a SilCam particle montage with a 1mm scale reference
 
-    Args:
-        montage (uint8)    : a SilCam montage created with scpp.make_montage
-        pixel_size (float) : the pixel size of the SilCam used, obtained from settings.PostProcess.pix_size in the
-                             config ini file
+    Parameters
+    ----------
+    montage : uint8
+        a montage created with scpp.make_montage
+    pixel_size : float
+        the pixel size (um) of the imaging system used
     '''
     msize = np.shape(montage)[0]
     ex = pixel_size * np.float64(msize) / 1000.