Skip to content

Commit 9ce1769

Browse files
authored
Merge pull request #297 from yucongalicechen/docs-do
docs: add examples for operations
2 parents 65088f9 + cfb7362 commit 9ce1769

File tree

2 files changed

+54
-8
lines changed

2 files changed

+54
-8
lines changed

Diff for: doc/source/examples/diffraction_objects_example.rst

+31-8
Original file line numberDiff line numberDiff line change
@@ -129,14 +129,14 @@ For convenience, you can also apply an offset to the scaled new diffraction obje
129129
DiffractionObject convenience functions
130130
---------------------------------------
131131

132-
1) create a copy of a diffraction object using the ``copy`` method
132+
1. create a copy of a diffraction object using the ``copy`` method
133133
when you want to preserve the original data while working with a modified version.
134134

135135
.. code-block:: python
136136
137137
copy_of_calculated = calculated.copy()
138138
139-
2) test the equality of two diffraction objects. For example,
139+
2. test the equality of two diffraction objects. For example,
140140

141141
.. code-block:: python
142142
@@ -145,15 +145,38 @@ DiffractionObject convenience functions
145145
146146
will return ``True``.
147147

148-
3) make arithmetic operations on the intensities of diffraction objects. e.g.,
148+
3. make arithmetic operations on the intensities of diffraction objects.
149+
For example, you can do scalar operations on a single diffraction object,
150+
which will modify the intensity values (``yarrays``) without affecting other properties:
149151

150152
.. code-block:: python
151153
152-
doubled_object = 2 * diff_object1 # Double the intensities
153-
sum_object = diff_object1 + diff_object2 # Sum the intensities
154-
subtract_scaled = diff_object1 - 5 * diff_object2 # subtract 5 * obj2 from obj 1
154+
increased_intensity = diff_object1 + 5 # Increases the intensities by 5
155+
decreased_intensity = diff_object1 - 1 # Decreases the intensities by 1
156+
doubled_object = 2 * diff_object1 # Double the intensities
157+
reduced_intensity = diff_object1 / 2 # Halves the intensities
155158
156-
4) get the value of the DiffractionObject at a given point in one of the xarrays
159+
You can also do binary operations between two diffraction objects, as long as they are on the same ``q/tth/d-array``.
160+
The operation will apply to the intensity values, while other properties
161+
(such as ``xarrays``, ``xtype``, and ``metadata``) will be inherited
162+
from the left-hand side diffraction object (``diff_object1``).
163+
For example:
164+
165+
.. code-block:: python
166+
167+
sum_object = diff_object1 + diff_object2 # Sum the intensities
168+
subtract_scaled = diff_object1 - 5 * diff_object2 # Subtract 5 * obj2 from obj 1
169+
multiplied_object = diff_object1 * diff_object2 # Multiply the intensities
170+
divided_object = diff_object1 / diff_object2 # Divide the intensities
171+
172+
You cannot perform operations between diffraction objects and incompatible types.
173+
For example, attempting to add a diffraction object and a string will raise an error:
174+
175+
.. code-block:: python
176+
177+
diff_object1 + "string_value" # This will raise an error
178+
179+
4. get the value of the DiffractionObject at a given point in one of the xarrays
157180

158181
.. code-block:: python
159182
@@ -170,7 +193,7 @@ you can find its closest index for ``q=0.25`` by typing either of the following:
170193
index = do.get_array_index(0.25) # no xtype passed, defaults to do._input_xtype, or in this example, q
171194
index = do.get_array_index(0.25, xtype="q") # explicitly choose an xtype to specify a value
172195
173-
5) The ``dump`` function saves the diffraction data and relevant information to an xy format file with headers
196+
5. The ``dump`` function saves the diffraction data and relevant information to an xy format file with headers
174197
(widely used chi format used, for example, by Fit2D and diffpy. These files can be read by ``LoadData()``
175198
in ``diffpy.utils.parsers``).
176199

Diff for: news/docs-do.rst

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
**Added:**
2+
3+
* no news added: adding documentation for diffraction object operation examples
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>

0 commit comments

Comments
 (0)