mt_metadata.processing.aurora.decimation_level ============================================== .. py:module:: mt_metadata.processing.aurora.decimation_level .. autoapi-nested-parse:: This module contains the DecimationLevel class. TODO: Factor or rename. The decimation level class here has information about the entire processing. Classes ------- .. autoapisummary:: mt_metadata.processing.aurora.decimation_level.SaveFcsTypeEnum mt_metadata.processing.aurora.decimation_level.DecimationLevel Functions --------- .. autoapisummary:: mt_metadata.processing.aurora.decimation_level.get_fft_harmonics Module Contents --------------- .. py:class:: SaveFcsTypeEnum Bases: :py:obj:`mt_metadata.common.enumerations.StrEnumerationBase` str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'. .. py:attribute:: h5 :value: 'h5' .. py:attribute:: csv :value: 'csv' .. py:class:: DecimationLevel(**data) Bases: :py:obj:`mt_metadata.base.MetadataBase` Base class for all metadata objects with Pydantic validation. MetadataBase extends DotNotationBaseModel (which inherits from Pydantic's BaseModel) to provide automatic validation according to metadata standards. It adds functionality beyond dictionaries, supporting JSON, XML, pandas Series, and other formats for metadata interchange. .. attribute:: _skip_equals Private attribute listing fields to skip in equality comparisons :type: list[str] .. attribute:: _fields Private attribute caching field information :type: dict[str, Any] .. rubric:: Notes - All field assignments are validated automatically via Pydantic - None values are converted to appropriate defaults (empty string or 0.0) - Supports nested attribute access via dot notation - Thread-safe for read operations after initialization .. py:attribute:: bands :type: Annotated[list[mt_metadata.common.band.Band], Field(default_factory=list, description='List of bands', json_schema_extra={'units': None, 'required': True, 'examples': ['[]']})] .. py:attribute:: channel_weight_specs :type: Annotated[List[mt_metadata.features.weights.ChannelWeightSpec], Field(default_factory=list, description='List of weighting schemes to use for TF processing for each output channel', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['[]']})] .. py:attribute:: input_channels :type: Annotated[list[str], Field(default_factory=list, description='list of input channels (sources)', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['hx, hy']})] .. py:attribute:: output_channels :type: Annotated[list[str], Field(default_factory=list, description='list of output channels (responses)', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['ex, ey, hz']})] .. py:attribute:: reference_channels :type: Annotated[list[str], Field(default_factory=list, description='list of reference channels (remote sources)', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': ['hx, hy']})] .. py:attribute:: save_fcs :type: Annotated[bool, Field(default=False, description='Whether the Fourier coefficients are saved [True] or not [False].', alias=None, json_schema_extra={'units': None, 'required': True, 'examples': [True]})] .. py:attribute:: save_fcs_type :type: Annotated[SaveFcsTypeEnum | None, Field(default=None, description='Format to use for fc storage', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['h5']})] .. py:attribute:: decimation :type: Annotated[mt_metadata.processing.TimeSeriesDecimation, Field(default_factory=Decimation, description='Decimation settings', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['Decimation()']})] .. py:attribute:: estimator :type: Annotated[mt_metadata.processing.aurora.estimator.Estimator, Field(default_factory=Estimator, description='Estimator settings', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['Estimator()']})] .. py:attribute:: regression :type: Annotated[mt_metadata.processing.aurora.regression.Regression, Field(default_factory=Regression, description='Regression settings', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['Regression()']})] .. py:attribute:: stft :type: Annotated[mt_metadata.processing.ShortTimeFourierTransform, Field(default_factory=STFT, description='Short-time Fourier transform settings', alias=None, json_schema_extra={'units': None, 'required': False, 'examples': ['STFT()']})] .. py:method:: validate_channel_weight_specs(value, info) :classmethod: Validator for channel_weight_specs field. .. py:method:: validate_bands(value, info) :classmethod: .. py:method:: add_band(band) add a band .. py:property:: lower_bounds :type: numpy.ndarray get lower bounds index values into an array. .. py:property:: upper_bounds :type: numpy.ndarray get upper bounds index values into an array. .. py:property:: bands_dataframe :type: pandas.DataFrame Utility function that transforms a list of bands into a dataframe See notes in `_df_from_bands`. :returns: **bands_df** -- Same format as that generated by EMTFBandSetupFile.get_decimation_level() :rtype: pd.Dataframe .. py:property:: frequency_sample_interval :type: float Returns the delta_f in frequency domain df = 1 / (N * dt) Here dt is the sample interval after decimation :returns: **frequency_sample_interval** -- The frequency sample interval after decimation. :rtype: float .. py:property:: band_edges :type: numpy.ndarray Returns the band edges as a numpy array :returns: **band_edges** :rtype: 2D numpy array, one row per frequency band and two columns .. py:method:: frequency_bands_obj() Gets a FrequencyBands object that is used as input to processing. Used by Aurora. TODO: consider adding .to_frequency_bands() method directly to self.bands :returns: **frequency_bands** -- A FrequencyBands object that can be used as an iterator for processing. :rtype: FrequencyBands .. py:property:: fft_frequencies :type: numpy.ndarray Gets the harmonics of the STFT. :returns: **freqs** -- The frequencies at which the stft will be available. :rtype: np.ndarray .. py:property:: harmonic_indices :type: List[int] Loops over all bands and returns a list of the harminic indices. TODO: Distinguish the bands which are a processing construction vs harmonic indices which are FFT info. :returns: **return_list** -- The indices of the harmonics that are needed for processing. :rtype: list of integers .. py:property:: local_channels .. py:method:: is_consistent_with_archived_fc_parameters(fc_decimation, remote) Usage: For an already existing spectrogram stored in an MTH5 archive, this compares the metadata within the archive (fc_decimation) with an aurora decimation level (self), and tells whether the parameters are in agreement. If True, this allows aurora to skip the calculation of FCs and instead read them from the archive. TODO: Merge all checks of TimeSeriesDecimation parameters into a single check. - e.g. Compress all decimation checks to: assert fc_decimation.decimation == self.decimation Parameters ---------- decimation_level: FCDecimation metadata describing the parameters used to compute an archived spectrogram remote: bool If True, we are looking for reference channels, not local channels in the FCGroup. Iterates over FCDecimation attributes: "channels_estimated": to ensure all expected channels are in the group "decimation.anti_alias_filter": check that the expected AAF was applied "decimation.sample_rate, "decimation.method", "stft.prewhitening_type", "stft.recoloring", "stft.pre_fft_detrend_type", "stft.min_num_stft_windows", "stft.window", "stft.harmonic_indices", :rtype: return: .. py:method:: to_fc_decimation(remote = False, ignore_harmonic_indices = True) Generates a FC Decimation() object for use with FC Layer in mth5. TODO: this is being tested only in aurora -- move a test to mt_metadata or move the method. Ignoring for now these properties "time_period.end": "1980-01-01T00:00:00+00:00", "time_period.start": "1980-01-01T00:00:00+00:00", TODO: FIXME: Assignment of TSDecimation can be done in one shot once #235 is addressed. :param remote: If True, use reference channels, if False, use local_channels. We may wish to not pass remote=True when _building_ FCs however, because then not all channels will get built. :type remote: bool :param ignore_harmonic_indices: If True, leave harmonic indices at default [-1,], which means all indices. If False, only the specific harmonic indices needed for processing will be stored. Thus, when building FCs, it maybe best to leave this as True, that way all FCs will be stored, so if the band setup is changed, the FCs will still be there. :type ignore_harmonic_indices: bool :param Returns: fc_dec_obj:mt_metadata.transfer_functions.processing.fourier_coefficients.decimation.Decimation A decimation object configured for STFT processing .. py:function:: get_fft_harmonics(samples_per_window, sample_rate) Works for odd and even number of points. Development notes: Could be modified with kwargs to support one_sided, two_sided, ignore_dc ignore_nyquist, and etc. Consider taking FrequencyBands as an argument. :param samples_per_window: Number of samples in a window that will be Fourier transformed. :type samples_per_window: integer :param sample_rate: Inverse of time step between samples, Samples per second :type sample_rate: float :returns: **harmonic_frequencies** -- The frequencies that the fft will be computed. These are one-sided (positive frequencies only) Does not return Nyquist Does return DC component :rtype: numpy array