coco_pipe.report.api
====================

.. py:module:: coco_pipe.report.api

.. autoapi-nested-parse::

   High-level API for generating Reports from various sources.



Functions
---------

.. autoapisummary::

   coco_pipe.report.api.from_container
   coco_pipe.report.api.from_bids
   coco_pipe.report.api.from_tabular
   coco_pipe.report.api.from_embeddings
   coco_pipe.report.api.from_reductions


Module Contents
---------------

.. py:function:: from_container(container: coco_pipe.io.structures.DataContainer, title: str = 'Analysis Report', config: Optional[Dict] = None, raw_preview: bool = True) -> coco_pipe.report.core.Report

   Create a standard report from a DataContainer.

   :param container: The data to summarize.
   :type container: DataContainer
   :param title: Report title.
   :type title: str
   :param config: Configuration/provenance info.
   :type config: Dict, optional
   :param raw_preview: If True, adds an interactive raw data scroller. Default True.
   :type raw_preview: bool

   :returns: A Report object with a "Data Overview" section added.
   :rtype: Report

   .. rubric:: Examples

   >>> ds = TabularDataset("data.csv")
   >>> container = ds.load()
   >>> report = from_container(container)
   >>> report.save("report.html")


.. py:function:: from_bids(root: Union[str, pathlib.Path], task: Optional[str] = None, **kwargs) -> coco_pipe.report.core.Report

   Auto-generate a report from a BIDS dataset.

   :param root: BIDS root directory.
   :type root: str or Path
   :param task: Task name.
   :type task: str, optional
   :param \*\*kwargs: Additional arguments passed to BIDSDataset (e.g., session, subjects).

   :returns: A Report object with a "Data Overview" section added.
   :rtype: Report

   .. rubric:: Examples

   >>> report = from_bids("/path/to/bids")
   >>> report.save("report.html")


.. py:function:: from_tabular(path: Union[str, pathlib.Path], **kwargs) -> coco_pipe.report.core.Report

   Auto-generate a report from a tabular file (CSV/Excel).

   :param path: Path to file.
   :type path: str or Path
   :param \*\*kwargs: Additional arguments passed to TabularDataset (e.g., target_col, clean).

   :rtype: Report


.. py:function:: from_embeddings(path: Union[str, pathlib.Path], **kwargs) -> coco_pipe.report.core.Report

   Auto-generate a report from a directory of embeddings.

   :param path: Directory containing embedding files.
   :type path: str or Path
   :param \*\*kwargs: Additional arguments passed to EmbeddingDataset.

   :rtype: Report

   .. rubric:: Examples

   >>> report = from_embeddings("/path/to/embeddings")
   >>> report.save("report.html")


.. py:function:: from_reductions(reductions: List[Any], container: Optional[coco_pipe.io.structures.DataContainer] = None, embeddings: Optional[List[numpy.ndarray]] = None, labels: Optional[numpy.ndarray] = None, metadata: Optional[Dict[str, Any]] = None, times: Optional[numpy.ndarray] = None, title: str = 'DimReduction Comparison', config: Optional[Dict] = None) -> coco_pipe.report.core.Report

   Create a comparative report from multiple dimensionality reduction results.

   :param reductions: List of scored reduction objects implementing ``get_summary()``.
   :type reductions: List[Any]
   :param container: Original data container to include in "Data Overview".
   :type container: DataContainer, optional
   :param embeddings: Explicit embedding payloads aligned with ``reductions``.
   :type embeddings: list of np.ndarray, optional
   :param labels: Optional labels aligned with each embedding.
   :type labels: np.ndarray, optional
   :param metadata: Optional column-oriented metadata aligned with 2D embeddings.
   :type metadata: dict, optional
   :param times: Optional time axis aligned with 3D trajectory embeddings.
   :type times: np.ndarray, optional
   :param title: Report title.
   :type title: str

   :returns: Report with Data Overview (if valid) and one section per reduction.
   :rtype: Report

   .. rubric:: Notes

   Reduction summaries no longer carry cached embedding payloads. Pass
   ``embeddings`` explicitly when the report should render embedding or
   trajectory plots.

   .. rubric:: Examples

   >>> report = from_reductions([pca, tsne], embeddings=[pca_emb, tsne_emb])
   >>> report.save("report.html")