Utils API Reference
===================
.. automodule:: scistanpy.utils
   :undoc-members:
   :show-inheritance:

Lazy Import System
------------------

To speed up initial import times, SciStanPy provides a lazy import system that defers loading of optional dependencies until they are actually needed.

.. autofunction:: scistanpy.utils.lazy_import

.. autoclass:: scistanpy.utils.LazyObjectProxy
   :members:
   :undoc-members:
   :show-inheritance:

.. autofunction:: scistanpy.utils.lazy_import_from

Backend Selection
-----------------
Many SciStanPy operations can be performed using either NumPy or PyTorch as the underlying numerical backend. The utility function below automates the selection of the appropriate backend based on the input data type.

.. autofunction:: scistanpy.utils.choose_module

Numerical Stability
-------------------
With probabilistic computations, numerical stability is often a concern. The following utility function provides a numerically stable implementation of the sigmoid function.

.. autofunction:: scistanpy.utils.stable_sigmoid

Dask Integration
----------------

For particularly large models, sampling via Stan can yield more data than cat fit in memory. To handle such cases, SciStanPy integrates Dask to enable out-of-core computation and parallel processing, particularly with the :py:class:`~scistanpy.model.results.hmc.SampleResults` class. The following utility functions assist with Dask integration.

.. autofunction:: scistanpy.utils.get_chunk_shape
   :noindex:

.. autoclass:: scistanpy.utils.az_dask
   :members:
   :undoc-members:
   :show-inheritance: