Multi-Resolution Time Series Analysis #2345

GabrielSoto-INL · 2024-07-29T16:05:01Z

Pull Request Description

What issue does this change request address? (Use "#" before the issue to link it, i.e., #42.)

What are the significant changes in functionality due to this change request?

Replaces #2129 .

New changes include introduction of multi-resolution time series analysis capabilities to RAVEN, particularly incorporated within the ROMCollection , SyntheticHistory and TSA module infrastructure. Multiresolution (MR) time series analysis algorithms are capable of investigating the inherent dynamics of time series at multiple timescales or frequencies. Decomposition of time series at multiple levels is a typical MR algorithm. These changes add the capability of decomposing time series signal(s) at different levels via a MR algorithm while still leveraging characterization, additional transformation, and generative algorithms within the current TSA library.

A new algorithm was added to the TSA module which is a modified wavelet transform: FilterBankDWT. This algorithm (and more in the future) will be compatible with a new MultiResolutionTSA ROM subtype and a Decomposition ROMCollection subtype. An example input script is shown below to help walk through the new additions:

A new ROM subtype called MultiResolutionTSA has been added.
- It inherits the SupervisedLearning ROM class.
- It serves the role of the _interfaceROM (for example, when using the standard TSA module, the _interfaceROM is the SyntheticHistory class).
A new algorithm FilterBankDWT, using the PyWavelets python package, uses a filter bank discrete wavelet transform to decompose the original signal into various levels.
- Note that other TSA algorithms can be used to modify or learn characteristics of the signal prior to this algorithm being used.
- It accepts a wavelet family and an integer number of decomposition levels.
- After this algorithm is applied (the last applied within this node before the SegmentROM), the signal is split into multiple instances, one per decomposition level.
Another new class within the ROMCollection architecture is a Decomposition class which inherits the SupervisedLearning ROM class.
- It serves the role of the _segmentROM (for example, previous instances use Segment, Clusters, or Interpolated classes).
- This class handles training and evaluation of algorithms for the time series before and after decomposition.
- Each decomposition gets assigned to a new instance of a SyntheticHistory object. Any algorithms within the <Segment> node of this input will be applied to each decomposition level (e.g., here, an ARMA model is trained per decomposition level).

Other notes:

input time series data can be a single macroStep or multiple macroSteps (e.g., multiple years). examples are given in the \tests subdirectory.
interpolation of learned features between missing macroSteps is not handled within this PR (potential future one).

For Change Control Board: Change Request Review

The following review must be completed by an authorized member of the Change Control Board.

1. Review all computer code.
2. If any changes occur to the input syntax, there must be an accompanying change to the user manual and xsd schema. If the input syntax change deprecates existing input files, a conversion script needs to be added (see Conversion Scripts).
3. Make sure the Python code and commenting standards are respected (camelBack, etc.) - See on the wiki for details.
4. Automated Tests should pass, including run_tests, pylint, manual building and xsd tests. If there are changes to Simulation.py or JobHandler.py the qsub tests must pass.
5. If significant functionality is added, there must be tests added to check this. Tests should cover all possible options. Multiple short tests are preferred over one large test. If new development on the internal JobHandler parallel system is performed, a cluster test must be added setting, in XML block, the node <internalParallel> to True.
6. If the change modifies or adds a requirement or a requirement based test case, the Change Control Board's Chair or designee also needs to approve the change. The requirements and the requirements test shall be in sync.
7. The merge request must reference an issue. If the issue is closed, the issue close checklist shall be done.
8. If an analytic test is changed/added is the the analytic documentation updated/added?
9. If any test used as a basis for documentation examples (currently found in raven/tests/framework/user_guide and raven/docs/workshop) have been changed, the associated documentation must be reviewed and assured the text matches the example.

moosebuild · 2024-07-31T13:17:00Z

Job Mingw Test on c2e8911 : invalidated by @GabrielSoto-INL

Segmentation fault when activating raven_libraries, trying again?

j-bryan

Looks good to me, just a couple small comments.

j-bryan · 2024-08-02T03:01:29Z

ravenframework/SupervisedLearning/MultiResolutionTSA.py

+  def __init__(self):
+    """
+      Constructor.
+      @ In, kwargs, dict, initialization options


Method has no **kwargs argument.

j-bryan · 2024-08-02T04:32:28Z

ravenframework/TSA/Transformers/FilterBankDWT.py

+    self._levels = settings['levels'] - 1
+    return settings
+
+  def fit(self, signal, pivot, targets, settings, trainedParams=None):


Add trainedParams to docstring

good catch, found some other algos for which I forgot to add that docstring

j-bryan · 2024-08-02T04:51:58Z

ravenframework/TSA/Transformers/FilterBankDWT.py

+      @ In, settings, dict, additional settings specific to algorithm
+      @ Out, residual, np.array, reduced signal shaped [pivotValues, targets]
+    """
+    residual = np.zeros(initial.shape)


Would it be better to copy the initial array instead of creating an array of zeros? That way any values in targets not in initial are passed through.

Jimmy-INL · 2024-08-01T18:19:41Z

plugins/HERON

Is this intentional?

it... was not. a little unsure what's happening, on my local it says they're at the same commit as the plugins in the RAVEN repo... I'll dig in to it a little more.

Jimmy-INL · 2024-08-01T18:25:13Z

ravenframework/SupervisedLearning/MultiResolutionTSA.py

+      @ In, skip, list, optional, unused (kept for compatability)
+      @ Out, None
+    """
+


Is this function completely empty? even not an empty return or pass? Is it an abstract one that has to be there?

I missed the return statement. this one is empty for now, need to find an efficient way to print out XML meta

I actually found an easy way of reporting back info, this method is now filled in!

Jimmy-INL · 2024-08-01T18:32:11Z

plugins/TEAL

Jimmy-INL · 2024-08-02T15:16:55Z

ravenframework/TSA/Transformers/FilterBankDWT.py

+      @ In, pivot, np.1darray, time-like parameter values
+      @ In, targets, list(str), names of targets in same order as signal
+      @ In, settings, dict, additional settings specific to this algorithm
+      @ Out, params, dict, characteristic parameters


@ In, trainedParams,...

wangcj05

Some comments for you to consider, in addition, please fix the submodule issue also. @GabrielSoto-INL

wangcj05 · 2024-08-27T21:38:03Z

ravenframework/SupervisedLearning/MultiResolutionTSA.py

+    self._globalROM = SyntheticHistory()
+    self._decompParams = {}
+    self.decompositionAlgorithm = None


It is better to provide some descriptions for the self variables.

fixed, actually realized I wasn't using _decompParams so it helped clean up the code!

wangcj05 · 2024-08-27T21:39:00Z

ravenframework/SupervisedLearning/MultiResolutionTSA.py

+    """
+    super()._handleInput(paramInput)
+    self._globalROM._handleInput(paramInput)
+    self._dynamicHandling = True # This ROM is able to manage the time-series on its own.


I think this should be moved to init method.

wangcj05 · 2024-08-27T21:40:45Z

ravenframework/SupervisedLearning/MultiResolutionTSA.py

+
+  def __evaluateLocal__(self, featureVals):
+    """
+    Evaluate algorithms for ROM generation


two extra spaces for this line.

fixed, good catch!

wangcj05 · 2024-08-27T21:41:45Z

ravenframework/SupervisedLearning/MultiResolutionTSA.py

+  ### ESSENTIALLY UNUSED ###
+  def _localNormalizeData(self,values,names,feat):
+    """
+      Overwrites default normalization procedure, since we do not desire normalization in this implementation.
+      @ In, values, unused
+      @ In, names, unused
+      @ In, feat, feature to normalize
+      @ Out, None
+    """
+    self.muAndSigmaFeatures[feat] = (0.0,1.0)
+
+  def __confidenceLocal__(self,featureVals):
+    """
+      This method is currently not needed for ARMA
+    """
+    pass
+
+  def __resetLocal__(self,featureVals):
+    """
+      After this method the ROM should be described only by the initial parameter settings
+      Currently not implemented for ARMA
+    """
+    pass
+
+  def __returnInitialParametersLocal__(self):
+    """
+      there are no possible default parameters to report
+    """
+    localInitParam = {}
+    return localInitParam
+
+  def __returnCurrentSettingLocal__(self):
+    """
+      override this method to pass the set of parameters of the ROM that can change during simulation
+      Currently not implemented for ARMA
+    """
+    pass


Do you need to keep these methods? I assume they are also defined in the base class.

it seems we didn't need _localNormalizeData but the others are abstract methods in SupervisedLearning so they need to be defined here

wangcj05 · 2024-08-27T21:44:21Z

ravenframework/SupervisedLearning/ROMCollection.py

+  # dummy methods that are required by SVL and not generally used
+  def __confidenceLocal__(self, featureVals):
+    """
+      This should return an estimation of the quality of the prediction.
+      This could be distance or probability or anything else, the type needs to be declared in the variable cls.qualityEstType
+      @ In, featureVals, 2-D numpy array , [n_samples,n_features]
+      @ Out, __confidenceLocal__, float, the confidence
+    """
+    pass
+
+  def __resetLocal__(self):
+    """
+      Reset ROM. After this method the ROM should be described only by the initial parameter settings
+      @ In, None
+      @ Out, None
+    """
+    pass
+
+  def __returnCurrentSettingLocal__(self):
+    """
+      Returns a dictionary with the parameters and their current values
+      @ In, None
+      @ Out, params, dict, dictionary of parameter names and current values
+    """
+    return {}
+
+  def __returnInitialParametersLocal__(self):
+    """
+      Returns a dictionary with the parameters and their initial values
+      @ In, None
+      @ Out, params, dict,  dictionary of parameter names and initial values
+    """
+    return {}


Are these methods required?

same as above^ these are abstract methods in the base class

wangcj05 · 2024-08-27T21:50:02Z

ravenframework/TSA/Transformers/FilterBankDWT.py

+    """
+    # general infrastructure
+    super().__init__(*args, **kwargs)
+    self._levels = 1


provide descriptions for self variables

wangcj05 · 2024-08-27T21:51:34Z

ravenframework/TSA/Transformers/FilterBankDWT.py

+    # determine maximum decomposition level
+    max_level = pywt.dwt_max_level(len(pivot), family)
+    if self._levels>max_level:
+      print(f"Number of levels requested is larger than maximum DWT decomposition level, switching to maximum allowed: {max_level}")


please use message handler to raise messages.

it looks like the base classes for the TSA algorithms do not inherit Message Handler at the moment. this may be a subject of future discussion?

wangcj05 · 2024-08-27T21:55:44Z

tests/framework/ROM/TimeSeries/MultiResolutionTSA/multiYearDWT.xml

+    <created>2021-01-08</created>
+    <classesTested>SupervisedLearning.SyntheticHistory,TSA.Fourier</classesTested>
+    <description>
+      Tests the SyntheticHistory ROM using only the Fourier TimeSeriesAnalyzer algorithm.


I would suggest to add descriptions to reflect multi-resolution TSA

wangcj05 · 2024-08-27T21:55:59Z

tests/framework/ROM/TimeSeries/MultiResolutionTSA/simpleDWT.xml

+    <created>2021-01-08</created>
+    <classesTested>SupervisedLearning.MultiResolutionTSA,TSA.FilterBankDWT</classesTested>
+    <description>
+      Tests the SyntheticHistory ROM using only the Fourier TimeSeriesAnalyzer algorithm.


I would suggest to add descriptions to reflect multi-resolution TSA

wangcj05 · 2024-08-27T21:56:58Z

tests/framework/ROM/TimeSeries/MultiResolutionTSA/gold/MultiYearDWT/samples.csv

@@ -0,0 +1,4001 @@
+RAVEN_sample_ID,seconds,macro,scaling,signal0,PointProbability,prefix,ProbabilityWeight


Is it possible to reduce the size of this file? In addition, you do not need ProbabilityWeight, PointProbability in your output.

I can reduce the number of levels requested per year and regold.
I'm unsure how to get rid of ProbabilityWeight and PointProbability.. I don't request those in the raven input XML, I wonder if they're there automatically because there are multiple target signals?

moosebuild · 2024-09-19T15:18:44Z

Job Test Ubuntu 18 PIP on 48c5e1b : invalidated by @GabrielSoto-INL

GabrielSoto-INL added 8 commits May 14, 2024 11:22

new classes for multiresolutionTSA and discrete wavelet transform algo

ed77ac5

updating submodules to match devel

b89d1a0

renaming DWT to FilterBankDWT, adding class attrib for MRA

95a0f25

allowing macroSteps (e.g., years) looping in training

19bd128

formalizing getters for trained MRA params

7cbb350

fixing evaluate for multiple macrosteps

746a852

fixing levels error when requested exceeds max

d2d1205

multiresolution tests

0c0973d

GabrielSoto-INL mentioned this pull request Jul 29, 2024

[WIP] Multiresolution Analysis via Wavelet-ARMAs #2129

Closed

9 tasks

GabrielSoto-INL added 3 commits July 29, 2024 12:45

pywavelets not optional, but imported with lazy loading

045bc72

fixing typo in pywt call, gold dirnames, add docstrings

5921128

fixing other typos

c2e8911

Jimmy-INL requested review from Jimmy-INL, wangcj05 and j-bryan August 1, 2024 18:17

j-bryan requested changes Aug 2, 2024

View reviewed changes

Jimmy-INL requested changes Aug 2, 2024

View reviewed changes

fixing docstrings

84d3222

wangcj05 requested changes Aug 27, 2024

View reviewed changes

GabrielSoto-INL added 6 commits September 11, 2024 16:36

addressing reviewer comments, fixing writeXML and additional getters

8a16c42

fixing test files and regolding romMeta

038c71c

updating descriptions and some fixes to levels input

31bfc5a

matching TEAL plugin to remote

521ae78

changing training data and MRA tests

0fd5ae0

regolding

48c5e1b

Merge branch 'devel' into multiResolutionTSA

ee4a358

		@@ -0,0 +1,4001 @@
		RAVEN_sample_ID,seconds,macro,scaling,signal0,PointProbability,prefix,ProbabilityWeight

Multi-Resolution Time Series Analysis #2345

Are you sure you want to change the base?

Multi-Resolution Time Series Analysis #2345

Conversation

GabrielSoto-INL commented Jul 29, 2024 • edited Loading

Pull Request Description

What issue does this change request address? (Use "#" before the issue to link it, i.e., #42.)

What are the significant changes in functionality due to this change request?

For Change Control Board: Change Request Review

moosebuild commented Jul 31, 2024

j-bryan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wangcj05 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

moosebuild commented Sep 19, 2024

GabrielSoto-INL commented Jul 29, 2024 •

edited

Loading