<!-- README.md is generated from README.Rmd. Please edit that file -->



<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/sshist)](https://CRAN.R-project.org/package=sshist)
[![CRAN downloads](https://cranlogs.r-pkg.org/badges/grand-total/sshist)](https://CRAN.R-project.org/package=sshist)
[![CRAN downloads](https://cranlogs.r-pkg.org/badges/sshist)](https://CRAN.R-project.org/package=sshist)
[![CRAN downloads](https://cranlogs.r-pkg.org/badges/last-week/sshist)](https://CRAN.R-project.org/package=sshist)
[![CRAN downloads](https://cranlogs.r-pkg.org/badges/last-day/sshist)](https://CRAN.R-project.org/package=sshist)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/celebithil/sshist)
<!-- badges: end -->

# sshist: Optimal Density Estimation via Shimazaki-Shinomoto Method

The `sshist` package implements state-of-the-art algorithms for optimal non-parametric density estimation based on the framework developed by Hideaki Shimazaki and Shigeru Shinomoto (2007, 2010). The core optimization principle is to find the parameters that minimize the expected Mean Integrated Squared Error (MISE) between the estimated density and the true, unknown underlying distribution. 

By utilizing purely data-driven optimization, this package avoids subjective choices for bin widths or kernel bandwidths, making it highly robust—especially for data with complex, multimodal, or heavy-tailed structures.

## Key Features

- **Data-Driven Optimization:** Replaces subjective "rules of thumb" (like Sturges' or Freedman-Diaconis' rules) with objective minimizers of the MISE cost function.
- **Multi-Dimensional Support:** Provides full capability for both 1D univariate and 2D bivariate distributions.
- **Fixed and Variable Estimators:** Offers both classical global estimators and advanced locally adaptive variable bandwidth selectors (based on Abramson's scaling method).
- **High Performance:** Designed to evaluate cost functions efficiently, leveraging analytical formulations and fast backend calculations.

## Summary of Available Functions

| Function | Estimator Type | Dimension | Bandwidth / Bin Selection |
|:---|:---|:---|:---|
| `sshist` | Histogram | 1D | Fixed (single optimal bin width) |
| `sshist_2d` | Histogram | 2D | Fixed independent bin width per axis |
| `sskernel` | Kernel Density | 1D | Fixed global bandwidth |
| `ssvkernel` | Kernel Density | 1D | Locally adaptive variable bandwidth |
| `sskernel2d` | Kernel Density | 2D | Fixed global isotropic bandwidth |
| `ssvkernel2d` | Kernel Density | 2D | Locally adaptive bivariate bandwidth |

## Installation

You can install the stable version of `sshist` from CRAN:

```r
install.packages("sshist")
```

Alternatively, you can install the development version directly from GitHub using `devtools`:

```r
# install.packages("devtools")
devtools::install_github("celebithil/sshist")
```

## References

- Shimazaki, H. and Shinomoto, S. (2007). A method for selecting the bin size of a time histogram. *Neural Computation*, **19**(6), 1503–1527. [doi:10.1162/neco.2007.19.6.1503](https://doi.org/10.1162/neco.2007.19.6.1503)
- Shimazaki, H. and Shinomoto, S. (2010). Kernel bandwidth optimization in spike rate estimation. *Journal of Computational Neuroscience*, **29**(1-2), 171–182. [doi:10.1007/s10827-009-0180-4](https://doi.org/10.1007/s10827-009-0180-4)

- https://www.neuralengine.org/res/histogram.html

- https://github.com/shimazaki/density_estimation

- https://s-shinomoto.com/toolbox/sshist/hist.html
