:py:mod:`maxent_disaggregation.plot_samples_hist`
=================================================

.. py:module:: maxent_disaggregation.plot_samples_hist


Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   maxent_disaggregation.plot_samples_hist.plot_samples_hist



.. py:function:: plot_samples_hist(samples, mean_0=None, sd_0=None, shares=None, sds=None, logscale=False, plot_agg=True, plot_sample_mean=True, title=None, xlabel=None, ylabel=None, ylim=None, legend_labels=None, save=False, filename=None)

   Plot histograms of sample distributions, optionally including aggregate and sample means.
   :param samples: 2D array of shape (n_samples, n_disaggregates) containing the samples to plot.
   :type samples: np.ndarray
   :param mean_0: Mean of the aggregate distribution for labeling purposes.
   :type mean_0: float, optional
   :param sd_0: Standard deviation of the aggregate distribution for labeling purposes.
   :type sd_0: float, optional
   :param shares: List of share values for each disaggregate, used for labeling.
   :type shares: list or np.ndarray, optional
   :param sds: List of standard deviations for each disaggregate, used for labeling.
   :type sds: list or np.ndarray, optional
   :param logscale: If True, use a logarithmic scale for the x-axis. Default is False.
   :type logscale: bool, optional
   :param plot_agg: If True, plot the histogram of the aggregate (sum across disaggregates). Default is True.
   :type plot_agg: bool, optional
   :param plot_sample_mean: If True, plot vertical lines for the mean of each sample and the aggregate. Default is True.
   :type plot_sample_mean: bool, optional
   :param title: Title for the plot. If None, a default title is used.
   :type title: str, optional
   :param xlabel: Label for the x-axis. If None, defaults to "Value".
   :type xlabel: str, optional
   :param ylabel: Label for the y-axis. If None, defaults to "Probability density".
   :type ylabel: str, optional
   :param ylim: Tuple specifying y-axis limits (min, max). If None, limits are set automatically.
   :type ylim: tuple, optional
   :param legend_labels: Custom labels for the legend for each disaggregate and the aggregate.
   :type legend_labels: list of str, optional
   :param save: If True, save the plot to a file specified by `filename`. Default is False.
   :type save: bool, optional
   :param filename: Path to save the plot if `save` is True.
   :type filename: str, optional

   :raises ValueError: If `save` is True and `filename` is not provided.

   .. rubric:: Notes

   - Each disaggregate's histogram is plotted with its own color and label.
   - The aggregate histogram (sum across disaggregates) is plotted if `plot_agg` is True.
   - Sample means are indicated with dashed vertical lines if `plot_sample_mean` is True.
   - The function uses matplotlib for plotting and will display the plot unless `save` is True.