Skip to content

Commit

Permalink
docs: update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@kmnhan
kmnhan committed Jun 24, 2024
1 parent 399715e commit 87872da
Show file tree
Hide file tree
Showing 5 changed files with 160 additions and 28 deletions.
10 changes: 8 additions & 2 deletions docs/source/user-guide/curve-fitting.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,13 @@
"fit multidimensional xarray objects. Finally, we will show how to use `iminuit\n",
"<https://github.com/scikit-hep/iminuit>`_ with lmfit models.\n",
"\n",
"If you are familiar with lmfit, you can skip the first section."
"\n",
"Curve fitting with ``lmfit``\n",
"----------------------------\n",
"\n",
"In this section, we will cover basic curve fitting using `lmfit\n",
"<https://lmfit.github.io/lmfit-py/>`_. If you are familiar with the library, you can\n",
"skip this section."
]
},
{
Expand Down Expand Up @@ -331,7 +337,7 @@
"whether to multiply with a Fermi-Dirac distribution, the shape of the background, and\n",
"whether to convolve the result with experimental resolution.\n",
"\n",
"For a detailed explanation of all the arguments, see its `documentation\n",
"For a detailed explanation of all the arguments, see its :class:`documentation\n",
"<erlab.analysis.fit.models.MultiPeakModel>`.\n",
"\n",
"The model can be constructed as follows:"
Expand Down
3 changes: 2 additions & 1 deletion docs/source/user-guide/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@ Introduction
Welcome to the ERLabPy user guide! This guide provides an overview of ERLabPy and its
core features.

If you are new to using ERLabPy, you may want to start with the :doc:`getting started guide <../getting-started.rst>`.
If you are new to using ERLabPy, you may want to start with the `getting started guide
<../getting-started.rst>`_.

.. toctree::
:caption: Table of Contents
Expand Down
144 changes: 126 additions & 18 deletions docs/source/user-guide/indexing.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,22 @@
"slideshow": {
"slide_type": ""
},
"tags": []
"tags": [],
"vscode": {
"languageId": "raw"
}
},
"source": [
"Selecting and indexing data\n",
"===========================\n",
"\n",
"In most cases, the powerful data manipulation and indexing methods provided by :mod:`xarray` are sufficient. In this page, some frequently used :mod:`xarray` features are summarized in addition to some utilities provided by this package. Refer to the `xarray user guide <https://docs.xarray.dev/en/stable/usedatr-guide/indexing.html>`_ for more information.\n",
"In most cases, the powerful data manipulation and indexing methods provided by\n",
":mod:`xarray` are sufficient. In the first section, we will briefly cover some\n",
"frequently used :mod:`xarray` features. Refer to the `xarray user guide\n",
"<https://docs.xarray.dev/en/stable/user-guide/indexing.html>`_ for more information.\n",
"\n",
"First, let us import some example data: a simple tight binding simulation of graphene."
"Basic ``xarray`` operations\n",
"---------------------------"
]
},
{
Expand All @@ -32,6 +39,14 @@
"xr.set_options(display_expand_data=False)"
]
},
{
"cell_type": "markdown",
"id": "fd4ee1a3",
"metadata": {},
"source": [
"First, let us generate some example data: a simple tight binding simulation of graphene."
]
},
{
"cell_type": "code",
"execution_count": null,
Expand Down Expand Up @@ -68,10 +83,38 @@
},
{
"cell_type": "markdown",
"id": "046a132c",
"id": "c61ee48d",
"metadata": {},
"source": [
"We have a three-dimensional array of intensity given in terms of $k_x$, $k_y$, and\n",
"binding energy. \n"
]
},
{
"cell_type": "raw",
"id": "16477885",
"metadata": {
"editable": true,
"raw_mimetype": "text/restructuredtext",
"slideshow": {
"slide_type": ""
},
"tags": [],
"vscode": {
"languageId": "raw"
}
},
"source": [
"For extracting 2D data (cuts and constant energy surfaces) or 1D data (MDCs and EDCs)\n",
"given the coordinate values, xarray provides :meth:`sel <xarray.DataArray.sel>`."
]
},
{
"cell_type": "markdown",
"id": "8b3790ed",
"metadata": {},
"source": [
"We can see that the generated data is a three-dimensional DataArray. Now, let's extract a cut along $k_y = 0.3$."
"Let's extract a cut along $k_y = 0.3$."
]
},
{
Expand All @@ -87,15 +130,15 @@
},
"outputs": [],
"source": [
"dat.sel(ky=0.3, method=\"nearest\")"
"dat.sel(ky=0.3, method=\"nearest\").plot()"
]
},
{
"cell_type": "markdown",
"id": "8f54de42",
"metadata": {},
"source": [
"How about the Fermi surface?"
"Likewise, the Fermi surface can be extracted like this:"
]
},
{
Expand All @@ -105,21 +148,51 @@
"metadata": {},
"outputs": [],
"source": [
"dat.sel(eV=0.0, method=\"nearest\")"
"dat.sel(eV=0.0, method=\"nearest\").plot()"
]
},
{
"cell_type": "raw",
"id": "626a74d6",
"metadata": {
"editable": true,
"raw_mimetype": "text/restructuredtext",
"slideshow": {
"slide_type": ""
},
"tags": [],
"vscode": {
"languageId": "raw"
}
},
"source": [
"You can also pass :class:`slice` objects to :meth:`sel <xarray.DataArray.sel>` to\n",
"effectively crop the data."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b495a686",
"metadata": {},
"outputs": [],
"source": [
"cut = dat.sel(ky=0.3, method=\"nearest\")\n",
"cut.sel(kx=slice(-0.2, 0.8), eV=slice(-0.25, 0.05)).plot()"
]
},
{
"cell_type": "markdown",
"id": "987121ee",
"metadata": {},
"source": [
"In many scenarios, it is necessary to perform integration across multiple array slices. This can be done by slicing and averaging. The following code integrates the intensity over a window of 50 meV centered at $E_F$."
"In many scenarios, it is necessary to perform integration across multiple indices. This can be done by slicing and then averaging. The following code returns a new DataArray with the intensity integrated over a window of 50 meV centered at $E_F$."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b495a686",
"id": "af14527c",
"metadata": {},
"outputs": [],
"source": [
Expand All @@ -141,11 +214,12 @@
}
},
"source": [
"However, doing this every time is cumbersome, and we have lost the coordinate `eV`. \n",
"However, doing this every time is cumbersome, and we have lost the coordinate ``eV``. In\n",
"the following sections, we will introduce some utilities for convenient indexing.\n",
"\n",
"The ``qsel`` accessor\n",
"---------------------\n",
"ERLabPy provides a callable accessor :class:`qsel <erlab.accessors.utils.SelectionAccessor>` to streamline this process."
"ERLabPy provides a callable accessor :class:`qsel <erlab.accessors.utils.SelectionAccessor>` to streamline the slicing and averaging process. It can be used just like other DataArray methods:"
]
},
{
Expand Down Expand Up @@ -176,12 +250,26 @@
"Note that the averaged coordinate is automatically added to the data array. This is\n",
"useful for plotting and further analysis.\n",
"\n",
"- If the width is not specified, :class:`qsel <erlab.accessors.utils.SelectionAccessor>`\n",
" behaves like passing ``method='nearest'`` to :meth:`sel <xarray.DataArray.sel>`.\n",
"With :class:`qsel <erlab.accessors.utils.SelectionAccessor>`, position along a dimension\n",
"can be specified in three ways:\n",
"\n",
"- As a value and width: ``eV=-0.1, eV_width=0.05``\n",
"\n",
" The data is *averaged* over a slice of width `0.05`, centered at `-0.1` along the\n",
" dimension ``'eV'``.\n",
"\n",
"- As a scalar value: ``eV=0.0``\n",
"\n",
"- If a `slice` object is given instead of a single value, no integration is performed.\n",
" If no width is specified, the data is selected along the nearest value. It is\n",
" equivalent to passing ``method='nearest'`` to :meth:`sel <xarray.DataArray.sel>`.\n",
"\n",
"- All of these methods can be combined:"
"- As a slice: ``eV=slice(-0.2, 0.05)``\n",
"\n",
" The data is selected over the specified slice. No averaging is performed.\n",
"\n",
"The arguments can either be provided in a key-value form, or as a single dictionary.\n",
"\n",
"Unlike :meth:`sel <xarray.DataArray.sel>`, all of this can be combined in a single call:"
]
},
{
Expand Down Expand Up @@ -209,9 +297,29 @@
}
},
"source": [
"In practice, you can generate the arguments for :class:`qsel\n",
"<erlab.accessors.utils.SelectionAccessor>` that reproduce a certain slice within\n",
"`ImageTool <../imagetool.rst>`_ from the right-click menu of each plot.\n",
"\n",
"Averaging data within a distance\n",
"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n",
"\n",
"The :class:`qsel <erlab.accessors.utils.SelectionAccessor>` accessor also provides a\n",
"method :meth:`qsel.around <erlab.accessors.utils.SelectionAccessor.around>` to average\n",
"over points within a certain distance of a given point."
"over points within a certain distance of a given point.\n",
"\n",
"The following plot shows the integrated EDCs near the K point for different radii."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "3f013c3b",
"metadata": {},
"outputs": [],
"source": [
"for radius in (0.03, 0.06, 0.09, 0.12):\n",
" dat.qsel.around(radius, kx=0.52, ky=0.3).plot()"
]
},
{
Expand All @@ -232,7 +340,7 @@
"Masking\n",
"-------\n",
"\n",
"In some cases, it is necessary to mask the data. Although basic masks are supported by :mod:`xarray`, ERLabPy provides a way to mask data with arbitrary polygons.\n",
"ERLabPy provides a way to mask data with arbitrary polygons.\n",
"\n",
".. admonition:: Work in Progress\n",
" :class: warning\n",
Expand Down
21 changes: 15 additions & 6 deletions docs/source/user-guide/plotting.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,17 @@
"slideshow": {
"slide_type": ""
},
"tags": []
"tags": [],
"vscode": {
"languageId": "raw"
}
},
"source": [
"Plotting\n",
"========\n",
"\n",
"ERLabPy provides a number of plotting functions to help visualize data and\n",
"create publication quality figures.\n",
"ERLabPy provides a number of plotting functions to help visualize data and create\n",
"publication quality figures.\n",
"\n",
"Importing\n",
"---------\n",
Expand Down Expand Up @@ -167,10 +170,13 @@
"slideshow": {
"slide_type": ""
},
"tags": []
"tags": [],
"vscode": {
"languageId": "raw"
}
},
"source": [
":func:`plot_array <erlab.plotting.general.plot_array>` takes many arguments that can customize the look of your plot. The following is an example of some of the functionality provided. For all arguments, see the API reference."
":func:`plot_array <erlab.plotting.general.plot_array>` takes many arguments that can customize the look of your plot. The following is an example of some of the functionality provided. For all arguments, see the `API reference <../reference.rst>`_."
]
},
{
Expand Down Expand Up @@ -344,7 +350,10 @@
"slideshow": {
"slide_type": ""
},
"tags": []
"tags": [],
"vscode": {
"languageId": "raw"
}
},
"source": [
"Not bad. However, when it gets to multiple slices along multiple datasets, it\n",
Expand Down
10 changes: 9 additions & 1 deletion src/erlab/interactive/colors.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,15 @@ def resetCmap(self):


class ColorMapGammaWidget(QtWidgets.QWidget):
valueChanged = QtCore.Signal(float)
"""Slider and spinbox for adjusting colormap gamma.
Signals
-------
valueChanged(float)
"""

valueChanged = QtCore.Signal(float) #: :meta private:

def __init__(
self,
Expand Down

0 comments on commit 87872da

Please sign in to comment.