MultiDataPlotting 1.3.4
A package for plotting multiple datasets
License: MIT
Requires Python: >=3.6

# MultiDataPlotting

`MultiDataPlotting` is a Python package designed for easy and efficient plotting of multiple data sets, providing tools for generating bar plots, scatter plots, and other types of visual data representations. It leverages popular libraries such as Matplotlib, Seaborn, and Pandas to offer a versatile set of plotting functionalities.

## Features

- Plot multiple data sets in a single figure.
- Support for various types of plots: bar plots, scatter plots, line plots, rose maps.
- Customizable plot settings: colors, labels, legends, and more.
- Integration with Pandas for direct data frame plotting.

## Installation

You can install `MultiDataPlotting` using pip:

```bash
pip install MultiDataPlotting
```

## Usage

To use the package, you can import it into your Python scripts as follows:

```python
import multidataprocessing as mdp
```

### Plotting Beeswarm with Reference Lines

The `plot_beeswarm` function in our advanced data visualization toolkit offers a comprehensive method for displaying beeswarm plots that highlight medians and interquartile ranges (IQRs), along with optional horizontal reference lines for key values such as optimizer or desired outcomes. This function is ideal for statistical analysis across various categories or conditions in fields like environmental science, economics, and health sciences.

_Functionality_

This function facilitates the visualization of value distributions across different categories with additional context provided by horizontal reference lines, which can be set according to the user's specific needs (e.g., target values, thresholds). It helps in understanding data spread, central tendency, and compliance with desired or optimal values.

_Parameters_
- **categories** (list): Category labels for the x-axis.
- **values** (list of arrays): Data points for each category.
- **optimizer_value** (float, optional): The optimizer value to plot as a horizontal dashed line. Default is `None`.
- **desired_value** (float, optional): The desired target value to plot as a horizontal solid line. Default is `None`.
- **fig_size** (tuple, optional): Dimensions of the figure in inches. Default is `(12, 8)`.
- **swarm_color** (str, optional): Color of the swarm points. Default is 'gray'.
- **swarm_size** (int, optional): Size of the swarm points. Default is 2.
- **swarm_transparency** (float, optional): Transparency of swarm points. Default is `None`.
- **median_color** (str, optional): Color of the median points. Default is 'black'.
- **median_edge_color** (str, optional): Edge color of the median points. Default is 'none'.
- **median_size** (int, optional): Size of the median points. Default is 30.
- **line_color** (str, optional): Color of the IQR lines and desired value line. Default is 'black'.
- **line_thickness** (int, optional): Thickness of the IQR and desired value lines. Default is 2.
- **optimizer_color** (str, optional): Color of the optimizer line. Default is 'black'.
- **optimizer_style** (str, optional): Style of the optimizer line. Default is '--'.
- **optimizer_thickness** (int, optional): Thickness of the optimizer line. Default is 1.5.
- **desired_color** (str, optional): Color of the desired value line. Default is 'blue'.
- **desired_style** (str, optional): Style of the desired value line. Default is '-'.
- **desired_thickness** (int, optional): Thickness of the desired value line. Default is 1.5.
- **title** (str, optional): Title of the plot. Default is 'Subcatchment Area Distribution by Site'.
- **xlabel_name** (str, optional): Label for the x-axis. Default is 'Category'.
- **ylabel_name** (str, optional): Label for the y-axis. Default is 'Subcatchment Area (kmÂ²)'.
- **xlabel_size** (int, optional): Font size for the x-axis label. Default is 12.
- **ylabel_size** (int, optional): Font size for the y-axis label. Default is 12.
- **xlabel_font** (str, optional): Font family for the x-axis label. Default is 'Arial'.
- **ylabel_font** (str, optional): Font family for the y-axis label. Default is 'Arial'.
- **tick_font_name** (str, optional): Font family for tick labels. Default is 'Arial'.
- **tick_font_size** (int, optional): Font size for tick labels. Default is 10.
- **xtick_rotation** (int, optional): Rotation angle of x-axis tick labels. Default is 0.
- **y_range** (tuple, optional): Y-axis range for the plot. Default is `None`.
- **is_show** (bool, optional): Whether to display the plot on screen. Default is True.
- **save_path** (str, optional): File path to save the plot image, if desired.

_Code Example_

```python
import numpy as np
import pandas as pd
import multidataplotting as mdp

categories = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N']  # Example categories
values = [np.random.rand(150) * 1.0 + 0.5 for _ in categories]  # Random data generation for illustration
optimizer_value = 1.2  # Example value for optimizer bandwidth
desired_value = 1.0  # Example value for desired value

mdp.plot_beeswarm(categories, values, optimizer_value = optimizer_value , desired_value=desired_value)
```

