Skip to content

Add class docstring for DiffractionObject #265

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sbillinge merged 3 commits into from
Dec 23, 2024
Merged

Add class docstring for DiffractionObject #265

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f96728a
Add class docstring for diffraction object and news
bobleesj Dec 22, 2024
1af98b4
Fix docstring for DiffractionObject with PEP256
bobleesj Dec 22, 2024
90672ee
Fix small typo in diffractionobjet
bobleesj Dec 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions news/class-docstring.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
**Added:**

* class docstring for `DiffractionObject`

**Changed:**

* <news item>

**Deprecated:**

* <news item>

**Removed:**

* <news item>

**Fixed:**

* <news item>

**Security:**

* <news item>
113 changes: 73 additions & 40 deletions src/diffpy/utils/diffraction_objects.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,50 +36,38 @@ def _setter_wmsg(attribute):

class DiffractionObject:
"""
Initialize a DiffractionObject instance.
A class to represent diffraction data for various scientific experiments involving scattering
Comment thread
sbillinge marked this conversation as resolved.
Outdated
Copy link
Copy Markdown
Contributor

@sbillinge sbillinge Dec 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's use the numpy standard. First line is <80 chars and gives a high level statement of the purpose.

Then a blank line. then a more meaty description such as you have here).

Copy link
Copy Markdown
Contributor Author

@bobleesj bobleesj Dec 22, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done - do we want to use automatic doc formatting in pre-commit?

  # docformatter - formats docstrings in python code
  - repo: https://github.com/s-weigand/docformatter
    rev: 5757c5190d95e5449f102ace83df92e7d3b06c6c
    hooks:
      - id: docformatter
        additional_dependencies: [tomli]
        args: [--in-place, --config, ./pyproject.toml]

??

This basically modifies our code to PEP 257, although it does not fix the length, it does change the format.

REF: https://github.com/PyCQA/docformatter

Copy link
Copy Markdown
Contributor Author

@bobleesj bobleesj Dec 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Screenshot 2024-12-22 at 3 20 30 PM

Like black, it first fails, and the modify it automatically for us.

Copy link
Copy Markdown
Contributor Author

@bobleesj bobleesj Dec 22, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(i can create a separate PR for this)

techniques such as X-ray, neutron, and electron diffraction. This object can manage diffraction
data including transformations between different scattering quantities like q (scattering vector),
2θ (two-theta angle), and d (interplanar spacing), and perform various operations like scaling, addition,
Comment thread
sbillinge marked this conversation as resolved.
Outdated
and subtraction of diffraction patterns.

Parameters
Attributes
Comment thread
sbillinge marked this conversation as resolved.
----------
xarray : array-like
The independent variable array containing "q", "tth", or "d" values.
yarray : array-like
The dependent variable array corresponding to intensity values.
xtype : str
The type of the independent variable in `xarray`. Must be one of {*XQUANTITIES}.
wavelength : float, optional
The wavelength of the incoming beam, specified in angstroms (Å). Default is none.
scat_quantity : str, optional
all_arrays : ndarray
The array containing the quantity of q, tth, d values.
input_xtype : str
The type of the independent variable in `xarray`. Must be one of {*XQUANTITIES}
id : uuid
The unique identifier for the diffraction object.
Comment thread
sbillinge marked this conversation as resolved.
Outdated
scat_quantity : str
The type of scattering experiment (e.g., "x-ray", "neutron"). Default is an empty string "".
name : str, optional
wavelength : float
The wavelength of the incoming beam, specified in angstroms (Å). Default is none.
name: str
The name or label for the scattering data. Default is an empty string "".
metadata : dict, optional
The additional metadata associated with the diffraction object. Default is {}.

Examples
--------
Create a DiffractionObject for X-ray scattering data:

>>> import numpy as np
>>> from diffpy.utils.diffraction_objects import DiffractionObject
...
>>> x = np.array([0.12, 0.24, 0.31, 0.4]) # independent variable (e.g., q)
>>> y = np.array([10, 20, 40, 60]) # intensity values
>>> metadata = {
... "sample": "rock salt from the beach",
... "composition": "NaCl",
... "temperature": "300 K,",
... "experimenters": "Phill, Sally"
... }
>>> do = DiffractionObject(
... xarray=x,
... yarray=y,
... xtype="q",
... wavelength=1.54,
... scat_quantity="x-ray",
... name="beach_rock_salt_1",
... metadata=metadata
... )
>>> print(do.metadata)
qmin : float
The minimum q value.
qmax : float
The maximum q value.
tthmin : float
The minimum two-theta value.
tthmax : float
The maximum two-theta value.
dmin : float
The minimum d-spacing value.
dmax : float
The maximum d-spacing value.
Comment thread
sbillinge marked this conversation as resolved.
"""

def __init__(
Expand All @@ -92,6 +80,51 @@ def __init__(
name="",
metadata={},
):
"""
Comment thread
sbillinge marked this conversation as resolved.
Outdated
Initialize a DiffractionObject instance.

Parameters
----------
xarray : ndarray
The independent variable array containing "q", "tth", or "d" values.
yarray : ndarray
The dependent variable array corresponding to intensity values.
xtype : str
The type of the independent variable in `xarray`. Must be one of {*XQUANTITIES}.
wavelength : float, optional
The wavelength of the incoming beam, specified in angstroms (Å). Default is none.
scat_quantity : str, optional
The type of scattering experiment (e.g., "x-ray", "neutron"). Default is an empty string "".
name : str, optional
The name or label for the scattering data. Default is an empty string "".
metadata : dict, optional
The additional metadata associated with the diffraction object. Default is {}.

Examples
--------
Create a DiffractionObject for X-ray scattering data
>>> import numpy as np
>>> from diffpy.utils.diffraction_objects import DiffractionObject
...
>>> x = np.array([0.12, 0.24, 0.31, 0.4]) # independent variable (e.g., q)
>>> y = np.array([10, 20, 40, 60]) # intensity values
>>> metadata = {
... "sample": "rock salt from the beach",
... "composition": "NaCl",
... "temperature": "300 K,",
... "experimenters": "Phill, Sally"
... }
>>> do = DiffractionObject(
... xarray=x,
... yarray=y,
... xtype="q",
... wavelength=1.54,
... scat_quantity="x-ray",
... name="beach_rock_salt_1",
... metadata=metadata
... )
>>> print(do.metadata)
"""

self._id = uuid.uuid4()
self._input_data(xarray, yarray, xtype, wavelength, scat_quantity, name, metadata)
Expand Down