add: beta probability distribution

[Calluumm]

Adds a beta distribution to stats
This is a modernisation/continuation of #286 all credit to the original author.

Comparatively to #286 :
Tests are standardised and modernised to current stdlib standards
Beta calculations are moved to the gamma specialfunctions module
Documentation changed to modern standards

Build tests passed fine, calculations matched that of scipy

I think beta calculations are best suited in the gamma specialfunctions rather than their own file or within the beta distribution module for code efficiency and later use
@sebastian-mutz

[Calluumm]

locally wrote it relying on the changes made in #1133 will leave as draft for now

[codecov]

Codecov Report

❌ Patch coverage is 0% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 67.82%. Comparing base (b6086ce) to head (8bf15dc).
⚠️ Report is 20 commits behind head on master.

Files with missing lines	Patch %	Lines
...ample/stats_distribution_beta/example_beta_rvs.f90	0.00%	14 Missing ⚠️
...ample/stats_distribution_beta/example_beta_cdf.f90	0.00%	9 Missing ⚠️
...ample/stats_distribution_beta/example_beta_pdf.f90	0.00%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1139      +/-   ##
==========================================
- Coverage   68.05%   67.82%   -0.24%     
==========================================
  Files         402      406       +4     
  Lines       12839    12882      +43     
  Branches     1383     1383              
==========================================
- Hits         8738     8737       -1     
- Misses       4101     4145      +44     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds a Beta probability distribution implementation to stats, backed by new Beta-related special functions colocated in stdlib_specialfunctions_gamma, along with tests, examples, and specification docs.

Changes:

• Introduces stdlib_stats_distribution_beta with rvs_beta, pdf_beta, and cdf_beta (real + complex overloads).
• Adds beta, log_beta, and incomplete_beta to stdlib_specialfunctions_gamma, plus corresponding unit tests.
• Wires new module/tests/examples/docs into CMake and the specs index.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/stats/stdlib_stats_distribution_beta.fypp	New Beta distribution implementation (rvs/pdf/cdf).
src/specialfunctions/stdlib_specialfunctions_gamma.fypp	Adds Beta-related special functions used by the distribution.
test/stats/test_distribution_beta.fypp	New Beta distribution test coverage.
test/stats/CMakeLists.txt	Registers the new Beta distribution test.
test/specialfunctions/test_specialfunctions_gamma.fypp	Adds tests for beta, log_beta, and incomplete_beta.
src/stats/CMakeLists.txt	Includes the new Beta distribution module in the stats build.
example/stats_distribution_beta/example_beta_rvs.f90	Example usage for rvs_beta.
example/stats_distribution_beta/example_beta_pdf.f90	Example usage for pdf_beta.
example/stats_distribution_beta/example_beta_cdf.f90	Example usage for cdf_beta.
example/stats_distribution_beta/CMakeLists.txt	Builds the new Beta distribution examples.
example/CMakeLists.txt	Adds the Beta distribution examples subdirectory.
doc/specs/stdlib_stats_distribution_beta.md	New Beta distribution specification page.
doc/specs/index.md	Adds Beta distribution to the specs index.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[sebastian-mutz]

Thanks, @Calluumm. Looks good and consistent with gamma and previous distribution modules.

• Since we moved away from normal statistical notation, I agree with the use of a and b instead of alpha and beta. (The former seems common; see Maltab and SciPy).
• I agree with Jose about the elemental declaration.
• Regarding the additions to the special functions gamma module: I support this implementation. Since beta is closely related to gamma, I think this works. I think the risk of creating confusion down the line is minimal, esp. if the person looking at the code has some understanding of these distributions.

[Calluumm]

This commit should address the above suggestions they can be pure elementals yes, locally passed everything

[jvdp1]

Thank you @Calluumm for this PR. The PR is taking a good shape. Please find below some suggestions.

[jvdp1]

@jalvesz were these values not defined somewhere in stdlib? Should it be preferable to import them or to re-define them here?

[jalvesz]

Yes, they are defined in stdlib_constants, either they could be used directly in the code, or here to define the local zero and one parameters. The advantage I see with this is that the internal implementation has less fypp verbosity.

[Calluumm]

I think I've resolved everything you suggested with this commit @jalvesz

@jvdp1 I made amends to the cdf example and subsequently the pdf example which had the same issues
ive pushed through the majority of the other suggestions too without problem I'm just stuck on the error handling changes to the beta distribution test, I've left comments on the suggestions directly