cloudnetpy 1.56.1__py3-none-any.whl → 1.56.3__py3-none-any.whl

cloudnetpy/categorize/atmos.py

@@ -27,16 +27,13 @@ def calc_lwc_change_rate(temperature: np.ndarray, pressure: np.ndarray) -> np.nd
     with height, given the cloud base temperature and pressure.
 
     Args:
-    ----
         temperature: Temperature of cloud base (K).
         pressure: Pressure of cloud base (Pa).
 
     Returns:
-    -------
         dlwc/dz (kg m-3 m-1)
 
     References:
-    ----------
         Brenguier, 1991, https://bit.ly/2QCSJtb
 
     """
@@ -59,12 +56,10 @@ def calc_mixing_ratio(svp: np.ndarray, pressure: np.ndarray) -> np.ndarray:
     """Calculates mixing ratio from saturation vapor pressure and pressure.
 
     Args:
-    ----
         svp: Saturation vapor pressure (Pa).
         pressure: Atmospheric pressure (Pa).
 
     Returns:
-    -------
         Mixing ratio (kg kg-1).
 
     """
@@ -79,13 +74,11 @@ def calc_air_density(
     """Calculates air density (kg m-3).
 
     Args:
-    ----
         pressure: Pressure (Pa).
         temperature: Temperature (K).
         svp_mixing_ratio: Saturation vapor pressure mixing ratio (kg/kg).
 
     Returns:
-    -------
         Air density (kg m-3).
 
     """
@@ -96,12 +89,10 @@ def get_attenuations(data: dict, classification: ClassificationResult) -> dict:
     """Calculates attenuations due to atmospheric gases and liquid water.
 
     Args:
-    ----
         data: Containing :class:`Model` and :class:`Mwr` instances.
         classification: A :class:`ClassificationResult` instance.
 
     Returns:
-    -------
         Dictionary containing `radar_gas_atten`, `radar_liquid_atten`,
             `liquid_atten_err`, `liquid_corrected` and `liquid_uncorrected` fields.
 
@@ -121,12 +112,10 @@ class Attenuation:
     """Base class for gas and liquid attenuations.
 
     Args:
-    ----
         model: The :class:`Model` instance.
         classification: The :class:`ClassificationResult` instance.
 
     Attributes:
-    ----------
         classification (ClassificationResult): The :class:`ClassificationResult`
         instance.
 
@@ -143,12 +132,10 @@ class GasAttenuation(Attenuation):
     """Radar gas attenuation class. Child of Attenuation.
 
     Args:
-    ----
         data: Containing :class:`Model` instance.
         classification: The :class:`ClassificationResult` instance.
 
     Attributes:
-    ----------
         atten (ndarray): Gas attenuation (dB).
 
     """
@@ -180,12 +167,10 @@ class LiquidAttenuation(Attenuation):
     """Radar liquid attenuation class. Child of Attenuation.
 
     Args:
-    ----
         data: Containing :class:`Model` and :class:`Mwr` instances.
         classification: The :class:`ClassificationResult` instance.
 
     Attributes:
-    ----------
         atten (ndarray): Radar liquid attenuation (dB).
         atten_err (ndarray): Error of radar liquid attenuation (dB).
         uncorrected (ndarray): Boolean array denoting uncorrected pixels.
@@ -255,12 +240,10 @@ def fill_clouds_with_lwc_dz(atmosphere: tuple, is_liquid: np.ndarray) -> np.ndar
     """Fills liquid clouds with lwc change rate at the cloud bases.
 
     Args:
-    ----
         atmosphere: 2-element tuple containing temperature (K) and pressure (Pa).
         is_liquid: Boolean array indicating presence of liquid clouds.
 
     Returns:
-    -------
         Liquid water content change rate (kg/m3/m), so that for each cloud the base
         value is filled for the whole cloud.
 
@@ -278,12 +261,10 @@ def get_lwc_change_rate_at_bases(
     """Finds LWC change rate in liquid cloud bases.
 
     Args:
-    ----
         atmosphere: 2-element tuple containing temperature (K) and pressure (Pa).
         is_liquid: Boolean array indicating presence of liquid clouds.
 
     Returns:
-    -------
         Liquid water content change rate at cloud bases (kg/m3/m).
 
     """
@@ -300,11 +281,9 @@ def find_cloud_bases(array: np.ndarray) -> np.ndarray:
     """Finds bases of clouds.
 
     Args:
-    ----
         array: 2D boolean array denoting clouds or some other similar field.
 
     Returns:
-    -------
         Boolean array indicating bases of the individual clouds.
 
     """
@@ -317,11 +296,9 @@ def find_cloud_tops(array: np.ndarray) -> np.ndarray:
     """Finds tops of clouds.
 
     Args:
