mt_metadata.utils.summarize
===========================

.. py:module:: mt_metadata.utils.summarize

.. autoapi-nested-parse::

   Created on Tue Feb 23 11:52:35 2021

   :copyright:
       Jared Peacock (jpeacock@usgs.gov)

   :license: MIT

   This module provides functionality to summarize metadata standards from both
   legacy BaseDict-based objects and modern Pydantic v2 MetadataBase objects.

   The main functions are:
   - summarize_timeseries_standards(): Legacy function for BaseDict objects
   - summarize_pydantic_standards(): New function for Pydantic v2 MetadataBase objects
   - extract_metadata_fields_from_pydantic(): Extract fields from individual Pydantic classes
   - summarize_standards(): Unified interface supporting both legacy and Pydantic systems

   Example usage:
       # For Pydantic v2 objects (recommended)
       >>> df = summarize_standards(metadata_type="pydantic")

       # Extract fields from individual class
       >>> from mt_metadata.timeseries import Survey
       >>> fields = extract_metadata_fields_from_pydantic(Survey)

       # Get BaseDict-compatible summary
       >>> summary = summarize_pydantic_standards()



Attributes
----------

.. autoapisummary::

   mt_metadata.utils.summarize.SUMMARIZE_DTYPE


Functions
---------

.. autoapisummary::

   mt_metadata.utils.summarize.extract_metadata_fields_from_pydantic
   mt_metadata.utils.summarize.collect_basemodel_objects
   mt_metadata.utils.summarize.summarize_pydantic_standards
   mt_metadata.utils.summarize.summary_to_array
   mt_metadata.utils.summarize.summary_to_dataframe
   mt_metadata.utils.summarize.summarize_standards


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

.. py:data:: SUMMARIZE_DTYPE

.. py:function:: extract_metadata_fields_from_pydantic(metadata_class)

   Extract field information from a Pydantic v2 MetadataBase class definition
   and convert it to a format compatible with BaseDict.

   :param metadata_class: A MetadataBase class (not instance)
   :type metadata_class: type

   :returns: Dictionary with field information compatible with BaseDict
   :rtype: dict


.. py:function:: collect_basemodel_objects(module)

   Collect all MetadataBase subclasses from a given module.

   :param module: The module to inspect (e.g., 'mt_metadata.timeseries')
   :type module: str

   :returns: Dictionary mapping class objects to their names
   :rtype: dict[type[MetadataBase], str]


.. py:function:: summarize_pydantic_standards(module = 'timeseries')

   Summarize the standards for metadata using Pydantic v2 MetadataBase classes.
   Similar to summarize_timeseries_standards but works with the new Pydantic structure.

   :param module: The module to inspect, by default "timeseries"
   :type module: str, optional

   :returns: BaseDict object containing summarized field information
   :rtype: BaseDict


.. py:function:: summary_to_array(summary_dict, dtype=SUMMARIZE_DTYPE)

   Summarize all metadata from a summarized dictionary of standards

   :param summary_dict: Dictionary of summarized standards
   :type summary_dict: dict

   :returns: numpy structured array
   :rtype: np.array


.. py:function:: summary_to_dataframe(summary_dict)

   Convert a summary dictionary to a pandas DataFrame.

   :param summary_dict: Dictionary of summarized standards
   :type summary_dict: dict

   :returns: DataFrame containing the summarized standards
   :rtype: pd.DataFrame


.. py:function:: summarize_standards(module='timeseries', csv_fn=None, output_type='dataframe', dtype=SUMMARIZE_DTYPE)

   Summarize standards into a numpy array and write a csv if specified

   :param module: Module to summarize, by default "timeseries"
   :type module: str, optional
   :param csv_fn: Full path to write a csv file, by default None
   :type csv_fn: str or Path, optional

   :returns: If output_type is "array", returns a numpy structured array.
             If output_type is "dataframe", returns a pandas DataFrame.
   :rtype: numpy.ndarray | pd.DataFrame