![alt text](https://github.com/wwang487/MultiDataPlotting/blob/main/picture/beeswarm.png?raw=true)

### Plotting Clustered Data with Boundaries
The `plot_clustered_data` function in the advanced data visualization toolkit allows for the visual representation of data clusters from a pandas DataFrame. This function is highly versatile, supporting multiple clustering methods and customizable plot aesthetics, including the option to draw smoothed boundaries around clusters. It is particularly useful in fields such as market segmentation, bioinformatics, environmental analysis, and any other area where data clustering provides insight.

_Functionality_

This function provides a detailed clustering and visualization of multidimensional data. Users can select specific columns for clustering and choose different axes for visualization. It supports various clustering algorithms, and it can visually delineate cluster boundaries, enhancing the interpretability of cluster separation and density. This makes it an invaluable tool for comprehensive data analysis and presentation.

_Parameters_
- **df** (pandas.DataFrame): The DataFrame containing the data.
- **columns** (list): Column indices or names to include in the clustering.
- **x_index** (int or str): Column index or name for the x-axis of the plot.
- **y_index** (int or str): Column index or name for the y-axis of the plot.
- **n_clusters** (int, optional): Number of clusters for certain algorithms. Default is 3.
- **method** (str, optional): Clustering method; options include 'KMeans', 'Agglomerative', 'DBSCAN', 'Spectral', or 'GaussianMixture'. Default is 'KMeans'.
- **marker_size** (int, optional): Size of the markers in the plot. Default is 50.
- **marker_colors** (list or dict, optional): Colors for the markers, specified as a list or dictionary mapping clusters to colors. Defaults to the 'viridis' colormap.
- **marker_type** (str, optional): Shape of the markers, such as 'o' (circle), 'x' (cross). Default is 'o'.
- **fig_size** (tuple, optional): Dimensions of the figure in inches. Default is (10, 5).
- **tick_font_size** (int, optional): Font size for tick labels. Default is 12.
- **tick_font_name** (str, optional): Font family for tick labels. Default is 'Arial'.
- **xlabel** (str, optional): Label for the x-axis. Default is 'X-axis'.
- **ylabel** (str, optional): Label for the y-axis. Default is 'Y-axis'.
- **label_font_size** (int, optional): Font size for axis labels. Default is 14.
- **is_legend** (bool, optional): Whether to display a legend for the clusters. Default is True.
- **cluster_names** (list, optional): Custom names for each cluster in the legend. Defaults to generic names like "Cluster 0".
- **is_show** (bool, optional): Whether to display the plot on screen. Default is True.
- **save_path** (str, optional): File path to save the plot image, if desired.
- **is_boundary** (bool, optional): Whether to draw smooth boundaries around each cluster using a convex hull. Default is False.
- **boundary_color** (str, optional): Color of the boundary lines. Default is 'black'.
- **boundary_linewidth** (int, optional): Width of the boundary lines. Default is 2.
- **boundary_alpha** (float, optional): Transparency of the boundary lines. Default is 0.5.

_Code Example_

```python
import pandas as pd
import numpy as np
import multidataplotting as mdp
np.random.seed(4444)  # For reproducible results
data = {
    'Feature1': np.random.normal(loc=0, scale=1, size=100),  # Normal distribution centered at 0
    'Feature2': np.random.normal(loc=5, scale=2, size=100),  # Normal distribution centered at 5
    'Feature3': np.random.normal(loc=10, scale=3, size=100)  # Normal distribution centered at 10
}

# Create DataFrame
df = pd.DataFrame(data)
# Example usage:
# Assuming 'df' is your DataFrame and it contains columns that you want to cluster
mdp.plot_clustered_data(df, ['Feature1', 'Feature2', 'Feature3'], 'Feature1', 'Feature2',
                    method='KMeans', marker_type='^', cluster_names=['Type A', 'Type B', 'Type C'], is_legend=True, is_boundary=True)
```

![alt text](https://github.com/wwang487/MultiDataPlotting/blob/main/picture/clusters.png?raw=true)

### Heatmap Plotting on Geographic Maps

The `plot_heatmap_on_geomap` function facilitates the visualization of spatial data distributions by rendering heatmaps on geographic maps. It supports two mapping backends, Basemap and OpenStreetMap (OSM), offering flexibility in the appearance and detail of the underlying geographic context. This function is ideal for environmental studies, meteorology, urban planning, and other disciplines requiring geographic data visualization.

_Functionality_

This function overlays heatmap data onto a geographic map, allowing for precise visualization adjustments. It supports various customization options, including transparency thresholds, colormap choices, and tick formatting. The integration of Basemap and OpenStreetMap ensures broad applicability for different visualization needs.

_Parameters_

- **data** (numpy.ndarray): The 2D array of data points to be visualized as a heatmap.
- **top_left_lat, top_left_lon** (float): The latitude and longitude of the top-left corner of the map.
- **bottom_right_lat, bottom_right_lon** (float): The latitude and longitude of the bottom-right corner of the map.
- **threshold** (float): The data value threshold below which points will be transparent.
- **cmap** (str, optional): Colormap for the heatmap. Default is 'jet'.
- **map_choice** (str, optional): Backend map provider ('base' for Basemap, 'osm' for OpenStreetMap). Default is 'base'.
- **zoom** (int, optional): Zoom level for the map when using OSM. Default is 10.
- **is_show** (bool, optional): Whether to display the plot. Default is True.
- **save_path** (str, optional): Path to save the figure. If not specified, the figure is not saved.
- **title** (str, optional): Title of the plot. Default is 'Heatmap Overlay on Geomap'.
- **colorbar_label** (str, optional): Label for the colorbar. Default is 'Data Intensity'.
- **fig_size** (tuple, optional): Figure dimensions in inches. Default is (8, 6).
- **x_tick_interval, y_tick_interval** (float, optional): Interval between ticks on the x and y axes.
- **tick_format** (str, optional): Format string for tick labels. Default is "{:.2f}".

_Code Example_

```python
import numpy as np
import multidataplotting as mdp

data = np.random.rand(100, 100)
mdp.plot_heatmap_on_geomap(data, 48.0, -123.0, 45.0, -120.0, threshold=0.75, map_choice='osm', x_tick_interval=1, y_tick_interval=1, tick_format="{:.2f}")

```

![alt text](https://github.com/wwang487/MultiDataPlotting/blob/main/picture/heatgeomap.png?raw=true)


### Plotting Data by Quadrants

The `plot_quadrant_data` function in our toolkit provides a robust method for displaying data points categorized by defined thresholds on both the x and y axes. This function is ideal for applications in fields such as finance, meteorology, and health sciences where data is often analyzed by its position relative to critical thresholds.

_Functionality_

This function categorizes and visualizes data points into quadrants based on user-specified x and y threshold values. It supports customization of various plot aspects including category names, marker aesthetics, and plot labels, enhancing the interpretability and visual appeal of the output.

_Parameters_
- **data** (pandas.DataFrame): The DataFrame must contain 'x' and 'y' columns.
- **x_threshold** (float): Threshold value for categorizing data along the x-axis.
- **y_threshold** (float): Threshold value for categorizing data along the y-axis.
- **fig_size** (tuple): Figure size; default is (10, 8)
- **category_names** (list, optional): Custom names for each category; default categories are 'Above Left', 'Above Right', 'Below Left', 'Below Right', 'On Line'.
- **xlabel** (str, optional): Label for the x-axis. Default is 'Centroid offset (mm)'.
- **ylabel** (str, optional): Label for the y-axis. Default is 'Edge height difference (mm)'.
- **title** (str, optional): Title of the plot. Default is 'Classification of Data Relative to Threshold Lines'.
- **xlabel_size**, **ylabel_size**, **title_size** (int, optional): Font sizes for the x-axis label, y-axis label, and title.
- **marker_color** (str or list, optional): Color map or list of colors for the markers. Default is 'viridis'.
- **marker_size** (int, optional): Size of the markers. Default is 100.
- **x_tick_interval**, **y_tick_interval** (float, optional): Custom intervals for x and y axis ticks.
- **tick_font** (str, optional): Font family for tick labels. Default is 'Arial'.
- **tick_font_size** (int, optional): Font size for tick labels. Default is 10.
- **is_show** (bool, optional): If True, display the plot on screen. Default is True.
- **is_legend** (bool, optional): If True, display a legend for the categories. Default is True.
- **save_path** (str, optional): File path to save the plot image, if desired.

_Code Example_

```python
import pandas as pd
import numpy as np
import multidataplotting as mdp

# Example data
np.random.seed(0)
data = pd.DataFrame({
    'x': np.random.normal(0, 50, 300),
    'y': np.random.normal(0, 5, 300)
})

# Define thresholds
x_threshold = 0  # Example threshold for x-axis
y_threshold = 0  # Example threshold for y-axis

# Classify the data
mdp.plot_quadrant_data(data, x_threshold, y_threshold)
```

![alt text](https://github.com/wwang487/MultiDataPlotting/blob/main/picture/quadrant.png?raw=true)

### Plotting Grouped Dot Chart with Vertical Lines

The `plot_grouped_dot_chart` function in our data visualization toolkit provides a dynamic method for creating grouped dot charts with vertical connecting lines to the x-axis. This function is particularly useful for visualizing categorical data comparisons across different states or groups, highlighting individual data points and their distribution within each category.

_Functionality_

This function enables the visualization of numerical data across categorical groups with enhancements that visually connect each data point to the baseline, thereby facilitating a clearer understanding of value distribution and differences between groups.

_Parameters_
- **data** (DataFrame): The DataFrame containing the data to be plotted. Must include categorical and numerical columns.
- **category_col** (str): The column name in DataFrame used as the categorical axis (e.g., 'State').
- **value_cols** (list of str, optional): The column names to be plotted as numerical values. If `None`, all columns except `category_col` are used.
- **label_size** (int, optional): Font size for the axis labels. Default is 12.
- **tick_label_size** (int, optional): Font size for the tick labels. Default is 10.
- **cmap** (str, optional): Name of the matplotlib colormap used for differentiating categories. Default is 'tab20'.
- **font_name** (str, optional): Font family for text elements in the plot. Default is 'Arial'.
- **is_legend** (bool, optional): Whether to display the legend in the plot. Default is True.
- **is_show** (bool, optional): Whether to display the plot on screen after drawing. Default is True.
- **fig_size** (tuple, optional): Dimensions of the figure in inches. Default is (10, 8).
- **save_path** (str, optional): File path to save the plot image, if desired. Default is None.

_Code Example_

```python
import pandas as pd
import multidataplotting as mdp

# Example data
data = pd.DataFrame({
    'State': ['CA', 'TX', 'NY', 'FL', 'IL', 'PA'],
    'Under 5 Years': [2.5, 3.0, 1.5, 2.0, 1.8, 2.1],
    '5 to 13 Years': [4.0, 4.5, 2.5, 3.5, 3.0, 3.6],
    '14 to 17 Years': [1.0, 1.2, 0.8, 1.1, 1.0, 0.9],
    '18 to 24 Years': [2.8, 3.2, 1.9, 2.5, 2.2, 2.8],
    '25 to 44 Years': [8.0, 7.5, 4.5, 6.0, 5.5, 5.9],
    '45 to 64 Years': [7.5, 8.0, 5.0, 6.5, 6.0, 6.4],
    '65 Years and Over': [5.0, 5.5, 3.5, 4.0, 3.8, 4.2]
})
mdp.plot_grouped_dot_chart(data, is_legend=True, is_show=True, fig_size=(12, 8))

```

![alt text](https://github.com/wwang487/MultiDataPlotting/blob/main/picture/dotline.png?raw=true)

### Plot Ridgelines

The `plot_ridgelines` function is a specialized visualization tool designed for creating impactful ridgeline plots, which are ideal for displaying the distribution of data across different categories, such as time periods or groups. This function is versatile and can be tailored for various data analysis needs, especially useful in statistics, finance, environmental science, and more.

_Functionality_

This function generates ridgeline plots that help in visualizing changes or distributions over categories with a clear, artistic representation. The use of color gradients or monochrome palettes enhances the visual appeal and helps in distinguishing between categories effectively.

_Parameters_
- **data** (Dictionary or DataFrame): Contains the data for each category. If a dictionary, it will be converted into a DataFrame.
- **categories** (list): A list of categories representing each dataset, like months or groups.
- **x_label** (str): Label for the x-axis.
- **title** (str): Title of the plot.
- **cmap** (str, optional): Color palette to use. If None, a black and white scheme is employed.
- **tick_interval** (float, optional): Specifies the interval between ticks on the x-axis. If None, the default is used.
- **tick_size** (int): Font size for the x-axis ticks.
- **tick_font** (str): Font family for the x-axis ticks.
- **category_size** (int): Font size for category labels.
- **category_font** (str): Font family for category labels.
- **title_size** (int): Font size for the plot title.
- **save_path** (str, optional): If provided, the plot will be saved to the specified path.
- **is_show** (bool): If True, the plot will be displayed. If False, the plot will be closed after creation.
- **is_legend** (bool): If True, a legend mapping colors to categories will be displayed.
- **fig_size** (tuple): Dimensions of the figure (width, height).

_Code Example_

```python
import pandas as pd
import numpy as np
import multidataplotting as mdp
# Sample data creation
np.random.seed(10)
months = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
data = {month: np.random.normal(loc=20 + i, scale=5, size=100) for i, month in enumerate(months)}
# Example usage
mdp.plot_ridgelines(data, months, 'Mean Temperature [F]', 'Temperatures by Month', cmap='viridis', tick_interval=5)
```

![alt text](https://github.com/wwang487/MultiDataPlotting/blob/main/picture/ridge.png?raw=true)

### Plotting Time Histograms

The `plot_time_histogram` function creates histograms based on time data, ideal for visualizing event frequencies over specific intervals. This method helps in identifying trends and patterns by illustrating how event occurrences are distributed across different time points.

_Functionality_

This function is particularly useful in scenarios such as analyzing user activity logs, sales data over time, or any periodic data that is timestamped. It helps in understanding the distribution and concentration of events, aiding in decision-making processes like resource allocation during peak times

_Parameters_

- **histogram** (dict): Dictionary with datetime keys (either strings or objects) and frequency counts as values.
- **color** (str, optional): Color of the histogram bars. Default is 'blue'.
- **edgecolor** (str, optional): Color of the bar edges. Default is 'black'.
- **fig_size** (tuple, optional): Size of the figure in inches. Default is (10, 6).
- **tick_fontname** (str, optional): Font name for the tick labels. Default is 'Arial'.
- **tick_fontsize** (int, optional): Font size for the tick labels. Default is 12.
- **title_fontsize** (int, optional): Font size for the title of the plot. Default is 14.
- **label_fontsize** (int, optional): Font size for the axis labels. Default is 14.
- **y_range** (list, optional): List specifying the y-axis limits as [min, max]. If not set, the axis scales automatically.
- **x_tick_interval_minutes**: (int,optional): the interval of the x ticks in minutes
- **x_ticklabel_format** (str, optional): Format of the x-tick labels, can be 'HH' for hours and minutes, or 'YYYY-MM-DD' for dates. Default is 'HH'.
- **is_legend** (bool, optional): Indicates whether to display a legend. Default is False.
- **save_path** (str, optional): File path where the plot will be saved, if desired. If not provided, the plot is not saved.
- **is_show** (bool, optional): Whether to display the plot on the screen. Default is False.
- **is_save** (bool, optional): Whether to save the plot to a file. Default is True.
- **transparent_bg** (bool, optional): Whether the background of the saved figure should be transparent. Default is True.

_Code Example_

```python
import multidataplotting as mdp

# Example histogram data
# Example usage with datetime conversion
login_data = {
    '00:00:00 - 00:03:00': 100,
    '00:03:00 - 00:06:00': 150,
    '00:07:00 - 00:12:00': 125,
    '00:19:00 - 00:23:00': 175,
    '00:29:00 - 00:33:00': 175,
}

mdp.plot_time_histogram(login_data, color='blue', edgecolor='black', is_show=True)
```
![alt text](https://github.com/wwang487/MultiDataPlotting/blob/main/picture/timehist.png?raw=true)

### Plotting Polylines

The `plot_polylines` function in the multidataprocessing package is designed to plot multiple lines from a DataFrame using specified columns for the x and y axes. This functionality is essential for visualizing trends and relationships in data over time or across categories.

_Functionality_

This function is invaluable for comparing trends across multiple datasets, enabling clear insights into how different variables evolve concurrently. It is particularly useful in financial analysis, environmental monitoring, or any scientific data visualization involving multiple variables.

_Parameters_

- **df** (pandas.DataFrame): The DataFrame containing the data to plot.
- **x** (int): Index of the column in the DataFrame to use as the x-axis.
- **ys** (list of int): Indices of columns to plot on the y-axis.
- **line_styles** (dict, optional): Dictionary specifying line styles for each y-column plotted, with keys as column indices and values as style strings. Default is solid lines for all.
- **line_widths** (dict, optional): Dictionary specifying line widths for each plotted y-column, with keys as column indices and values as numeric widths. Default is 2 for all lines.
- **line_colors** (dict, optional): Dictionary specifying colors for each plotted y-column, with keys as column indices and values as color names or hex codes. Default is 'blue' for all lines.
- **legends** (list, optional): List of legend labels corresponding to each y-column. If not provided, column names are used as labels.
- **marker_colors** (dict, optional): Dictionary specifying marker colors for each y-column, enhancing distinctiveness of each line.
- **fig_size** (tuple, optional): Size of the figure in inches. Default is (10, 6).
- **x_tick_interval** (int, optional): Interval at which x-axis ticks should be placed. Default is 1.
- **markers** (dict, optional): Dictionary specifying marker styles for each y-column plotted, adding visual distinction to the lines.
- **y_label** (str, optional): Label for the y-axis. If not provided, defaults to a generic label.
- **show_grid** (bool, optional): Whether to display a grid in the background of the plot. Default is True.
- **font_name** (str, optional): Font family for all text elements in the plot. Default is 'Arial'.
- **font_size** (int, optional): Font size for all text elements in the plot. Default is 12.
- **save_path** (str, optional): Path to save the figure to a file. If not specified, the figure is not saved.
- **dpi** (int, optional): Resolution of the saved figure in dots per inch. Default is 600.
- **y_range** (list, optional): Specific limits for the y-axis as [min, max].
- **is_show** (bool, optional): Whether to display the plot on the screen. Default is True.

_Code Example_

```python
import pandas as pd
import numpy as np
import multidataplotting as mdp

data = {
    'X': list(range(12)),
    'Product1': np.random.randint(1000, 5000, size=12),
    'Product2': np.random.randint(1000, 5000, size=12)
}

data = pd.DataFrame(data)
mdp.plot_polylines(data, x=0, ys=[1, 2], line_colors={1: 'red', 2: 'green'}, x_tick_interval = 2, markers={1: 'o', 2: 'x'})
```
![alt text](https://github.com/wwang487/MultiDataPlotting/blob/main/picture/polyline.png?raw=true)

### plot_rolling_series Function Documentation

The `plot_rolling_series` function is designed for visualizing time series data along with its rolling statistics such as rolling maximum, minimum, and average. This function allows for significant customization to suit various analytical and presentation needs.

_Functionality_

This function plots a given time series data with its rolling statistics to provide insights into trends, fluctuations, and overall behavior over a specified period. It includes options for visual customization and can be adapted for both simple exploratory analysis and detailed, polished presentations.

_Parameters_

- **data** (`pd.Series`): The time series data as a Pandas Series with a DateTime index.
- **rolling_period** (`int`): The number of periods to use for calculating rolling statistics.
- **title** (`str`): The title of the plot.
- **xlabel**, **ylabel** (`str`): Labels for the X and Y axes.
- **series_color**, **max_color**, **min_color**, **avg_color** (`str`): Colors for the original data series, rolling maximum, minimum, and average lines.
- **alpha** (`float`): Opacity for the original series plot, where 1 is opaque and 0 is transparent.
- **fig_size** (`tuple`): Dimensions of the figure (width, height).
- **line_width** (`int`): The thickness of the plotted lines.
- **line_style** (`str`): Style of the lines (e.g., '-', '--', '-.', ':').
- **legend_labels** (`dict`): Labels for the plot legend, should include keys for 'original', 'max', 'min', and 'avg'.
- **font_name** (`str`): Font family for all text elements in the plot.
- **font_size** (`int`): Font size for all text elements in the plot.
- **y_lim** (`tuple`): The limits for the Y-axis (min, max).
- **y_tick_interval**, **x_tick_interval** (`int`): Interval between ticks on the Y-axis and X-axis respectively.
- **is_grid** (`bool`): If True, displays a grid on the plot.
- **is_legend** (`bool`): If True, displays a legend on the plot.
- **is_label** (`bool`): If True, labels are displayed alongside lines.
- **save_path** (`str`, optional): Path to save the figure file.
- **is_show** (`bool`): If True, displays the plot.

_Code Example_

```python
import pandas as pd
import multidataplotting as mdp

dates = pd.date_range(start='2020-01-01', periods=1000)
data = pd.Series(np.random.randn(1000).cumsum(), index=dates)
legend_labels = {'original': 'Data', 'max': 'Max Roll', 'min': 'Min Roll', 'avg': 'Average Roll'}
mdp.plot_rolling_series(data, rolling_period=10, legend_labels=legend_labels, x_tick_interval=90, y_tick_interval=3, is_grid=False, font_name='Times New Roman', font_size=14, is_label=True)

```

![alt text](https://github.com/wwang487/MultiDataPlotting/blob/main/picture/rolling.png?raw=true)

### Two-Colored Time Series Plot

The `plot_two_colored_time_series` function in our data visualization toolkit offers a distinctive way to visualize time series data by changing the color of the plot line based on a specified threshold value. This is particularly useful for highlighting segments of the data that exceed or fall below critical levels, such as temperature thresholds, stock price targets, or performance benchmarks.

_Functionality_

This function plots a time series where the line color changes above and below a predefined threshold. It intelligently divides segments that cross the threshold, ensuring that the transition between colors accurately represents the point at which the data crosses this boundary.

_Parameters_
- **data** (pandas Series): A pandas Series with a DateTime index and one column of values to plot.
- **threshold** (float): The value at which the plot line color changes.
- **title** (str): Title of the plot.
- **xlabel**, **ylabel** (str): Labels for the x-axis and y-axis.
- **color_above**, **color_below** (str): Colors for the line segments above and below the threshold, respectively.
- **line_style** (str): Style of the plot line (e.g., '-', '--', '-.', ':').
- **line_width** (float): Width of the plot line.
- **threshold_color** (str): Color of the threshold line.
- **threshold_style** (str): Style of the threshold line (e.g., '-', '--').
- **threshold_width** (float): Thickness of the threshold line.
- **fig_size** (tuple): Dimensions of the figure.
- **x_tick_interval**, **y_tick_interval** (float): Interval between ticks on the x-axis and y-axis.
- **tick_font_name**, **tick_font_size** (str, int): Font name and size for the tick labels.
- **is_legend** (bool): Whether to display the legend.
- **legend_text** (str): Text for the legend entries.
- **save_path** (str, optional): File path to save the plot image, if desired.
- **is_show** (bool, optional): Whether to display the plot. Defaults to True if not specified.

_Example Usage_
```python
import pandas as pd
import numpy as np
import multidataplotting as mdp
# Generating sample data
dates = pd.date_range(start="2021-01-01", periods=100)
values = np.random.normal(loc=52, scale=5, size=100)  # Generate random data
data = pd.Series(values, index=dates)
mdp.plot_two_colored_time_series(data, threshold=56, title="Temperature Over Time", xlabel="Time", ylabel="Temperature (Â°F)",
                             x_tick_interval=10, y_tick_interval=2, tick_font_name='Arial', tick_font_size=10,
                             color_above='red', color_below='black', line_style='-', line_width=1.5,
                             threshold_color='gray', threshold_style=':', threshold_width=3)
```

![alt text](https://github.com/wwang487/MultiDataPlotting/blob/main/picture/two_color.png?raw=true)

### Scatter Plot with Threshold

The `plot_scatter_with_threshold` function in our visualization library creates a scatter plot where points are colored differently based on their position relative to a specified threshold value. This function is ideal for highlighting distributions and differences in datasets relative to a critical value.

_Functionality_

This function generates a scatter plot with two distinct color mappings for data points lying above and below a given threshold. The saturation of colors indicates the distance from the threshold, providing a clear visual representation of how data points deviate from a critical value. Additionally, a threshold line is drawn to visually segregate the data, enhancing the interpretability of the plot.

_Parameters_
- **data** (pandas DataFrame): Contains the data with 'x' and 'y' columns to be plotted.
- **threshold** (float): The critical value against which data points are evaluated and colored.
- **title** (str): The title of the plot.
- **xlabel**, **ylabel** (str): Labels for the x-axis and y-axis.
- **edge_color** (str, optional): Color of the edges of scatter plot markers.
- **base_color_above**, **base_color_below** (str): Color maps for points above and below the threshold.
- **fig_size** (tuple): The dimensions of the figure.
- **is_legend** (bool): Whether to display the legend.
- **legend_font_size** (int): Font size for the legend text.
- **legend_font_name** (str): Font family for the legend text.
- **line_color** (str): Color of the threshold line.
- **line_style** (str): Style of the threshold line (e.g., '-', '--').
- **line_thickness** (float): Thickness of the threshold line.
- **label_font_size** (int): Font size for the axis labels.
- **label_font_name** (str): Font family for the axis labels.
- **save_path** (str, optional): Path to save the plot image, if desired.
- **is_show** (bool, optional): Set to True to display the plot. Defaults to True if not specified.

_Example Usage_
```python
import pandas as pd
import numpy as np
import multidataplotting as mdp

# Example usage
df = pd.DataFrame({
    'x': np.random.rand(100),
    'y': np.random.randn(100)  # Simulated values centered around zero
})
mdp.plot_scatter_with_threshold(df, threshold=0, title="Scatter Plot Example", xlabel="Random X", ylabel="Random Y",
                            base_color_above='Blues', base_color_below='Reds')

```

![alt text](https://github.com/wwang487/MultiDataPlotting/blob/main/picture/thresh_scatter.png?raw=true)

### Plotting Histograms

The `plot_histograms` function from the multidataprocessing package allows users to plot multiple histograms in a single figure. This feature is particularly useful for comparing the distributions of several datasets simultaneously, providing insights into variability, skewness, or similarity among the datasets.

_Functionality_

`plot_histograms` is ideal for statistical analysis and data exploration, helping to visualize and compare the frequency distributions of multiple groups or variables within the same graphical context. It's especially useful in fields like biostatistics, market research, and any area where distribution comparison is crucial.

_Parameters_

- **list_of_lists** (list of lists): A list where each sublist contains numeric data for one histogram.
- **titles** (list of str): Titles for each histogram. Must match the number of sublists in list_of_lists.
- **xlabels** (str or list of str, optional): X-axis labels for each histogram. Can be a single string or a list of strings matching the number of histograms.
- **ylabels** (str or list of str, optional): Y-axis labels for each histogram. Can be a single string or a list of strings matching the number of histograms.
- **bins** (int, optional): Number of bins for the histograms. Default is 10.
- **color** (str, optional): Color of the histogram bars. Default is 'blue'.
- **edgecolor** (str, optional): Color of the bar edges. Default is 'black'.
- **fig_size** (tuple, optional): Size of the figure, in inches. Default is (10, 6).
- **tick_fontname** (str, optional): Font name for the tick labels. Default is 'Arial'.
- **tick_fontsize** (int, optional): Font size for the tick labels. Default is 12.
- **title_fontsize** (int, optional): Font size for the titles of each plot. Default is 14.
- **label_fontsize** (int, optional): Font size for the labels. Default is 14.
- **value_range** (list, optional): Specific range of values to include in each histogram as [min, max].
- **line_color** (str, optional): Color of the mean line within each histogram. Default is 'red'.
- **show_all_xticklabels** (bool, optional): Whether to show all x-axis tick labels. Default is True.
- **line_style** (str, optional): Style of the mean line, such as '--' for dashed lines. Default is '--'.
- **line_width** (float, optional): Width of the mean line. Default is 2.
- **is_legend** (bool, optional): Whether to include a legend in the plots. Default is False.
- **unit** (str, optional): Unit of measurement for the data, useful for annotations. Default is 'm'.
- **is_log** (bool, optional): Whether to use a logarithmic scale for the y-axis. Default is False.
- **is_log_x** (bool, optional): Whether to use a logarithmic scale for the x-axis. Default is False.
- **is_fixed_y_range** (bool, optional): Whether to fix the y-axis range across all plots. Default is False.
- **y_range** (list, optional): Specific y-axis limits as [min, max] if is_fixed_y_range is True.
- **is_mean_value** (bool, optional): Whether to display the mean value on the histograms. Default is True.
- **is_scaled** (bool, optional): Whether to scale the data by a factor. Default is False.
- **scale_factor** (float, optional): Factor by which to scale the data if is_scaled is True. Default is 10.
- **save_path** (str, optional): File path where the plot will be saved, if desired.
- **is_show** (bool, optional): Whether to display the plot on the screen. Default is True.
- **is_save** (bool, optional): Whether to save the plot to a file. Default is True.
- **transparent_bg** (bool, optional): Whether the background of the saved figure should be transparent. Default is True.
- **hspace** (float, optional): Space between subplots, in normalized subplot coordinates. Default is 0.1.
- **label_sep** (str, optional): Separator for splitting the labels. Default is '_'.

_Code Example_

```python
import numpy as np
import multidataplotting as mdp

# Generate random age data for four groups
group1 = np.random.normal(loc=30, scale=5, size=100)  # Mean age 30, SD 5
group2 = np.random.normal(loc=40, scale=5, size=100)  # Mean age 40, SD 5
group3 = np.random.normal(loc=20, scale=5, size=100)  # Mean age 20, SD 5
group4 = np.random.normal(loc=50, scale=5, size=100)  # Mean age 50, SD 5
list_of_lists = [group1, group2, group3, group4]

# Titles for each histogram
titles = ["Group 1: 20s", "Group 2: 30s", "Group 3: 40s", "Group 4: 50s"]
xlabels = ['A', 'B', 'C', 'D']
ylabels = 'Frequency (%)'
# Plotting histograms
mdp.plot_histograms(list_of_lists, titles=titles, xlabels = None, ylabels = ylabels, is_show=True, hspace = 0.2, color = '#edf8b1')
```
![alt text](https://github.com/wwang487/MultiDataPlotting/blob/main/picture/hists.png?raw=true)

### Drawing Categorical Bar and Curve Plots

The `draw_cat_bar_curveplots` function from the multidataprocessing package combines categorical bar plots with overlaid curve plots. This feature allows for a detailed comparative analysis of primary data alongside secondary trends within the same visual context, making it ideal for simultaneous examination of discrete and continuous data aspects.

_Functionality_

This function is perfect for applications where understanding the relationship between categorical and continuous data is essential. It can be used in market research for product comparison across different time points, financial analysis showing categorical expenditure against revenue trends, or any scenario where integrated visualization provides deeper insights.

_Parameters_

- **main_result** (dict): Main categorical data to be plotted as bars. Keys should be categories