Skip to content

Commit 8107874

Browse files
sbillingesbillinge
authored
Merge pull request #265 from bobleesj/class-docstring
Add class docstring for `DiffractionObject`
2 parents d791c63 + 90672ee commit 8107874

File tree

2 files changed

+105
-49
lines changed

2 files changed

+105
-49
lines changed

‎news/class-docstring.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
**Added:**
2+
3+
* class docstring for `DiffractionObject`
4+
5+
**Changed:**
6+
7+
* <news item>
8+
9+
**Deprecated:**
10+
11+
* <news item>
12+
13+
**Removed:**
14+
15+
* <news item>
16+
17+
**Fixed:**
18+
19+
* <news item>
20+
21+
**Security:**
22+
23+
* <news item>

‎src/diffpy/utils/diffraction_objects.py

Lines changed: 82 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -35,51 +35,41 @@ def _setter_wmsg(attribute):
3535

3636

3737
class DiffractionObject:
38-
"""
39-
Initialize a DiffractionObject instance.
38+
"""Class for storing and manipulating diffraction data.
39+
40+
DiffractionObject stores data produced from X-ray, neutron,
41+
and electron scattering experiments. The object can transform
42+
between different scattering quantities such as q (scattering vector),
43+
2θ (two-theta angle), and d (interplanar spacing), and perform various
44+
operations like scaling, addition, subtraction, and comparison for equality
45+
between diffraction objects.
4046
41-
Parameters
47+
Attributes
4248
----------
43-
xarray : array-like
44-
The independent variable array containing "q", "tth", or "d" values.
45-
yarray : array-like
46-
The dependent variable array corresponding to intensity values.
47-
xtype : str
48-
The type of the independent variable in `xarray`. Must be one of {*XQUANTITIES}.
49-
wavelength : float, optional
50-
The wavelength of the incoming beam, specified in angstroms (Å). Default is none.
51-
scat_quantity : str, optional
49+
all_arrays : ndarray
50+
The array containing the quantity of q, tth, d values.
51+
input_xtype : str
52+
The type of the independent variable in `xarray`. Must be one of {*XQUANTITIES}
53+
id : uuid
54+
The unique identifier for the diffraction object.
55+
scat_quantity : str
5256
The type of scattering experiment (e.g., "x-ray", "neutron"). Default is an empty string "".
53-
name : str, optional
57+
wavelength : float
58+
The wavelength of the incoming beam, specified in angstroms (Å). Default is none.
59+
name: str
5460
The name or label for the scattering data. Default is an empty string "".
55-
metadata : dict, optional
56-
The additional metadata associated with the diffraction object. Default is {}.
57-
58-
Examples
59-
--------
60-
Create a DiffractionObject for X-ray scattering data:
61-
62-
>>> import numpy as np
63-
>>> from diffpy.utils.diffraction_objects import DiffractionObject
64-
...
65-
>>> x = np.array([0.12, 0.24, 0.31, 0.4]) # independent variable (e.g., q)
66-
>>> y = np.array([10, 20, 40, 60]) # intensity values
67-
>>> metadata = {
68-
... "sample": "rock salt from the beach",
69-
... "composition": "NaCl",
70-
... "temperature": "300 K,",
71-
... "experimenters": "Phill, Sally"
72-
... }
73-
>>> do = DiffractionObject(
74-
... xarray=x,
75-
... yarray=y,
76-
... xtype="q",
77-
... wavelength=1.54,
78-
... scat_quantity="x-ray",
79-
... name="beach_rock_salt_1",
80-
... metadata=metadata
81-
... )
82-
>>> print(do.metadata)
61+
qmin : float
62+
The minimum q value.
63+
qmax : float
64+
The maximum q value.
65+
tthmin : float
66+
The minimum two-theta value.
67+
tthmax : float
68+
The maximum two-theta value.
69+
dmin : float
70+
The minimum d-spacing value.
71+
dmax : float
72+
The maximum d-spacing value.
8373
"""
8474

8575
def __init__(
@@ -92,6 +82,50 @@ def __init__(
9282
name="",
9383
metadata={},
9484
):
85+
"""Initialize a DiffractionObject instance.
86+
87+
Parameters
88+
----------
89+
xarray : ndarray
90+
The independent variable array containing "q", "tth", or "d" values.
91+
yarray : ndarray
92+
The dependent variable array corresponding to intensity values.
93+
xtype : str
94+
The type of the independent variable in `xarray`. Must be one of {*XQUANTITIES}.
95+
wavelength : float, optional
96+
The wavelength of the incoming beam, specified in angstroms (Å). Default is none.
97+
scat_quantity : str, optional
98+
The type of scattering experiment (e.g., "x-ray", "neutron"). Default is an empty string "".
99+
name : str, optional
100+
The name or label for the scattering data. Default is an empty string "".
101+
metadata : dict, optional
102+
The additional metadata associated with the diffraction object. Default is {}.
103+
104+
Examples
105+
--------
106+
Create a DiffractionObject for X-ray scattering data
107+
>>> import numpy as np
108+
>>> from diffpy.utils.diffraction_objects import DiffractionObject
109+
...
110+
>>> x = np.array([0.12, 0.24, 0.31, 0.4]) # independent variable (e.g., q)
111+
>>> y = np.array([10, 20, 40, 60]) # intensity values
112+
>>> metadata = {
113+
... "sample": "rock salt from the beach",
114+
... "composition": "NaCl",
115+
... "temperature": "300 K,",
116+
... "experimenters": "Phill, Sally"
117+
... }
118+
>>> do = DiffractionObject(
119+
... xarray=x,
120+
... yarray=y,
121+
... xtype="q",
122+
... wavelength=1.54,
123+
... scat_quantity="x-ray",
124+
... name="beach_rock_salt_1",
125+
... metadata=metadata
126+
... )
127+
>>> print(do.metadata)
128+
"""
95129

96130
self._id = uuid.uuid4()
97131
self._input_data(xarray, yarray, xtype, wavelength, scat_quantity, name, metadata)
@@ -273,8 +307,8 @@ def id(self, _):
273307
raise AttributeError(_setter_wmsg("id"))
274308

275309
def get_array_index(self, value, xtype=None):
276-
"""
277-
Return the index of the closest value in the array associated with the specified xtype.
310+
"""Return the index of the closest value in the array associated with
311+
the specified xtype.
278312
279313
Parameters
280314
----------
@@ -337,8 +371,8 @@ def on_d(self):
337371
return [self.all_arrays[:, 3], self.all_arrays[:, 0]]
338372

339373
def scale_to(self, target_diff_object, q=None, tth=None, d=None, offset=0):
340-
"""
341-
returns a new diffraction object which is the current object but rescaled in y to the target
374+
"""Returns a new diffraction object which is the current object but
375+
rescaled in y to the target.
342376
343377
The y-value in the target at the closest specified x-value will be used as the factor to scale to.
344378
The entire array is scaled by this factor so that one object places on top of the other at that point.
@@ -379,8 +413,8 @@ def scale_to(self, target_diff_object, q=None, tth=None, d=None, offset=0):
379413
return scaled
380414

381415
def on_xtype(self, xtype):
382-
"""
383-
Return a list of two 1D np array with x and y data, raise an error if the specified xtype is invalid
416+
"""Return a list of two 1D np array with x and y data, raise an error
417+
if the specified xtype is invalid.
384418
385419
Parameters
386420
----------
@@ -425,8 +459,7 @@ def dump(self, filepath, xtype=None):
425459
np.savetxt(f, data_to_save, delimiter=" ")
426460

427461
def copy(self):
428-
"""
429-
Create a deep copy of the DiffractionObject instance.
462+
"""Create a deep copy of the DiffractionObject instance.
430463
431464
Returns
432465
-------

0 commit comments

Comments
 (0)