coco_pipe.report.descriptor_qc
==============================

.. py:module:: coco_pipe.report.descriptor_qc

.. autoapi-nested-parse::

   Descriptor QC report builders.

   Assembles the standard subject-level and dataset-level descriptor QC HTML
   reports from the dataframes produced by
   :mod:`coco_pipe.descriptors.qc` (family summaries, missingness, failure
   summaries, etc.) and figure paths produced by descriptor-QC viz helpers.



Functions
---------

.. autoapisummary::

   coco_pipe.report.descriptor_qc.generate_descriptor_subject_report
   coco_pipe.report.descriptor_qc.generate_descriptor_dataset_report


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

.. py:function:: generate_descriptor_subject_report(output_path, overview_df, flags_df, failure_summary_df, feature_missingness_df, family_summary_df, figure_paths, asset_urls = None)

   Build the per-shard (subject/session/condition) descriptor QC report.

   :param output_path: Destination ``.html`` path. Parent directories are created.
   :param asset_urls: Passed through to :class:`~coco_pipe.report.core.Report`. Use
                      ``"inline"`` to embed Plotly/Tailwind/pako so the saved HTML renders
                      offline (file://) instead of referencing external CDNs.
   :param overview_df: Single-row dataframe with ``Subject``, ``Session``, ``Condition``,
                       and summary metrics for the shard.
   :param flags_df: QC flags raised for this shard (e.g. from
                    :func:`coco_pipe.io.quality.make_qc_flag`).
   :param failure_summary_df: Combined extraction-failure summary, e.g. the ``"combined"`` frame
                              from :func:`coco_pipe.descriptors.qc.summarize_failures`.
   :param feature_missingness_df: Per-feature missingness with family metadata, e.g. from
                                  :func:`coco_pipe.descriptors.qc.compute_family_missingness`.
   :param family_summary_df: One row per descriptor family, e.g. from
                             :func:`coco_pipe.descriptors.qc.aggregate_family_qc` (optionally
                             extended via :func:`coco_pipe.descriptors.qc.add_family_diagnostics`).
   :param figure_paths: Mapping of figure keys to image file paths, as produced by a
                        descriptor-QC figure-saving helper.

   :returns: *output_path*, after the report has been written.
   :rtype: Path


.. py:function:: generate_descriptor_dataset_report(output_path, overview_df, shard_summary_df, flags_df, failure_family_df, failure_channel_df, feature_missingness_df, low_variance_df, family_summary_df, figure_paths, manifest_df = None, condition_breakdown_df = None, asset_urls = None)

   Build the merged-dataset descriptor QC report.

   :param output_path: Destination ``.html`` path. Parent directories are created.
   :param asset_urls: Passed through to :class:`~coco_pipe.report.core.Report`. Use
                      ``"inline"`` to embed Plotly/Tailwind/pako so the saved HTML renders
                      offline (file://) instead of referencing external CDNs.
   :param overview_df: Single-row dataframe with dataset-level summary metrics.
   :param shard_summary_df: One row per merged shard with at least a ``qc_status`` column.
   :param flags_df: Dataset-level QC flags.
   :param failure_family_df: Failure counts grouped by family / channel, e.g. the ``"by_family"``
                             and ``"by_channel"`` frames from
                             :func:`coco_pipe.descriptors.qc.summarize_failures`.
   :param failure_channel_df: Failure counts grouped by family / channel, e.g. the ``"by_family"``
                              and ``"by_channel"`` frames from
                              :func:`coco_pipe.descriptors.qc.summarize_failures`.
   :param feature_missingness_df: Per-feature missingness with family metadata.
   :param low_variance_df: Features flagged as constant or near-zero variance.
   :param family_summary_df: One row per descriptor family (optionally extended via
                             :func:`coco_pipe.descriptors.qc.add_family_diagnostics`).
   :param figure_paths: Mapping of figure keys to image file paths.
   :param manifest_df: Optional single-row provenance table (e.g. derived from
                       ``merge_manifest.json``) rendered in the Overview section.
   :param condition_breakdown_df: Optional family x condition breakdown of failure counts and
                                  missingness, rendered in a dedicated section.

   :returns: *output_path*, after the report has been written.
   :rtype: Path