code: def histogram_equalization(
      data,
      mask_to_equalize,
      number_of_bins=1000,
      std_mult_cutoff=4.0,
      do_zerotoone_normalization=True,
      out=None,
  ):
      """Perform a histogram equalization on the data.
  
      Data is selected by the mask_to_equalize mask.
      The data will be separated into number_of_bins levels for equalization and
      outliers beyond +/- std_mult_cutoff*std will be ignored.
  
      If do_zerotoone_normalization is True the data selected by mask_to_equalize
      will be returned in the 0 to 1 range. Otherwise the data selected by
      mask_to_equalize will be returned in the 0 to number_of_bins range.
  
      Note: the data will be changed in place.
      """
      out = out if out is not None else data.copy()
  
      LOG.debug("determining DNB data range for histogram equalization")
      sub_arr = data[mask_to_equalize]
      if sub_arr.size == 0:
          # no good data
          return out
  
      avg = np.mean(sub_arr)
      std = np.std(sub_arr)
      # limit our range to +/- std_mult_cutoff*std; e.g. the default
      # std_mult_cutoff is 4.0 so about 99.8% of the data
      concervative_mask = (
          (data < (avg + std * std_mult_cutoff))
          & (data > (avg - std * std_mult_cutoff))
          & mask_to_equalize
      )
  
      LOG.debug("running histogram equalization")
      (
          cumulative_dist_function,
          temp_bins,
      ) = _histogram_equalization_helper(
          data[concervative_mask], number_of_bins
      )
  
      # linearly interpolate using the distribution function to get the new
      # values
      out[mask_to_equalize] = np.interp(
          data[mask_to_equalize],
          temp_bins[:-1],
          cumulative_dist_function,
      )
  
      # if we were asked to, normalize our data to be between zero and one,
      # rather than zero and number_of_bins
      if do_zerotoone_normalization:
          _linear_normalization_from_0to1(
              out, mask_to_equalize, number_of_bins
          )
  
      return out
  
imports: from __future__ import annotations
  import logging
  import math
  from datetime import datetime
  import dask
  import dask.array
  import numpy
  import xarray
  from satpy.composites import CompositeBase, GenericCompositor
  from satpy.dataset import combine_metadata
label_desc: Use image node_id 2 for calling a global function with example usage: histogram_equalization(data, mask_to_equalize, number_of_bins, std_mult_cutoff, do_zerotoone_normalization, out) and returns: out, out