jitterStripDensityP​lot

A MATLAB function for creating enhanced jitter strip plots with density-based coloring.

# Jitter Strip Density Plot Function

A MATLAB function for creating enhanced jitter strip plots with density-based coloring.

## Author
**M.N Hidayat**  
Email: [e-mail]

## Function: `jitterStripDensityPlot`

Creates publication-quality jitter strip plots with kernel density estimation coloring, showing individual data points colored by their local density.

### Features
- **Density Coloring**: Points are colored based on local density using kernel density estimation (KSDENSITY)
- **Custom Colormap**: Built-in colormap from dark purple/black (low density) to bright yellow (high density)
- **Median Visualization**: Horizontal lines and numeric labels for median values
- **Jitter Avoidance**: Horizontal jitter prevents overplotting of points
- **Flexible Options**: Numerous customization parameters
- **Professional Output**: Publication-ready formatting

### Syntax
```matlab
[hFig, hScatter, hMed] = jitterStripDensityPlot(data, groupNames)
[hFig, hScatter, hMed] = jitterStripDensityPlot(data, groupNames, Name, Value)
```

### Input Arguments

#### Required:
- `data` - Cell array of vectors, each containing data for one group
- `groupNames` - Cell array of strings for group labels

#### Optional Name-Value Pairs:

| Parameter | Description | Default |
|-----------|-------------|---------|
| `'Colormap'` | Colormap matrix (n×3) for density coloring | Built-in purple-black to red-yellow gradient |
    | `'JitterAmount'` | Amount of horizontal jitter (0-1) | 0.15 |
    | `'MarkerSize'` | Size of scatter markers | 20 |
    | `'MarkerAlpha'` | Transparency of markers (0-1) | 0.7 |
    | `'MedianLineWidth'` | Width of median lines | 2 |
    | `'MedianLineColor'` | Color of median lines | 'r' (red) |
    | `'MedianLineStyle'` | Style of median lines | '-' |
    | `'ShowColorbar'` | Show colorbar (true/false) | true |
    | `'ColorbarLabel'` | Label for colorbar | 'Density' |
        | `'GridOn'` | Show grid (true/false) | true |
        | `'BoxOn'` | Show box around plot (true/false) | true |
        | `'XLabel'` | X-axis label | '' |
        | `'YLabel'` | Y-axis label | 'Value' |
        | `'Title'` | Plot title | 'Jitter Strip Plot with Density Coloring' |
        | `'FontSize'` | Base font size | 12 |
        | `'Parent'` | Parent axes or figure | New figure |
        
        ### Output Arguments
        - `hFig` - Handle to the figure
        - `hScatter` - Cell array of scatter plot handles for each group
        - `hMed` - Array of line handles for median lines
        
        ### Examples
        
        #### Basic Usage
        ```matlab
        % Create sample data
        groupNames = {'Control', 'Treatment A', 'Treatment B'};
        nGroups = length(groupNames);
        nPerGroup = 200;
        data = cell(nGroups,1);
        for i = 1:nGroups
            data{i} = randn(nPerGroup,1) + i*0.5;
        end
        
        % Create basic plot
        jitterStripDensityPlot(data, groupNames);
        ```
        
        #### Customized Plot
        ```matlab
        jitterStripDensityPlot(data, groupNames, ...
            'Colormap', parula(256), ...
            'JitterAmount', 0.2, ...
            'MarkerSize', 30, ...
            'MedianLineColor', 'blue', ...
            'Title', 'Experimental Results', ...
            'YLabel', 'Response Variable');
        ```
        
        #### With Real Data
        ```matlab
        % Load your data
        T = readtable('your_data.csv');
        
        % Prepare data groups
        dataGroups = {T.variable1, T.variable2, T.variable3};
        groupNames = {'Condition 1', 'Condition 2', 'Condition 3'};
        
        % Create plot
        jitterStripDensityPlot(dataGroups, groupNames, ...
            'YLabel', 'Measurement Units', ...
            'Title', 'Data Distribution by Condition');
        ```
        
        #### Plot in Specific Axes
        ```matlab
        figure;
        subplot(1,2,1);
        jitterStripDensityPlot(data1, groups1, 'Parent', gca, 'Title', 'Dataset A');
        
        subplot(1,2,2);
        jitterStripDensityPlot(data2, groups2, 'Parent', gca, 'Title', 'Dataset B');
        ```
        
        #### Get Handles for Further Customization
        ```matlab
        [hFig, hScatter, hMed] = jitterStripDensityPlot(data, groupNames);
        
        % Customize scatter plots
        for i = 1:length(hScatter)
            if ~isempty(hScatter{i})
                set(hScatter{i}, 'MarkerEdgeAlpha', 0.5);
            end
        end
        
        % Customize median lines
        set(hMed, 'LineWidth', 3, 'LineStyle', '--');
        ```
        
        ### Built-in Colormap
        The default colormap progresses through:
        1. **Black** (very low density)
        2. **Dark purple** (low density)
        3. **Purple** (medium-low density)
        4. **Light purple** (medium density)
        5. **Red** (medium-high density)
        6. **Orange** (high density)
        7. **Bright yellow** (very high density)