Merge pull request #38402 from mantidproject/isis_orso_docs_update

Document module mantid.utils.reflectometry.orso_helper

Author: jmborr

docs/source/api/python/mantid/utils/index.rst

@@ -1,5 +1,6 @@
 .. _mantid.utils:
 
+
 ====================
  :mod:`mantid.utils`
 ====================
@@ -10,10 +11,10 @@ can be used as a library to pull internal functions from an algorithm
 so that the code can be shared with external software needing the
 same functionality without the need to duplicate code.
 
-Unit tests for functions in this module should be placed in the
-``Framework/PythonInterface/test/python/mantid/utils/`` directory and
-added to its ``CMakeLists.txt`` to make sure the testing code gets
-registered with Mantid.
+.. toctree::
+   :maxdepth: 1
+
+   reflectometry
 
 
 Calling functions from ``utils``
@@ -69,3 +70,12 @@ can be called from different algorithms.
         element_size=2,      # integration element cube in mm
         cache_dir="/tmp",    # cache diretory for speeding up repeated calculation
         )
+
+
+Testing ``utils``
+=================
+
+Unit tests for functions in this module should be placed in the
+``Framework/PythonInterface/test/python/mantid/utils/`` directory and
+added to its ``CMakeLists.txt`` to make sure the testing code gets
+registered with Mantid.

docs/source/api/python/mantid/utils/reflectometry.rst

@@ -0,0 +1,38 @@
+.. _mantid.utils.reflectometry:
+
+Reflectometry Utilities
+=======================
+
+
+ORSO format IO
+--------------
+
+The ``mantid.utils.reflectometry.orso_helper`` module provides functionality for reading and saving
+reflectivity data in the ORSO standard [#ORSO]_ format.
+The orsopy library [#orsopy]_ is used to collect numerical data as well as metadata into meaningful data structures
+which are later assembled and written out to file.
+The file's format can be ASCII (``.ort``) or binary Nexus (``.orb``).
+
+The ``orso_helper`` module defines classes such as ``MantidORSOSaver``,  ``MantidORSODataset``,
+and ``MantidORSODataColumns`` to facilitate the creation, manipulation, and saving of ORSO datasets.
+The ``MantidORSOSaver`` class manages the saving of datasets in ASCII or Nexus formats,
+while the ``MantidORSODataset`` class constructs the dataset with necessary metadata and data columns.
+Finally, the ``MantidORSODataColumns`` class handles the addition and management of data columns and their
+associated metadata.
+
+
+.. image:: /images/orso_helper.png
+    :alt: Class diagram showing the main classes and their relationships
+    :width: 50%
+
+This module integrates with the rest of the Mantid framework to ensure that reflectivity is standardized
+and shared in compliance with ORSO specifications.
+For instance, the module provides the backend functionality for the implementation of algorithm
+:ref:`algm-SaveISISReflectometryORSO`.
+
+
+References
+----------
+
+.. [#ORSO] ORSO file format specification: `https://www.reflectometry.org/file_format/specification <https://www.reflectometry.org/file_format/specification>`_
+.. [#orsopy] orsopy Python library: `https://orsopy.readthedocs.io/en/latest/ <https://orsopy.readthedocs.io/en/latest/>`_

docs/source/images/orso_helper.png

@@ -0,0 +1,41 @@
+@startuml
+
+class orsopy.Column {}
+
+class orsopy.ErrorColumn {}
+
+class orsopy.OrsoDataset{}
+
+class orsopy.Orso{}
+
+class orsopy.Header{}
+
+class MantidORSOSaver {
+    - _datasets: List[MantidORSODataset]
+    + add_dataset(dataset: MantidORSODataset)
+    + save_orso_ascii()
+    + save_orso_nexus()
+}
+
+class MantidORSODataset {
+    - _data_columns: MantidORSODataColumns
+    - _header: orsopy.Orso(_data_columns.header_info,...)
+    + dataset() : OrsoDataset(_header, _data_columns.data)
+}
+
+class MantidORSODataColumns {
+    + data: np.ndarray
+    + header_info: List[Union[Column, ErrorColumn]]
+}
+
+orsopy.Orso <-- orsopy.Header
+
+MantidORSOSaver "1" *-- "0..*" MantidORSODataset
+MantidORSODataset *-- MantidORSODataColumns
+MantidORSODataset *-- orsopy.Orso
+MantidORSODataset ..> orsopy.OrsoDataset : returns
+
+MantidORSODataColumns "1" *-- "0..*" orsopy.Column
+MantidORSODataColumns "1" *-- "0..*" orsopy.ErrorColumn
+
+@enduml