feat: Add random state feature. #150

john-halloran · 2025-06-06T19:48:37Z

feat: Added random_state feature for reproducibility.

sbillinge

This is great!

We have to decide how much testing we will add. Ideal is 100% coverage, optimal is probably less.

Maybe write the docstrings so I can understand what the class does, then we can decide what to test?

src/diffpy/snmf/snmf_class.py

john-halloran · 2025-06-06T21:09:28Z

This is great!

We have to decide how much testing we will add. Ideal is 100% coverage, optimal is probably less.

Maybe write the docstrings so I can understand what the class does, then we can decide what to test?

Thanks, will work on resolving these. To be clear, for things like the docstrings would you prefer I make new PRs, get those merged, then rebase this one, or just add to this existing PR?

john-halloran · 2025-06-08T06:23:10Z

For now, I will assume anything given as feedback in this PR could be in scope to include.

sbillinge

This is a great start. I left a couple of comments.

sbillinge · 2025-06-08T17:23:57Z

src/diffpy/snmf/snmf_class.py

@@ -17,6 +17,64 @@ def __init__(
        components=None,
        random_state=None,
    ):
+        """Run sNMF based on an ndarray, parameters, and either a number


This is fantastic! Thanks for this. Please see here for our docstring standards, I am not sure if you looked at it:
https://scikit-package.github.io/scikit-package/programming-guides/billinge-group-standards.html#docstrings

For classes it is a bit tricky because what info do we put in the "Class" docstring and what info do we put in the "constructor" (i.e., the __init__()) docstring. After some googling we came up with the breakout that is shown in the DiffractionObjects class that is shown there. We would be after something similar here.

By way of example, I would probably do like this in this case

def SNMFOptimizer: '''Configuration and methods to run the stretched NMF algorithm, sNMF Instantiating the SNMFOptimizer class runs all the analysis immediately. The results can then be accessed as instance attributes of the class (X, Y, and A). Please see <reference to paper> for more details about the algorithm. Attributes ----------- mm : ndarray The array containing the data to be decomposed. Shape is (length_of_signal, number_of_conditions) y0 : ndarray The array containing initial guesses for the component weights at each stretching condition. Shape is (number_of_components, number_of_conditions ... '''

put future development plans into issues, not in the docstring. Just describe the current behavior. Try and keep it brief but highly informational.

To conform to PEP8 standards I lower-cased the variables. I know they correspond to matrices but we should decide which standard to break. The tie-breaker should probably be scikit-learn. Whatever they do, let's do that. Let's also add a small comment (not in the docstring) to remind ourselves in the future if it breaks PEP8 or it will annoy me every time we revisit it and I will try and change it back......

Conditions on instantiation will go in the constructor docstring.

That one describes the init method so should look more like a function docstring. It would look something like....

def __init__(mm....) '''Initialize a SNMFOptimizer instance and run the optimization Parameters ------------ mm : ndarray The array containing the data to be decomposed. Shape is (length_of_signal, number_of_conditions) y0 : ndarray Optional. Defaults to None The array containing initial guesses for the component weights at each stretching condition. Shape is (number_of_components, number_of_conditions ...

I think there was some text before about how Y0 was required. But if it is required it may be better to make it a required (positional) variable in the constructor and not have it optional. we can discuss design decisions too if you like.

Either Y0 or n_components needs to be provided. Currently, Y0.shape overrides n_components if both are provided, and throws an error if neither are provided. The way scikit-learn is a little more flexible and also allows for an n_components which is different from Y0.shape, although I'm not clear on why you'd want that. But I'm not matching their behavior exactly because the current code doesn't allow that.

scikit-learn actually does break PEP8 to upper-case the matrices

sbillinge

good progress, please see comments.

src/diffpy/snmf/snmf_class.py

sbillinge · 2025-06-10T01:25:23Z

src/diffpy/snmf/snmf_class.py

+
+    For more information on sNMF, please reference:
+    Gu, R., Rakita, Y., Lan, L. et al. Stretched non-negative matrix factorization.
+    npj Comput Mater 10, 193 (2024). https://doi.org/10.1038/s41524-024-01377-5


we would normally do a list of Class attributes here. Everything that is self.something. This is obviously strongly overlapped with the arguments of the constructor, as many of the attributes get defined in the constructor, but logically they are different. Here we list and dsecribe the class attributes, there we describe the init function arguments.

I'm not clear on how I'd distinguish the arguments from the attributes. I understand how they are different semantically, but what part of that is necessary to make clear here? Can you give an example? Those have been helpful.

everything that is self.something (except for methods which are self.functions() which are not considered attributes) is an attribute. So MM, Y0, X0 are attributes, but also M, N, rng, num_updates etc.

Inside a function or method the parameters are the arguments of the function. so for the __init__() function they will be MM, Y0, X0, A, rho, eta and so on). Some of the descriptions will overlap but for the function argument the user needs to know if it is optional or not, what the default is, and anything else they need to know to successfully instantiate the class. People will generally not see the two docstrings at the same time, so there can be some repetition, but try and keep it short but informative.

pls confirm with a thumbs up if you saw this.

Added class attributes. Some of them are for sure redundant but a full cleanup I will save for the next PR.

src/diffpy/snmf/snmf_class.py

sbillinge · 2025-06-10T01:28:49Z

src/diffpy/snmf/snmf_class.py

-            provided.
+            The array containing initial guesses for the component weights
+            at each stretching condition. Shape is (number of components, number of
+            conditions) Must be provided if n_components is not provided. Will override


normally we would raise an exception if two conflicting things are provided (we don't want to guess which is the right one) unless there is a good functional reason to do it another way. We like to avoid "magic" and the current behavior of the code could be "magic". Please raise an exception unless there is a strong reason to do otherwise.

Okay. I don't see any reason for them not to match, so now the user will only be allowed to provide one. This isn't what scikit-learn does, but per your suggestion it makes the most sense for now. The new logic will be: "first, check that exclusively one of n_components and Y0 is provided. If not, raise an exception. If n_components is provided, use that to generate a Y0 with the appropriate size."

if scikit-learn does it the "magic" way we may want to/have to conform to that. But for now, let's do it this way.

src/diffpy/snmf/snmf_class.py

sbillinge

good discussion. pls see my comments

src/diffpy/snmf/snmf_class.py

sbillinge · 2025-06-13T01:02:09Z

src/diffpy/snmf/snmf_class.py

+
+    For more information on sNMF, please reference:
+    Gu, R., Rakita, Y., Lan, L. et al. Stretched non-negative matrix factorization.
+    npj Comput Mater 10, 193 (2024). https://doi.org/10.1038/s41524-024-01377-5


everything that is self.something (except for methods which are self.functions() which are not considered attributes) is an attribute. So MM, Y0, X0 are attributes, but also M, N, rng, num_updates etc.

Inside a function or method the parameters are the arguments of the function. so for the __init__() function they will be MM, Y0, X0, A, rho, eta and so on). Some of the descriptions will overlap but for the function argument the user needs to know if it is optional or not, what the default is, and anything else they need to know to successfully instantiate the class. People will generally not see the two docstrings at the same time, so there can be some repetition, but try and keep it short but informative.

src/diffpy/snmf/snmf_class.py

sbillinge · 2025-06-14T10:41:28Z

Thanks, will work on resolving these. To be clear, for things like the docstrings would you prefer I make new PRs, get those merged, then rebase this one, or just add to this existing PR?

Sounds good. Yes, in general, smaller PRs are easier to merge. We never rebase. You may have been using that term loosely, but it has a particular meaning. But yes everything will get merged together.

sbillinge

I have to run for a plane. I will make another review later, but this is getting very close now.

src/diffpy/snmf/snmf_class.py

sbillinge · 2025-06-14T10:44:51Z

src/diffpy/snmf/snmf_class.py

+            be overridden by Y0 if that is provided, but must be provided if no Y0 is
+            provided.
+        random_state : int
+            The seed for the initial matrices used in the optimization.


this is a little unclear. What matrices?

Should be clearer now.

src/diffpy/snmf/snmf_class.py

sbillinge

The docstrings are really good now, modulo a few small comments.

I want to understand why the SNMFOptimizer is a class and not a function (or rather a method in the SNMF class). Let's figure this out. It won't create that much work...less actually because we will need fewer docstrings.....so don't panic about wasted effort.

sbillinge · 2025-06-14T11:27:57Z

src/diffpy/snmf/main.py

-
-
-my_model = snmf_class.SNMFOptimizer(MM=MM, Y0=Y0, X0=X0, A=A0, components=2)
+my_model = snmf_class.SNMFOptimizer(MM=MM, Y0=Y0, X0=X0, A=A0, n_components=2)


Looking at this, it seems that we have already instantiated some kind of SNMF class, then this is doing the optimization. Is there a particular reason why we make this a class and not a function? It feels much more like a function to me. Could you think what the downsides are of making it a function? Is scikit-learn doing some thing like this too?

What scikit-learn has is an NMF class which instantiates, and then has the standard set of model class members like fit_transform and such. But to actually "do the math", NMF internally makes a call to non_negative_factorization. So the math should probably be a function, but unless (and until) we are literally merging this into scikit-learn, it's worth having a class. But instantiating the class should not be running math as it does currently. That's going to be the next thing I tackle, but this PR is getting a little long so I'm holding off.

it's worth having a class

I don't see the value in having this as a class tbh. Can you justify why it is worth having a class for this (when we have already instantiated a higher lever class (I can't easily see in the browser what this class is called) as snmf_class)

john-halloran · 2025-06-15T21:06:09Z

I am also taking off for a couple of days but this should be in decent shape. Content wise this is all I'd like to add without opening a new PR, but let me know if you see typos or fixes. Otherwise it looks okay to merge on my end. Thanks for all the help.

sbillinge · 2025-06-15T21:13:25Z

@john-halloran I figured out what was going. on. there was a dirty import in main (as a general matter we rarely/never use import <modeule> which obscured a bit the actual structure and which tricked me. Please ignore my comment about the class. Let's in general, have a conversation about what the class structure and naming should look like, but there is lots of good work on this PR so I will merge it for now.

feat: Add random state feature.

d8d4e11

sbillinge reviewed Jun 6, 2025

View reviewed changes

Add class docstring

ae45726

components->n_components

3d7c8b6

sbillinge reviewed Jun 8, 2025

View reviewed changes

Updated docstring

a0483b4

sbillinge reviewed Jun 10, 2025

View reviewed changes

Shorten and reformat docstring

d39cbe0

sbillinge reviewed Jun 13, 2025

View reviewed changes

docstring typo

c783a02

sbillinge reviewed Jun 14, 2025

View reviewed changes

John Halloran added 3 commits June 15, 2025 12:47

Flag self.rng as private

7f8e33d

Make logic for n_components and Y0 more rigid

6ba837f

added class attributes to docstring

f45b4bb

sbillinge added 2 commits June 15, 2025 17:09

fix: cleaner import of SNMFOptimizer

bdfab77

fix: correct class instantiation after change in import

4e13df1

sbillinge merged commit 373da11 into diffpy:john-development Jun 15, 2025
1 check passed



		my_model = snmf_class.SNMFOptimizer(MM=MM, Y0=Y0, X0=X0, A=A0, components=2)
		my_model = snmf_class.SNMFOptimizer(MM=MM, Y0=Y0, X0=X0, A=A0, n_components=2)

feat: Add random state feature. #150

feat: Add random state feature. #150

Uh oh!

Conversation

john-halloran commented Jun 6, 2025

Uh oh!

sbillinge left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

john-halloran commented Jun 6, 2025

Uh oh!

john-halloran commented Jun 8, 2025

Uh oh!

sbillinge left a comment

Choose a reason for hiding this comment

Uh oh!

sbillinge Jun 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbillinge left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sbillinge left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sbillinge commented Jun 14, 2025

Uh oh!

sbillinge left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sbillinge left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbillinge Jun 8, 2025 •

edited

Loading

john-halloran commented Jun 15, 2025 •

edited

Loading