-    ----
         array: 2D boolean array denoting clouds or some other similar field.
 
     Returns:
-    -------
         Boolean array indicating tops of the individual clouds.
 
     """
@@ -359,13 +336,11 @@ def calc_adiabatic_lwc(lwc_change_rate: np.ndarray, dheight: float) -> np.ndarra
     """Calculates adiabatic liquid water content (kg/m3).
 
     Args:
-    ----
         lwc_change_rate: Liquid water content change rate (kg/m3/m) calculated at the
             base of each cloud and filled to that cloud.
         dheight: Median difference of the height vector (m).
 
     Returns:
-    -------
         Liquid water content (kg/m3).
 
     """
@@ -382,12 +357,10 @@ def distribute_lwp_to_liquid_clouds(lwc: np.ndarray, lwp: np.ndarray) -> np.ndar
     theoretical proportion, i.e., sum(scaled LWC) = measured LWP.
 
     Args:
-    ----
         lwc: 2D liquid water content (kg/m3).
         lwp: 1D liquid water path (kg/m2).
 
     Returns:
-    -------
         2D LWP-weighted, normalized LWC (kg/m2).
 
     """

cloudnetpy/categorize/atmos_utils.py

@@ -17,15 +17,12 @@ def calc_wet_bulb_temperature(model_data: dict) -> np.ndarray:
     expansion of a simple expression for the saturated vapour pressure.
 
     Args:
-    ----
         model_data: Model variables `temperature`, `pressure`, `rh`.
 
     Returns:
-    -------
         Wet bulb temperature (K).
 
     References:
-    ----------
         J. Sullivan and L. D. Sanders: Method for obtaining wet-bulb
         temperatures by modifying the psychrometric formula.
 
@@ -66,11 +63,9 @@ def calc_saturation_vapor_pressure(temperature: np.ndarray) -> np.ndarray:
     """Goff-Gratch formula for saturation vapor pressure over water adopted by WMO.
 
     Args:
-    ----
         temperature: Temperature (K).
 
     Returns:
-    -------
         Saturation vapor pressure (Pa).
 
     """
@@ -95,11 +90,9 @@ def calc_psychrometric_constant(pressure: np.ndarray) -> np.ndarray:
     of water in air to the air temperature.
 
     Args:
-    ----
         pressure: Atmospheric pressure (Pa).
 
     Returns:
-    -------
         Psychrometric constant value (Pa K-1)
 
     """
@@ -110,15 +103,12 @@ def calc_dew_point_temperature(vapor_pressure: np.ndarray) -> np.ndarray:
     """Returns dew point temperature.
 
     Args:
-    ----
         vapor_pressure: Water vapor pressure (Pa).
 
     Returns:
-    -------
         Dew point temperature (K).
 
     Notes:
-    -----
         Method from Vaisala's white paper: "Humidity conversion formulas".
 
     """

cloudnetpy/categorize/categorize.py

@@ -20,10 +20,9 @@ def generate_categorize(
     and classified as different types of scatterers such as ice, liquid,
     insects, etc. Next, the radar signal is corrected for atmospheric
     attenuation, and error estimates are computed. Results are saved
-    in *ouput_file* which is a compressed netCDF4 file.
+    in *output_file* which is a compressed netCDF4 file.
 
     Args:
-    ----
         input_files: dict containing file names for calibrated `radar`, `lidar`,
             `model` and `mwr` files. Optionally also `lv0_files`, a list of
             RPG level 0 files.
@@ -31,15 +30,12 @@ def generate_categorize(
         uuid: Set specific UUID for the file.
 
     Returns:
-    -------
         UUID of the generated file.
 
     Raises:
-    ------
         RuntimeError: Failed to create the categorize file.
 
     Notes:
-    -----
         Separate mwr-file is not needed when using RPG cloud radar which
         measures liquid water path. Then, the radar file can be used as
         a mwr-file as well, i.e. {'mwr': 'radar.nc'}.
@@ -48,7 +44,6 @@ def generate_categorize(
         to detect liquid droplets.
 
     Examples:
-    --------
         >>> from cloudnetpy.categorize import generate_categorize
         >>> input_files = {'radar': 'radar.nc',
                            'lidar': 'lidar.nc',

cloudnetpy/categorize/classify.py

@@ -19,22 +19,18 @@ def classify_measurements(data: dict) -> ClassificationResult:
     time / height grid before calling this function.
 
     Args:
-    ----
         data: Containing :class:`Radar`, :class:`Lidar`, :class:`Model`
             and :class:`Mwr` instances.
 
     Returns:
-    -------
         A :class:`ClassificationResult` instance.
 
     References:
-    ----------
         The Cloudnet classification scheme is based on methodology proposed by
         Hogan R. and O'Connor E., 2004, https://bit.ly/2Yjz9DZ and its
         proprietary Matlab implementation.
 
     Notes:
-    -----
         Some individual classification methods are changed in this Python
         implementation compared to the original Cloudnet methodology.
         Especially methods classifying insects, melting layer and liquid droplets.
@@ -96,14 +92,12 @@ def fetch_quality(
     """Returns Cloudnet quality bits.
 
     Args:
