From d74ee6a9f96e0993804fecde175beb767a189ab0 Mon Sep 17 00:00:00 2001 From: Zhi Ming Xu Date: Sun, 15 Jun 2025 20:27:33 -0400 Subject: [PATCH 1/6] skpkg: migrate documentation --- doc/source/api/diffpy.snmf.rst | 66 +++++---------------- doc/source/conf.py | 47 ++++++++++++--- doc/source/index.rst | 103 +++++++++++---------------------- doc/source/license.rst | 3 +- requirements/docs.txt | 1 + 5 files changed, 90 insertions(+), 130 deletions(-) diff --git a/doc/source/api/diffpy.snmf.rst b/doc/source/api/diffpy.snmf.rst index 9a808f6d..28f90a6d 100644 --- a/doc/source/api/diffpy.snmf.rst +++ b/doc/source/api/diffpy.snmf.rst @@ -1,68 +1,30 @@ :tocdepth: -1 -diffpy.snmf package -=================== +|title| +======= -.. automodule:: diffpy.snmf - :members: - :undoc-members: - :show-inheritance: - -Submodules ----------- - -diffpy.snmf.subroutines module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: diffpy.snmf.subroutines - :members: - :undoc-members: - :show-inheritance: - -diffpy.snmf.containers module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: diffpy.snmf.containers - :members: - :undoc-members: - :show-inheritance: - -diffpy.snmf.io module -^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: diffpy.snmf.io - :members: - :undoc-members: - :show-inheritance: +.. |title| replace:: diffpy.snmf package -diffpy.snmf.polynomials module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: diffpy.snmf.polynomials +.. automodule:: diffpy.snmf :members: :undoc-members: :show-inheritance: -diffpy.snmf.optimizers module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Subpackages +----------- -.. automodule:: diffpy.snmf.optimizers - :members: - :undoc-members: - :show-inheritance: +.. toctree:: + diffpy.snmf.example_package -diffpy.snmf.factorizers module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Submodules +---------- -.. automodule:: diffpy.snmf.factorizers - :members: - :undoc-members: - :show-inheritance: +|module| +-------- -diffpy.snmf.stretchednmfapp module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. |module| replace:: diffpy.snmf.example_submodule module -.. automodule:: diffpy.snmf.stretchednmfapp +.. automodule:: diffpy.snmf.example_submodule :members: :undoc-members: :show-inheritance: diff --git a/doc/source/conf.py b/doc/source/conf.py index 195ee2ff..04ce9e8a 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,7 +1,7 @@ #!/usr/bin/env python # -*- coding: utf-8 -*- # -# diffpy.snmf documentation build configuration file, created by +# diffpy.snmf documentation build configuration file, created by # noqa: E501 # sphinx-quickstart on Thu Jan 30 15:49:41 2014. # # This file is execfile()d with the current directory set to its @@ -18,15 +18,21 @@ from importlib.metadata import version from pathlib import Path +# Attempt to import the version dynamically from GitHub tag. +try: + fullversion = version("diffpy.snmf") +except Exception: + fullversion = "No version found. The correct version will appear in the released version." # noqa: E501 + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the -# documentation root, use Path().resolve() to make it absolute, like shown here. +# documentation root, use Path().resolve() to make it absolute, like shown here. # noqa: E501 # sys.path.insert(0, str(Path(".").resolve())) sys.path.insert(0, str(Path("../..").resolve())) sys.path.insert(0, str(Path("../../src").resolve())) # abbreviations -ab_authors = "Billinge Group members and community contributors" +ab_authors = "Simon J.L. Billinge group" # -- General configuration ------------------------------------------------ @@ -43,6 +49,7 @@ "sphinx.ext.viewcode", "sphinx.ext.intersphinx", "sphinx_rtd_theme", + "sphinx_copybutton", "m2r", ] @@ -62,13 +69,12 @@ # General information about the project. project = "diffpy.snmf" -copyright = "2023-%Y, The Trustees of Columbia University in the City of New York" +copyright = "%Y, The Trustees of Columbia University in the City of New York" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. -fullversion = version(project) # The short X.Y version. version = "".join(fullversion.split(".post")[:1]) # The full version, including alpha/beta/rc tags. @@ -88,6 +94,11 @@ # substitute YEAR in the copyright string copyright = copyright.replace("%Y", year) +# For sphinx_copybutton extension. +# Do not copy "$" for shell commands in code-blocks. +copybutton_prompt_text = r"^\$ " +copybutton_prompt_is_regexp = True + # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = ["build"] @@ -123,6 +134,14 @@ # html_theme = "sphinx_rtd_theme" +html_context = { + "display_github": True, + "github_user": "diffpy", + "github_repo": "diffpy.snmf", + "github_version": "main", + "conf_py_path": "/doc/source/", +} + # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. @@ -221,7 +240,13 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - ("index", "diffpy.snmf.tex", "diffpy.snmf Documentation", ab_authors, "manual"), + ( + "index", + "diffpy.snmf.tex", + "diffpy.snmf Documentation", + ab_authors, + "manual", + ), ] # The name of an image file (relative to this directory) to place at the top of @@ -249,7 +274,15 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [("index", "diffpy.snmf", "diffpy.snmf Documentation", ab_authors, 1)] +man_pages = [ + ( + "index", + "diffpy.snmf", + "diffpy.snmf Documentation", + ab_authors, + 1, + ) +] # If true, show URL addresses after external links. # man_show_urls = False diff --git a/doc/source/index.rst b/doc/source/index.rst index b7755b07..e1645ecd 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,91 +1,56 @@ -Welcome to SNMF's Documentation! -==================================== +####### +|title| +####### -``SNMF``: This library implements the stretched non negative matrix factorization (sNMF) and sparse stretched NMF -(ssNMF) algorithms described in the paper "Stretched Non-negative Matrix Factorization" by Ran Gu et al. (2023), -which is referenced under the Citation section below. +.. |title| replace:: diffpy.snmf documentation -This algorithm is designed to do an NMF factorization on a set of signals ignoring any uniform stretching of the signal -on the independent variable axis. For example, for powder diffraction data taken from samples containing multiple -chemical phases where the measurements were done at different temperatures and the materials were undergoing thermal -expansion. +``diffpy.snmf`` - Python package implementing the stretched NMF algorithm. -Introduction -++++++++++++ +| Software version |release| +| Last updated |today|. -``snmf`` is a Python package that increases the insight one can obtain from a measured series time-dependent signals -through applying the stretched nonnegative matrix factorization and spare stretched nonnegative matrix factorization -algorithms. The package seeks to answer the question: "What are the structural signals composing my measured signal at -each moment in time?" +=============== +Getting started +=============== -One approach is to take the conventional nonnegative matrix factorization model and extend it by introducing a -stretching factor matrix that accounts for isotropic stretching of measured signals and returns components that explain -variability beyond this stretching. Conventional nonnegative matrix factorization (nmf) obtains component signals and -the weightings of the component signals at each moment in time from a series of data. However, this model assumes the -components themselves are constant in time, making this model unable to capture the changing of the components -themselves. - -``snmf`` consider components that change with time by introducing a stretching factor for each component at each moment -in time that isotropically stretches the component signals.The algorithm will attempt to find three matrices, a -"component" matrix that stores the component signals, a "stretching factor" matrix that stores the stretching factors of -the components at each moment in time, and a "weights" matrix that stores the weights of each component at each moment -in time. ``snmf`` will then plot the components, stretching factors, and weights. - -One import use case of ``snmf`` is for powder diffraction data taken from samples containing multiple -chemical phases where the measurements were done at different temperatures and the materials were undergoing thermal -expansion. The key advantage of ``snmf`` is that it accurately reflects the isotropic change of the atomic distances -within the chemical phases through its addition of stretching factors. - -It is important to note that the user must specify the number of component signals to obtain from the experimental data. -Non-physical results may be obtained if the number of anticipated component signals is too high. - -Citation --------- - -If you use this program for a scientific research that leads -to publication, we ask that you acknowledge use of the program -by citing the following paper in your publication: - - Ran Gu, Yevgeny Rakita, Ling Lan, Zach Thatcher, Gabrielle E. Kamm, Daniel O’Nolan, Brennan Mcbride, Allison Wustrow, James R. Neilson, Karena W. Chapman, Qiang Du, and Simon J. L. Billinge, - `Stretched Non-negative Matrix Factorization - `__, - *npj Comput Mater* **10**, 193 (2024). +Welcome to the ``diffpy.snmf`` documentation! +To get started, please visit the :ref:`Getting started ` page. +======= Authors -------- +======= -``snmf`` implements the algorithms described in ...., developed by members of the Billinge Group at -Columbia University, Brookhaven National Laboratory, Stony Brook University, Nankai University, and Colorado State -University including Ran Gu, Yevgeny Rakita, Ling Lan, Zach Thatcher, Gabrielle E. Kamm, Daniel O'Nolan, Brennan Mcbride, -Jame R. Neilson, Karena W. Chapman, Qiang Du, and Simon J. L. Billinge. +``diffpy.snmf`` is developed by Simon J.L. Billinge group. The maintainer for this project is Simon J.L. Billinge group. For a detailed list of contributors see +https://github.com/diffpy/diffpy.snmf/graphs/contributors. -This software implementation was developed by members of the Billinge Group at Columbia University and Brookhaven -National Laboratory including Ran Gu, Adeolu Ajayi, Qiang Du, and Simon J. L. Billinge. +============ +Installation +============ -For a detailed list of contributors, check `here -`_. +See the `README `_ +file included with the distribution. -To get started, please go to :ref:`quick_start` +================ +Acknowledgements +================ -.. toctree:: - :maxdepth: 3 - :hidden: - - quickstart +``diffpy.snmf`` is built and maintained with `scikit-package `_. +================= +Table of contents +================= .. toctree:: - :maxdepth: 4 - :caption: Contents: + :maxdepth: 2 - license - release + getting-started Package API + release + license -.. include:: ../../CHANGELOG.rst - +======= Indices -------- +======= * :ref:`genindex` * :ref:`search` diff --git a/doc/source/license.rst b/doc/source/license.rst index 573ccaf2..5e751f7a 100644 --- a/doc/source/license.rst +++ b/doc/source/license.rst @@ -9,8 +9,7 @@ OPEN SOURCE LICENSE AGREEMENT ============================= BSD 3-Clause License -Copyright (c) 2023-2024, The Trustees of Columbia University in -the City of New York. +Copyright (c) 2025, The Trustees of Columbia University in the City of New York. All Rights Reserved. Redistribution and use in source and binary forms, with or without diff --git a/requirements/docs.txt b/requirements/docs.txt index ab17b1c8..5f34c6ed 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -1,4 +1,5 @@ sphinx sphinx_rtd_theme +sphinx-copybutton doctr m2r From e1ad1fad277250be5cb1b67db2bc2e1a26e41dfe Mon Sep 17 00:00:00 2001 From: Zhi Ming Xu Date: Sun, 15 Jun 2025 23:22:08 -0400 Subject: [PATCH 2/6] skpkg: add config files for authors, changelog, code of conduct, license --- AUTHORS.rst | 2 +- CHANGELOG.rst | 49 +------------------------------------------------ LICENSE.rst | 3 +-- 3 files changed, 3 insertions(+), 51 deletions(-) diff --git a/AUTHORS.rst b/AUTHORS.rst index 4546e682..9d511935 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -1,7 +1,7 @@ Authors ======= -Billinge Group and community contributors. +Simon J.L. Billinge group Contributors ------------ diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 9b8d9a18..f29d3b53 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,52 +1,5 @@ ============= -Release Notes +Release notes ============= .. current developments - -0.1.3 -===== - -**Fixed:** - -* Updated README instructions for pip and conda-forge install -* Updated README instructions to check for successful installation - - -0.1.2 -===== - -**Added:** - -* Use GitHub Actions to build, release, upload to PyPI -* Added issue template for PyPI/GitHub release - -**Changed:** - -* Added tag check for release -* citation from arXiv to npj Comput Mater in docs - -**Fixed:** - -* Python version from 3.9 to 3.12 in CI news item -* tests folder at the root of the repo -* re-cookiecuter repo to groupd's package standard -* Add pip dependencies under pip.txt and conda dependencies under conda.txt - - -0.1.0 -===== - -**Added:** - -* Initial release of diffpy.snmf - -**Changed:** - -* Support Python version 3.12 -* Remove support for Python version 3.9 - -**Fixed:** - -* Repo structure modified to the new diffpy standard -* Code linting based on .pre-commit-config.yaml diff --git a/LICENSE.rst b/LICENSE.rst index 74fd798d..9cc6a9d1 100644 --- a/LICENSE.rst +++ b/LICENSE.rst @@ -1,7 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023-2024, The Trustees of Columbia University -in the City of New York. +Copyright (c) 2025, The Trustees of Columbia University in the City of New York. All rights reserved. Redistribution and use in source and binary forms, with or without From f1f1f8cd958d2f14b3f036b386fea19f328c606f Mon Sep 17 00:00:00 2001 From: Zhi Ming Xu Date: Mon, 16 Jun 2025 15:59:59 -0400 Subject: [PATCH 3/6] skpkg: add README.rst --- README.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.rst b/README.rst index 2350f693..1d938ba2 100644 --- a/README.rst +++ b/README.rst @@ -8,7 +8,7 @@ :target: https://diffpy.github.io/diffpy.snmf :height: 100px -|PyPi| |Forge| |PythonVersion| |PR| +|PyPI| |Forge| |PythonVersion| |PR| |CI| |Codecov| |Black| |Tracking| @@ -26,7 +26,7 @@ .. |PR| image:: https://img.shields.io/badge/PR-Welcome-29ab47ff -.. |PyPi| image:: https://img.shields.io/pypi/v/diffpy.snmf +.. |PyPI| image:: https://img.shields.io/pypi/v/diffpy.snmf :target: https://pypi.org/project/diffpy.snmf/ .. |PythonVersion| image:: https://img.shields.io/pypi/pyversions/diffpy.snmf @@ -35,7 +35,7 @@ .. |Tracking| image:: https://img.shields.io/badge/issue_tracking-github-blue :target: https://github.com/diffpy/diffpy.snmf/issues -A python package implementing the stretched NMF algorithm. +Python package implementing the stretched NMF algorithm. ``diffpy.snmf`` implements the stretched non negative matrix factorization (sNMF) and sparse stretched NMF (ssNMF) algorithms. @@ -50,14 +50,9 @@ For more information about the diffpy.snmf library, please consult our `online d Citation -------- -If you use this program for a scientific research that leads -to publication, we ask that you acknowledge use of the program -by citing the following paper in your publication: +If you use diffpy.snmf in a scientific publication, we would like you to cite this package as - Ran Gu, Yevgeny Rakita, Ling Lan, Zach Thatcher, Gabrielle E. Kamm, Daniel O’Nolan, Brennan Mcbride, Allison Wustrow, James R. Neilson, Karena W. Chapman, Qiang Du, and Simon J. L. Billinge, - `Stretched Non-negative Matrix Factorization - `__, - *npj Comput Mater* **10**, 193 (2024). + diffpy.snmf Package, https://github.com/diffpy/diffpy.snmf Installation ------------ @@ -104,7 +99,7 @@ Support and Contribute `Diffpy user group `_ is the discussion forum for general questions and discussions about the use of diffpy.snmf. Please join the diffpy.snmf users community by joining the Google group. The diffpy.snmf project welcomes your expertise and enthusiasm! -If you see a bug or want to request a feature, please `report it as an issue `_ and/or `submit a fix as a PR `_. You can also post it to the `Diffpy user group `_. +If you see a bug or want to request a feature, please `report it as an issue `_ and/or `submit a fix as a PR `_. Feel free to fork the project and contribute. To install diffpy.snmf in a development mode, with its sources being directly used by Python @@ -132,4 +127,9 @@ Before contributing, please read our `Code of Conduct `_ or email Prof. Simon Billinge at sb2896@columbia.edu. +For more information on diffpy.snmf please visit the project `web-page `_ or email Simon J.L. Billinge group at sb2896@columbia.edu. + +Acknowledgements +---------------- + +``diffpy.snmf`` is built and maintained with `scikit-package `_. From de23201e4b7035a7f3a872c256415428486367ba Mon Sep 17 00:00:00 2001 From: Zhi Ming Xu Date: Mon, 16 Jun 2025 16:05:25 -0400 Subject: [PATCH 4/6] skpkg: add news files --- news/doc.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 news/doc.rst diff --git a/news/doc.rst b/news/doc.rst new file mode 100644 index 00000000..b0ec659f --- /dev/null +++ b/news/doc.rst @@ -0,0 +1,23 @@ +**Added:** + +* + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* Support ``scikit-package`` Level 5 standard (https://scikit-package.github.io/scikit-package/). + +**Security:** + +* From dbd7d537766505274f1fc754f88e209f4aac81de Mon Sep 17 00:00:00 2001 From: Zhi Ming Xu Date: Mon, 16 Jun 2025 17:02:05 -0400 Subject: [PATCH 5/6] chore: add back necessary lines from the files --- AUTHORS.rst | 2 +- CHANGELOG.rst | 47 ++++++++++++++++++++++++ LICENSE.rst | 2 +- README.rst | 2 +- doc/source/api/diffpy.snmf.rst | 66 ++++++++++++++++++++++++++-------- doc/source/conf.py | 2 +- doc/source/license.rst | 2 +- 7 files changed, 104 insertions(+), 19 deletions(-) diff --git a/AUTHORS.rst b/AUTHORS.rst index 9d511935..4546e682 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -1,7 +1,7 @@ Authors ======= -Simon J.L. Billinge group +Billinge Group and community contributors. Contributors ------------ diff --git a/CHANGELOG.rst b/CHANGELOG.rst index f29d3b53..8275360d 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -3,3 +3,50 @@ Release notes ============= .. current developments + +0.1.3 +===== + +**Fixed:** + +* Updated README instructions for pip and conda-forge install +* Updated README instructions to check for successful installation + + +0.1.2 +===== + +**Added:** + +* Use GitHub Actions to build, release, upload to PyPI +* Added issue template for PyPI/GitHub release + +**Changed:** + +* Added tag check for release +* citation from arXiv to npj Comput Mater in docs + +**Fixed:** + +* Python version from 3.9 to 3.12 in CI news item +* tests folder at the root of the repo +* re-cookiecuter repo to groupd's package standard +* Add pip dependencies under pip.txt and conda dependencies under conda.txt + + +0.1.0 +===== + +**Added:** + +* Initial release of diffpy.snmf + +**Changed:** + +* Support Python version 3.12 +* Remove support for Python version 3.9 + +**Fixed:** + +* Repo structure modified to the new diffpy standard +* Code linting based on .pre-commit-config.yaml diff --git a/LICENSE.rst b/LICENSE.rst index 9cc6a9d1..748d7e06 100644 --- a/LICENSE.rst +++ b/LICENSE.rst @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2025, The Trustees of Columbia University in the City of New York. +Copyright (c) 2024-2025, The Trustees of Columbia University in the City of New York. All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/README.rst b/README.rst index 1d938ba2..8e3b4931 100644 --- a/README.rst +++ b/README.rst @@ -99,7 +99,7 @@ Support and Contribute `Diffpy user group `_ is the discussion forum for general questions and discussions about the use of diffpy.snmf. Please join the diffpy.snmf users community by joining the Google group. The diffpy.snmf project welcomes your expertise and enthusiasm! -If you see a bug or want to request a feature, please `report it as an issue `_ and/or `submit a fix as a PR `_. +If you see a bug or want to request a feature, please `report it as an issue `_ and/or `submit a fix as a PR `_. You can also post it to the `Diffpy user group `_. Feel free to fork the project and contribute. To install diffpy.snmf in a development mode, with its sources being directly used by Python diff --git a/doc/source/api/diffpy.snmf.rst b/doc/source/api/diffpy.snmf.rst index 28f90a6d..9a808f6d 100644 --- a/doc/source/api/diffpy.snmf.rst +++ b/doc/source/api/diffpy.snmf.rst @@ -1,30 +1,68 @@ :tocdepth: -1 -|title| -======= - -.. |title| replace:: diffpy.snmf package +diffpy.snmf package +=================== .. automodule:: diffpy.snmf :members: :undoc-members: :show-inheritance: -Subpackages ------------ - -.. toctree:: - diffpy.snmf.example_package - Submodules ---------- -|module| --------- +diffpy.snmf.subroutines module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: diffpy.snmf.subroutines + :members: + :undoc-members: + :show-inheritance: + +diffpy.snmf.containers module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: diffpy.snmf.containers + :members: + :undoc-members: + :show-inheritance: + +diffpy.snmf.io module +^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: diffpy.snmf.io + :members: + :undoc-members: + :show-inheritance: + +diffpy.snmf.polynomials module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: diffpy.snmf.polynomials + :members: + :undoc-members: + :show-inheritance: + +diffpy.snmf.optimizers module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: diffpy.snmf.optimizers + :members: + :undoc-members: + :show-inheritance: + +diffpy.snmf.factorizers module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. automodule:: diffpy.snmf.factorizers + :members: + :undoc-members: + :show-inheritance: -.. |module| replace:: diffpy.snmf.example_submodule module +diffpy.snmf.stretchednmfapp module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: diffpy.snmf.example_submodule +.. automodule:: diffpy.snmf.stretchednmfapp :members: :undoc-members: :show-inheritance: diff --git a/doc/source/conf.py b/doc/source/conf.py index 04ce9e8a..7f74b6d5 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -32,7 +32,7 @@ sys.path.insert(0, str(Path("../../src").resolve())) # abbreviations -ab_authors = "Simon J.L. Billinge group" +ab_authors = "Billinge Group members and community contributors" # -- General configuration ------------------------------------------------ diff --git a/doc/source/license.rst b/doc/source/license.rst index 5e751f7a..a03a8fb8 100644 --- a/doc/source/license.rst +++ b/doc/source/license.rst @@ -9,7 +9,7 @@ OPEN SOURCE LICENSE AGREEMENT ============================= BSD 3-Clause License -Copyright (c) 2025, The Trustees of Columbia University in the City of New York. +Copyright (c) 2024-2025, The Trustees of Columbia University in the City of New York. All Rights Reserved. Redistribution and use in source and binary forms, with or without From c1b4a124c1ab9a1955c8a543def1f08fe82d16f1 Mon Sep 17 00:00:00 2001 From: Zhi Ming Xu Date: Mon, 16 Jun 2025 17:29:08 -0400 Subject: [PATCH 6/6] chore: fix files according to comments in the review --- LICENSE.rst | 2 +- README.rst | 11 +++-- doc/source/conf.py | 2 +- doc/source/index.rst | 93 +++++++++++++++++++++++++++++++++--------- doc/source/license.rst | 2 +- 5 files changed, 85 insertions(+), 25 deletions(-) diff --git a/LICENSE.rst b/LICENSE.rst index 748d7e06..a3c60094 100644 --- a/LICENSE.rst +++ b/LICENSE.rst @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2024-2025, The Trustees of Columbia University in the City of New York. +Copyright (c) 2023-2025, The Trustees of Columbia University in the City of New York. All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/README.rst b/README.rst index 8e3b4931..8e50f883 100644 --- a/README.rst +++ b/README.rst @@ -35,7 +35,7 @@ .. |Tracking| image:: https://img.shields.io/badge/issue_tracking-github-blue :target: https://github.com/diffpy/diffpy.snmf/issues -Python package implementing the stretched NMF algorithm. +A python package implementing the stretched NMF algorithm. ``diffpy.snmf`` implements the stretched non negative matrix factorization (sNMF) and sparse stretched NMF (ssNMF) algorithms. @@ -50,9 +50,14 @@ For more information about the diffpy.snmf library, please consult our `online d Citation -------- -If you use diffpy.snmf in a scientific publication, we would like you to cite this package as +If you use this program for a scientific research that leads +to publication, we ask that you acknowledge use of the program +by citing the following paper in your publication: - diffpy.snmf Package, https://github.com/diffpy/diffpy.snmf + Ran Gu, Yevgeny Rakita, Ling Lan, Zach Thatcher, Gabrielle E. Kamm, Daniel O’Nolan, Brennan Mcbride, Allison Wustrow, James R. Neilson, Karena W. Chapman, Qiang Du, and Simon J. L. Billinge, + `Stretched Non-negative Matrix Factorization + `__, + *npj Comput Mater* **10**, 193 (2024). Installation ------------ diff --git a/doc/source/conf.py b/doc/source/conf.py index 7f74b6d5..3b12e7f1 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -69,7 +69,7 @@ # General information about the project. project = "diffpy.snmf" -copyright = "%Y, The Trustees of Columbia University in the City of New York" +copyright = "2023-%Y, The Trustees of Columbia University in the City of New York" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/doc/source/index.rst b/doc/source/index.rst index e1645ecd..0ad72619 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,28 +1,78 @@ -####### -|title| -####### - -.. |title| replace:: diffpy.snmf documentation +Welcome to SNMF's Documentation! +==================================== ``diffpy.snmf`` - Python package implementing the stretched NMF algorithm. | Software version |release| | Last updated |today|. -=============== -Getting started -=============== +``SNMF``: This library implements the stretched non negative matrix factorization (sNMF) and sparse stretched NMF +(ssNMF) algorithms described in the paper "Stretched Non-negative Matrix Factorization" by Ran Gu et al. (2023), +which is referenced under the Citation section below. + +This algorithm is designed to do an NMF factorization on a set of signals ignoring any uniform stretching of the signal +on the independent variable axis. For example, for powder diffraction data taken from samples containing multiple +chemical phases where the measurements were done at different temperatures and the materials were undergoing thermal +expansion. + +Introduction +++++++++++++ + +``snmf`` is a Python package that increases the insight one can obtain from a measured series time-dependent signals +through applying the stretched nonnegative matrix factorization and spare stretched nonnegative matrix factorization +algorithms. The package seeks to answer the question: "What are the structural signals composing my measured signal at +each moment in time?" + +One approach is to take the conventional nonnegative matrix factorization model and extend it by introducing a +stretching factor matrix that accounts for isotropic stretching of measured signals and returns components that explain +variability beyond this stretching. Conventional nonnegative matrix factorization (nmf) obtains component signals and +the weightings of the component signals at each moment in time from a series of data. However, this model assumes the +components themselves are constant in time, making this model unable to capture the changing of the components +themselves. + +``snmf`` consider components that change with time by introducing a stretching factor for each component at each moment +in time that isotropically stretches the component signals.The algorithm will attempt to find three matrices, a +"component" matrix that stores the component signals, a "stretching factor" matrix that stores the stretching factors of +the components at each moment in time, and a "weights" matrix that stores the weights of each component at each moment +in time. ``snmf`` will then plot the components, stretching factors, and weights. -Welcome to the ``diffpy.snmf`` documentation! +One import use case of ``snmf`` is for powder diffraction data taken from samples containing multiple +chemical phases where the measurements were done at different temperatures and the materials were undergoing thermal +expansion. The key advantage of ``snmf`` is that it accurately reflects the isotropic change of the atomic distances +within the chemical phases through its addition of stretching factors. + +It is important to note that the user must specify the number of component signals to obtain from the experimental data. +Non-physical results may be obtained if the number of anticipated component signals is too high. + +Citation +-------- + +If you use this program for a scientific research that leads +to publication, we ask that you acknowledge use of the program +by citing the following paper in your publication: + + Ran Gu, Yevgeny Rakita, Ling Lan, Zach Thatcher, Gabrielle E. Kamm, Daniel O’Nolan, Brennan Mcbride, Allison Wustrow, James R. Neilson, Karena W. Chapman, Qiang Du, and Simon J. L. Billinge, + `Stretched Non-negative Matrix Factorization + `__, + *npj Comput Mater* **10**, 193 (2024). -To get started, please visit the :ref:`Getting started ` page. ======= Authors ======= -``diffpy.snmf`` is developed by Simon J.L. Billinge group. The maintainer for this project is Simon J.L. Billinge group. For a detailed list of contributors see -https://github.com/diffpy/diffpy.snmf/graphs/contributors. +``snmf`` implements the algorithms described in ...., developed by members of the Billinge Group at +Columbia University, Brookhaven National Laboratory, Stony Brook University, Nankai University, and Colorado State +University including Ran Gu, Yevgeny Rakita, Ling Lan, Zach Thatcher, Gabrielle E. Kamm, Daniel O'Nolan, Brennan Mcbride, +Jame R. Neilson, Karena W. Chapman, Qiang Du, and Simon J. L. Billinge. + +This software implementation was developed by members of the Billinge Group at Columbia University and Brookhaven +National Laboratory including Ran Gu, Adeolu Ajayi, Qiang Du, and Simon J. L. Billinge. + +For a detailed list of contributors, check `here +`_. + +To get started, please go to :ref:`quick_start` ============ Installation @@ -37,16 +87,21 @@ Acknowledgements ``diffpy.snmf`` is built and maintained with `scikit-package `_. -================= -Table of contents -================= .. toctree:: - :maxdepth: 2 + :maxdepth: 3 + :hidden: + + quickstart + +.. toctree:: + :maxdepth: 4 + :caption: Contents: - getting-started - Package API - release license + release + Package API + +.. include:: ../../CHANGELOG.rst ======= Indices diff --git a/doc/source/license.rst b/doc/source/license.rst index a03a8fb8..0ea5fba4 100644 --- a/doc/source/license.rst +++ b/doc/source/license.rst @@ -9,7 +9,7 @@ OPEN SOURCE LICENSE AGREEMENT ============================= BSD 3-Clause License -Copyright (c) 2024-2025, The Trustees of Columbia University in the City of New York. +Copyright (c) 2023-2025, The Trustees of Columbia University in the City of New York. All Rights Reserved. Redistribution and use in source and binary forms, with or without