From 6757a57f3900617c3db3796a32a78dbf98e4affb Mon Sep 17 00:00:00 2001 From: yucongalicechen Date: Tue, 31 Dec 2024 16:16:26 -0500 Subject: [PATCH 1/3] docs: add docstrings and news --- news/DO-docstring.rst | 23 ++++++++++++++++++ src/diffpy/utils/diffraction_objects.py | 31 +++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 news/DO-docstring.rst diff --git a/news/DO-docstring.rst b/news/DO-docstring.rst new file mode 100644 index 00000000..e3107199 --- /dev/null +++ b/news/DO-docstring.rst @@ -0,0 +1,23 @@ +**Added:** + +* docstrings for `on_q`, `on_tth`, `on_d`, and `dump` in `diffraction_objects.py`. + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* diff --git a/src/diffpy/utils/diffraction_objects.py b/src/diffpy/utils/diffraction_objects.py index f95f1758..dc7bcea3 100644 --- a/src/diffpy/utils/diffraction_objects.py +++ b/src/diffpy/utils/diffraction_objects.py @@ -418,12 +418,33 @@ def _get_original_array(self): return self.on_d(), "d" def on_q(self): + """Return the tuple of two 1D numpy arrays containing q and y data. + + Returns + ------- + (xarray, yarray) : tuple of ndarray + The tuple containing two 1D numpy arrays with q and y data + """ return [self.all_arrays[:, 1], self.all_arrays[:, 0]] def on_tth(self): + """Return the tuple of two 1D numpy arrays containing tth and y data. + + Returns + ------- + (xarray, yarray) : tuple of ndarray + The tuple containing two 1D numpy arrays with tth and y data + """ return [self.all_arrays[:, 2], self.all_arrays[:, 0]] def on_d(self): + """Return the tuple of two 1D numpy arrays containing d and y data. + + Returns + ------- + (xarray, yarray) : tuple of ndarray + The tuple containing two 1D numpy arrays with d and y data + """ return [self.all_arrays[:, 3], self.all_arrays[:, 0]] def scale_to(self, target_diff_object, q=None, tth=None, d=None, offset=None): @@ -507,6 +528,16 @@ def on_xtype(self, xtype): raise ValueError(_xtype_wmsg(xtype)) def dump(self, filepath, xtype=None): + """Dump the xarray and yarray of the diffraction object to a two-column + file, with the associated information included in the header. + + Parameters + ---------- + filepath : str + The filepath where the diffraction object will be dumped + xtype : str, optional, default is q + The type of quantity for the independent variable chosen from {*XQUANTITIES, } + """ if xtype is None: xtype = "q" if xtype in QQUANTITIES: From da009de589d160e221d046104fc0e89434299773 Mon Sep 17 00:00:00 2001 From: yucongalicechen Date: Tue, 31 Dec 2024 16:40:17 -0500 Subject: [PATCH 2/3] docs: refine docstring and add example for dump --- src/diffpy/utils/diffraction_objects.py | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/src/diffpy/utils/diffraction_objects.py b/src/diffpy/utils/diffraction_objects.py index dc7bcea3..a5784fde 100644 --- a/src/diffpy/utils/diffraction_objects.py +++ b/src/diffpy/utils/diffraction_objects.py @@ -422,7 +422,7 @@ def on_q(self): Returns ------- - (xarray, yarray) : tuple of ndarray + (q-array, y-array) : tuple of ndarray The tuple containing two 1D numpy arrays with q and y data """ return [self.all_arrays[:, 1], self.all_arrays[:, 0]] @@ -432,7 +432,7 @@ def on_tth(self): Returns ------- - (xarray, yarray) : tuple of ndarray + (tth-array, y-array) : tuple of ndarray The tuple containing two 1D numpy arrays with tth and y data """ return [self.all_arrays[:, 2], self.all_arrays[:, 0]] @@ -442,7 +442,7 @@ def on_d(self): Returns ------- - (xarray, yarray) : tuple of ndarray + (d-array, y-array) : tuple of ndarray The tuple containing two 1D numpy arrays with d and y data """ return [self.all_arrays[:, 3], self.all_arrays[:, 0]] @@ -537,6 +537,14 @@ def dump(self, filepath, xtype=None): The filepath where the diffraction object will be dumped xtype : str, optional, default is q The type of quantity for the independent variable chosen from {*XQUANTITIES, } + + Examples + -------- + To save a diffraction object to a file named "diffraction_data.chi" with + the independent variable 'q': + + >>> file = "diffraction_data.chi" + >>> do.dump(file, xtype="q") """ if xtype is None: xtype = "q" From dd5995b7be4f3ddce8cb1c7e45e52d30c72ce120 Mon Sep 17 00:00:00 2001 From: yucongalicechen Date: Tue, 31 Dec 2024 16:54:28 -0500 Subject: [PATCH 3/3] docs: add more examples --- src/diffpy/utils/diffraction_objects.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/src/diffpy/utils/diffraction_objects.py b/src/diffpy/utils/diffraction_objects.py index a5784fde..99b6b7a1 100644 --- a/src/diffpy/utils/diffraction_objects.py +++ b/src/diffpy/utils/diffraction_objects.py @@ -540,11 +540,21 @@ def dump(self, filepath, xtype=None): Examples -------- - To save a diffraction object to a file named "diffraction_data.chi" with - the independent variable 'q': + To save a diffraction object to a file named "diffraction_data.chi" in the current directory + with the independent variable 'q': >>> file = "diffraction_data.chi" >>> do.dump(file, xtype="q") + + To save the diffraction data to a file in a subfolder `output`: + + >>> file = "./output/diffraction_data.chi" + >>> do.dump(file, xtype="q") + + To save the diffraction data with a different independent variable, such as 'tth': + + >>> file = "diffraction_data_tth.chi" + >>> do.dump(file, xtype="tth") """ if xtype is None: xtype = "q"