-    ----
         data: Containing :class:`Radar` and :class:`Lidar` instances.
         classification: A :class:`ClassificationResult` instance.
         attenuations: Dictionary containing keys `liquid_corrected`,
             `liquid_uncorrected`.
 
     Returns:
-    -------
         Dictionary containing `quality_bits`, an integer array with the bits:
 
             - bit 0: Pixel contains radar data
@@ -136,13 +130,11 @@ def _find_aerosols(
     Aerosols are lidar signals that are: a) not falling, b) not liquid droplets.
 
     Args:
-    ----
         obs: A :class:`ClassData` instance.
         is_falling: 2-D boolean array of falling hydrometeors.
         is_liquid: 2-D boolean array of liquid droplets.
 
     Returns:
-    -------
         2-D boolean array containing aerosols.
 
     """
@@ -166,13 +158,11 @@ def _find_drizzle_and_falling(
     """Classifies pixels as falling, drizzle and others.
 
     Args:
-    ----
         is_liquid: 2D boolean array denoting liquid layers.
         is_falling: 2D boolean array denoting falling pixels.
         is_freezing: 2D boolean array denoting subzero temperatures.
 
     Returns:
-    -------
         2D array where values are 1 (falling, drizzle, supercooled liquids),
         2 (drizzle), and masked (all others).
 
@@ -191,12 +181,10 @@ def _bits_to_integer(bits: list) -> np.ndarray:
     """Creates array of integers from individual boolean arrays.
 
     Args:
-    ----
         bits: List of bit fields (of similar sizes) to be saved in the resulting
             array of integers. bits[0] is saved as bit 0, bits[1] as bit 1, etc.
 
     Returns:
-    -------
         Array of integers containing the information of the individual boolean arrays.
 
     """

cloudnetpy/categorize/containers.py

@@ -24,12 +24,10 @@ class ClassData:
     """Container for observations that are used in the classification.
 
     Args:
-    ----
         data: Containing :class:`Radar`, :class:`Lidar`, :class:`Model`
             and :class:`Mwr` instances.
 
     Attributes:
-    ----------
         z (ndarray): 2D radar echo.
         ldr (ndarray): 2D linear depolarization ratio.
         v (ndarray): 2D radar velocity.
@@ -84,13 +82,11 @@ def _find_rain_from_radar_echo(
     detections as raining.
 
     Args:
-    ----
         z: Radar echo.
         time: Time vector.
         time_buffer: Time in minutes.
 
     Returns:
-    -------
         1D Boolean array denoting profiles with rain.
 
     """
