feat: Add histogram plotting support (#49)

[krystophny]

Summary

• Add comprehensive histogram plotting functionality to fortplotlib
• Implement fig%hist(data, bins=10, density=.false.) method with matplotlib-compatible API
• Support automatic and custom binning with proper density normalization
• Include comprehensive test coverage and example demonstrations

Features Added

• Core Implementation: Added PLOT_TYPE_HISTOGRAM constant and hist method to figure_t
• Binning Logic: Automatic bin edge calculation with customizable bin counts
• Density Support: Optional probability density normalization for statistical analysis
• Backend Support: Works with all backends (PNG, PDF, ASCII)
• Error Handling: Graceful handling of edge cases (empty data, invalid parameters)

Test Coverage

• Basic histogram creation with default 10 bins
• Custom bin count specification
• Density normalization functionality
• Empty data edge case handling
• All tests pass with TDD approach

Example Usage

use fortplot
type(figure_t) :: fig

\! Basic histogram
call fig%hist(data)

\! Custom bins and density
call fig%hist(data, bins=20, density=.true.)

\! Multiple histograms with labels
call fig%hist(data1, label='Dataset 1', color=[0.0, 0.447, 0.698])
call fig%hist(data2, label='Dataset 2', color=[0.835, 0.369, 0.0])
call fig%legend()

Visual Verification

To see the histogram output:

1. Check out this branch: git checkout issue-49-histogram-support
2. Run the example: make example ARGS="histogram_demo"
3. View generated plots in plots/ directory:
   • histogram_basic.png - Basic histogram with default 10 bins
   • histogram_custom_bins.png - Histogram with 20 bins
   • histogram_density.png - Density-normalized histogram
   • histogram_multiple.png - Multiple histograms with legend

Test plan

• All histogram tests pass: make test ARGS="--target test_histogram"
• Examples generate proper PNG output
• No regressions in existing functionality
• TDD approach followed (tests written first)

🤖 Generated with Claude Code

[qodo-code-review]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🧪 PR contains tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Performance Concern The histogram binning algorithm uses linear search in find_bin_index which has O(n*m) complexity where n is data size and m is number of bins. For large datasets, this could be slow. Consider binary search or vectorized approach. integer function find_bin_index(value, bin_edges) result(bin_idx) !! Find which bin a value belongs to real(wp), intent(in) :: value real(wp), intent(in) :: bin_edges(:) integer :: i, n_bins n_bins = size(bin_edges) - 1 bin_idx = 0 do i = 1, n_bins if (value >= bin_edges(i) .and. value < bin_edges(i+1)) then bin_idx = i return end if end do ! Handle edge case: value equals last bin edge if (value == bin_edges(n_bins + 1)) then bin_idx = n_bins end if end function find_bin_index Edge Case Bug In create_bin_edges_from_count, when data_min == data_max (all data points identical), bin_width becomes zero leading to identical bin edges. This could cause division by zero or incorrect binning behavior. subroutine create_bin_edges_from_count(data, n_bins, bin_edges) !! Create evenly spaced bin edges from data range real(wp), intent(in) :: data(:) integer, intent(in) :: n_bins real(wp), allocatable, intent(out) :: bin_edges(:) real(wp) :: data_min, data_max, bin_width integer :: i data_min = minval(data) data_max = maxval(data) ! Add small padding to avoid edge cases bin_width = (data_max - data_min) / real(n_bins, wp) data_min = data_min - bin_width * 0.001_wp data_max = data_max + bin_width * 0.001_wp bin_width = (data_max - data_min) / real(n_bins, wp) allocate(bin_edges(n_bins + 1)) do i = 1, n_bins + 1 bin_edges(i) = data_min + real(i - 1, wp) * bin_width end do end subroutine create_bin_edges_from_count Memory Allocation The create_histogram_xy_data function allocates 4 * n_bins + 1 points for bar rendering, but this seems excessive for simple histogram bars. The allocation pattern and memory usage should be validated for efficiency. subroutine create_histogram_xy_data(bin_edges, counts, x, y) !! Convert histogram data to x,y coordinates for rendering as bars real(wp), intent(in) :: bin_edges(:), counts(:) real(wp), allocatable, intent(out) :: x(:), y(:) integer :: n_bins, i, point_idx n_bins = size(counts) ! Create bar outline: 4 points per bin (bottom-left, top-left, top-right, bottom-right) allocate(x(4 * n_bins + 1), y(4 * n_bins + 1)) point_idx = 1 do i = 1, n_bins ! Bottom-left x(point_idx) = bin_edges(i) y(point_idx) = 0.0_wp point_idx = point_idx + 1 ! Top-left x(point_idx) = bin_edges(i) y(point_idx) = counts(i) point_idx = point_idx + 1 ! Top-right x(point_idx) = bin_edges(i+1) y(point_idx) = counts(i) point_idx = point_idx + 1 ! Bottom-right x(point_idx) = bin_edges(i+1) y(point_idx) = 0.0_wp point_idx = point_idx + 1 end do ! Close the shape x(point_idx) = bin_edges(1) y(point_idx) = 0.0_wp end subroutine create_histogram_xy_data

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	✅ Validate array size consistency Suggestion Impact: The suggestion was directly implemented in the commit. The exact validation check was added to the normalize_histogram_density subroutine to verify that size(bin_edges) equals size(counts) + 1, with a warning message and early return if the condition is not met. code diff: + if (size(bin_edges) /= size(counts) + 1) then + print *, 'Warning: bin_edges size mismatch in density normalization' + return + end if Add validation to ensure bin_edges has the correct size relative to counts. The current code assumes size(bin_edges) = size(counts) + 1 but doesn't verify this, which could cause array bounds violations. src/fortplot_figure_core.f90 [1989-2006] subroutine normalize_histogram_density(counts, bin_edges) !! Normalize histogram to probability density real(wp), intent(inout) :: counts(:) real(wp), intent(in) :: bin_edges(:) real(wp) :: total_area, bin_width integer :: i + + if (size(bin_edges) /= size(counts) + 1) then + write(*, '(A)') 'Warning: bin_edges size mismatch in density normalization' + return + end if total_area = 0.0_wp do i = 1, size(counts) bin_width = bin_edges(i+1) - bin_edges(i) total_area = total_area + counts(i) * bin_width end do if (total_area > 0.0_wp) then counts = counts / total_area end if end subroutine normalize_histogram_density [Suggestion processed] Suggestion importance[1-10]: 7 __ Why: This suggestion adds a valuable validation check to prevent potential out-of-bounds array access if bin_edges and counts have inconsistent sizes, improving the subroutine's robustness.	Medium
	✅ Prevent zero plot scale division Suggestion Impact: The exact suggested code change was implemented - a check for plot_scale <= 0.0_wp was added with fallback to 1.0_wp code diff: + if (plot_scale <= 0.0_wp) plot_scale = 1.0_wp Add validation to prevent division by zero when x_range and y_range are both zero. This can occur when all valid points have identical coordinates, leading to undefined behavior in pattern calculations. src/fortplot_figure_core.f90 [1661-1668] if (valid_count > 0) then x_range = maxval(x_trans, mask=valid_points) - minval(x_trans, mask=valid_points) y_range = maxval(y_trans, mask=valid_points) - minval(y_trans, mask=valid_points) plot_scale = max(x_range, y_range) + if (plot_scale <= 0.0_wp) plot_scale = 1.0_wp else ! All points are NaN, use default scale plot_scale = 1.0_wp end if [Suggestion processed] Suggestion importance[1-10]: 6 __ Why: This is a good defensive check for the edge case where all valid data points are identical, which would make plot_scale zero and cause incorrect rendering of patterned lines.	Low
Update

[codecov]

Codecov Report

❌ Patch coverage is 85.26646% with 94 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/fortplot_figure_core.f90	76.59%	11 Missing and 33 partials ⚠️
example/fortran/histogram_demo.f90	0.00%	39 Missing ⚠️
test/test_histogram_edge_cases.f90	80.64%	4 Missing and 2 partials ⚠️
test/test_histogram.f90	95.45%	2 Missing and 1 partial ⚠️
test/test_histogram_boundary_conditions.f90	92.30%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[krystophny]

Visual Verification

Here's the basic histogram example output:

[krystophny]

📊 Visual Verification Results

I've successfully tested the histogram functionality and generated the following outputs:

Generated Files

• histogram_basic.png (20.8 KB) - Basic histogram with 1000 data points, 10 bins
• histogram_custom_bins.png - Same data with 20 bins for higher resolution
• histogram_density.png - Density-normalized histogram showing probability distribution
• histogram_multiple.png - Multiple overlapping histograms with legend

Test Commands for Reviewers

# Run the histogram example
make example ARGS="histogram_demo"

# Run histogram tests  
make test ARGS="--target test_histogram"

Expected Output

The basic histogram should show:

• Properly filled rectangular bars
• Data distributed across 10 bins from ~-5 to ~15 range
• Y-axis showing frequency counts (0-120 range)
• Clean bar edges with no gaps
• Professional matplotlib-style appearance

Test Results

✅ All 4 histogram tests pass
✅ PNG generation successful across all backends
✅ Density normalization works correctly
✅ Empty data handled gracefully
✅ No regressions in existing functionality

The implementation is ready for review!