@@ -131,14 +127,12 @@ def _find_clutter(
     """Estimates clutter from doppler velocity.
 
     Args:
-    ----
         n_gates: Number of range gates from the ground where clutter is expected
             to be found. Default is 10.
         v_lim: Velocity threshold. Smaller values are classified as clutter.
             Default is 0.05 (m/s).
 
     Returns:
-    -------
         2-D boolean array denoting pixels contaminated by clutter.
 
     """

cloudnetpy/categorize/droplet.py

@@ -18,7 +18,6 @@ def correct_liquid_top(
     """Corrects lidar detected liquid cloud top using radar data.
 
     Args:
-    ----
         obs: The :class:`ClassData` instance.
         is_liquid: 2-D boolean array denoting liquid clouds from lidar data.
         is_freezing: 2-D boolean array of sub-zero temperature, derived from the model
@@ -26,11 +25,9 @@ def correct_liquid_top(
         limit: The maximum correction distance (m) above liquid cloud top.
 
     Returns:
-    -------
         Corrected liquid cloud array.
 
     References:
-    ----------
         Hogan R. and O'Connor E., 2004, https://bit.ly/2Yjz9DZ.
 
     """
@@ -64,7 +61,6 @@ def find_liquid(
     """Estimate liquid layers from SNR-screened attenuated backscatter.
 
     Args:
-    ----
         obs: The :class:`ClassData` instance.
         peak_amp: Minimum value of peak. Default is 1e-6.
         max_width: Maximum width of peak. Default is 300 (m).
@@ -76,11 +72,9 @@ def find_liquid(
         min_alt: Minimum altitude of the peak from the ground. Default is 100 (m).
 
     Returns:
-    -------
         2-D boolean array denoting liquid layers.
 
     References:
-    ----------
         The method is based on Tuononen, M. et.al, 2019,
         https://acp.copernicus.org/articles/19/1985/2019/.
 
@@ -134,7 +128,6 @@ def ind_base(dprof: np.ndarray, ind_peak: int, dist: int, lim: float) -> int:
     below the peak exceed a threshold value.
 
     Args:
-    ----
         dprof: 1-D array of 1st discrete difference. Masked values should
             be 0, e.g. dprof = np.diff(masked_prof).filled(0)
         ind_peak: Index of (possibly local) peak in the original profile.
@@ -149,16 +142,13 @@ def ind_base(dprof: np.ndarray, ind_peak: int, dist: int, lim: float) -> int:
             in the profile.
 
     Returns:
-    -------
         Base index of the peak.
 
     Raises:
-    ------
         IndexError: Can't find proper base index (probably too many masked
             values in the profile).
 
     Examples:
-    --------
         Consider a profile
 
         >>> x = np.array([0, 0.5, 1, -99, 4, 8, 5])
@@ -187,7 +177,6 @@ def ind_base(dprof: np.ndarray, ind_peak: int, dist: int, lim: float) -> int:
             1
 
     See Also:
-    --------
         droplet.ind_top()
 
     """
@@ -204,7 +193,6 @@ def ind_top(dprof: np.ndarray, ind_peak: int, nprof: int, dist: int, lim: float)
     above the peak exceed a threshold value.
 
     Args:
-    ----
         dprof: 1-D array of 1st discrete difference. Masked values should be 0, e.g.
             dprof = np.diff(masked_prof).filled(0)
         nprof: Length of the profile. Top index can't be higher than this.
@@ -218,16 +206,13 @@ def ind_top(dprof: np.ndarray, ind_peak: int, nprof: int, dist: int, lim: float)
             likely accept some other point, higher in the profile.
 
     Returns:
-    -------
         Top index of the peak.
 
     Raises:
-    ------
         IndexError: Can not find proper top index (probably too many masked
             values in the profile).
 
     See Also:
-    --------
         droplet.ind_base()
 
     """
@@ -241,11 +226,9 @@ def interpolate_lwp(obs: ClassData) -> np.ndarray:
     """Linear interpolation of liquid water path to fill masked values.
 
     Args:
-    ----
         obs: The :class:`ClassData` instance.
 
     Returns:
-    -------
         Liquid water path where the masked values are filled by interpolation.
 
     """

cloudnetpy/categorize/falling.py

@@ -21,17 +21,14 @@ def find_falling_hydrometeors(
     temperatures.
 
     Args:
-    ----
         obs: The :class:`ClassData` instance.
         is_liquid: 2-D boolean array of liquid droplets.
         is_insects: 2-D boolean array of insects.
 
     Returns:
-    -------
         2-D boolean array containing falling hydrometeors.
 
     References:
-    ----------
         Hogan R. and O'Connor E., 2004, https://bit.ly/2Yjz9DZ.
 
     """

cloudnetpy/categorize/freezing.py

@@ -20,16 +20,13 @@ def find_freezing_region(obs: ClassData, melting_layer: np.ndarray) -> np.ndarra
     interpolated for all profiles.
 
     Args:
-    ----
         obs: The :class:`ClassData` instance.
         melting_layer: 2-D boolean array denoting melting layer.
 
     Returns:
-    -------
         2-D boolean array denoting the sub-zero region.
 
     Notes:
-    -----
         It is not clear how model temperature and melting layer should be
         ideally combined to determine the sub-zero region. This current
         method differs slightly from the original Matlab code and should
@@ -84,12 +81,10 @@ def _find_t0_alt(temperature: np.ndarray, height: np.ndarray) -> np.ndarray:
     """Interpolates altitudes where temperature goes below freezing.
 
     Args:
-    ----
         temperature: 2-D temperature (K).
         height: 1-D altitude grid (m).
 
     Returns:
-    -------
         1-D array denoting altitudes where the temperature drops below 0 deg C.
 
     """

cloudnetpy/categorize/insects.py

@@ -29,7 +29,6 @@ def find_insects(
     above melting layer.
 
     Args:
-    ----
         obs: The :class:`ClassData` instance.
         melting_layer: 2D array denoting melting layer.
         liquid_layers: 2D array denoting liquid layers.
@@ -37,14 +36,12 @@ def find_insects(
             Default is 0.8.
 
     Returns:
-    -------
         tuple: 2-element tuple containing
 
         - 2-D boolean flag of insects presence.
         - 2-D probability of pixel containing insects.
 
     Notes:
-    -----
         This insect detection method is novel and needs to be validated.
 
     """

cloudnetpy/categorize/lidar.py

@@ -13,7 +13,6 @@ class Lidar(DataSource):
     """Lidar class, child of DataSource.
 
     Args:
-    ----
         full_path: Cloudnet Level 1 lidar netCDF file.
 
     """

cloudnetpy/categorize/melting.py

@@ -32,20 +32,17 @@ def find_melting_layer(obs: ClassData, *, smooth: bool = True) -> np.ndarray:
     the rest -8..+6.
 
     Notes:
-    -----
         This melting layer detection method is novel and needs to be validated.
         Also note that there might be some detection problems with strong
         updrafts of air. In these cases the absolute values for speed do not
         make sense (rain drops can even move upwards instead of down).
 
     Args:
-    ----
         obs: The :class:`ClassData` instance.
         smooth: If True, apply a small Gaussian smoother to the
             melting layer. Default is True.
 
     Returns:
-    -------
         2-D boolean array denoting the melting layer.
 
     """

cloudnetpy/categorize/model.py

@@ -14,12 +14,10 @@ class Model(DataSource):
     """Model class, child of DataSource.
 
     Args:
-    ----
         model_file: File name of the NWP model file.
         alt_site: Altitude of the site above mean sea level (m).
 
     Attributes:
-    ----------
         source_type (str): Model type, e.g. 'gdas1' or 'ecwmf'.
         model_heights (ndarray): 2-D array of model heights (one for each time
             step).
@@ -56,7 +54,6 @@ class Model(DataSource):
         """Interpolates model variables to common height grid.
 
         Args:
-        ----
             wl_band: Integer denoting the approximate wavelength band of the
                 cloud radar (0 = ~35.5 GHz, 1 = ~94 GHz).
 
@@ -90,12 +87,10 @@ class Model(DataSource):
         """Interpolates model variables to Cloudnet's dense time / height grid.
 
         Args:
-        ----
             time_grid: The target time array (fraction hour).
             height_grid: The target height array (m).
 
         Returns:
-        -------
             Indices fully masked profiles.
 
         """

cloudnetpy/categorize/mwr.py

@@ -10,7 +10,6 @@ class Mwr(DataSource):
     """Microwave radiometer class, child of DataSource.
 
     Args:
-    ----
          full_path: Cloudnet Level 1b mwr file.
 
     """
@@ -24,7 +23,6 @@ class Mwr(DataSource):
         """Approximates lwp and its error in a grid using mean.
 
         Args:
-        ----
             time_grid: 1D target time grid.
 
         """

cloudnetpy/categorize/radar.py

@@ -16,11 +16,9 @@ class Radar(DataSource):
     """Radar class, child of DataSource.
 
     Args:
-    ----
         full_path: Cloudnet Level 1 radar netCDF file.
 
     Attributes:
-    ----------
         radar_frequency (float): Radar frequency (GHz).
         folding_velocity (float): Radar's folding velocity (m/s).
         location (str): Location of the radar, copied from the global attribute
@@ -33,7 +31,6 @@ class Radar(DataSource):
             radars.
 
     See Also:
-    --------
         :func:`instruments.rpg2nc()`, :func:`instruments.mira2nc()`
 
     """
@@ -53,7 +50,6 @@ class Radar(DataSource):
         """Rebins radar data in time using mean.
 
         Args:
-        ----
             time_new: Target time array as fraction hour. Updates *time* attribute.
 
         """
@@ -202,12 +198,10 @@ class Radar(DataSource):
         """Corrects radar echo for liquid and gas attenuation.
 
         Args:
-        ----
             attenuations: 2-D attenuations due to atmospheric gases and liquid:
                 `radar_gas_atten`, `radar_liquid_atten`.
 
         References:
-        ----------
             The method is based on Hogan R. and O'Connor E., 2004,
             https://bit.ly/2Yjz9DZ and the original Cloudnet Matlab implementation.
 
@@ -228,12 +222,10 @@ class Radar(DataSource):
         :class:`CloudnetArray` instances to `data` attribute.
 
         Args:
-        ----
             attenuations: 2-D attenuations due to atmospheric gases.
             classification: The :class:`ClassificationResult` instance.
 
         References:
-        ----------
             The method is based on Hogan R. and O'Connor E., 2004,
             https://bit.ly/2Yjz9DZ and the original Cloudnet Matlab implementation.