From 58544e6435c665ace6ea53fc6db42e20d5599568 Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Fri, 20 Oct 2023 09:33:48 -0500 Subject: [PATCH] Refactor: Changes suggested by @hakonanes --- doc/conf.py | 4 ++- doc/dev_guide/contributing.rst | 10 ++----- doc/dev_guide/intro.rst | 6 ++-- doc/intro.rst | 2 +- doc/tutorials/index.rst | 3 +- doc/user_guide/distributed_big_data.rst | 19 ++++++------ doc/user_guide/index.rst | 2 +- doc/user_guide/installing.rst | 32 ++++++++++++-------- doc/user_guide/intro.rst | 14 ++++----- doc/user_guide/loading_data.rst | 4 +-- pyxem/data/_data.py | 40 ++++++++++++++++--------- pyxem/signals/diffraction2d.py | 6 ++-- pyxem/signals/polar_diffraction2d.py | 2 +- readthedocs.yaml | 2 +- setup.py | 2 ++ 15 files changed, 84 insertions(+), 64 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index db14db78e..f4f4acb41 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -52,6 +52,8 @@ "sphinx.ext.inheritance_diagram", "sphinx.ext.intersphinx", "sphinx.ext.napoleon", + "sphinx.ext.linkcode", + "sphinx_codeautolink", "sphinx_gallery.gen_gallery", "sphinx_copybutton", "nbsphinx", @@ -96,7 +98,7 @@ html_theme_options = { "github_url": "https://github.com/pyxem/pyxem", "header_links_before_dropdown": 7, - "navigation_with_keys": False, + "navigation_with_keys": True, "show_toc_level": 2, "use_edit_page_button": True, } diff --git a/doc/dev_guide/contributing.rst b/doc/dev_guide/contributing.rst index 774050ec1..83c0be107 100644 --- a/doc/dev_guide/contributing.rst +++ b/doc/dev_guide/contributing.rst @@ -187,12 +187,8 @@ The easiest way to download the ``pyxem-demos`` repository is to use the ``git c command to checkout the repository. command:: - cd doc/tutorial - git clone https://github.com/pyxem/pyxem-demos.git - -Then, build the documentation from the ``doc`` directory:: - cd doc + git clone https://github.com/pyxem/pyxem-demos.git tutorials/pyxem-demos || echo "You have already cloned this repo try using git pull to update the demos" make html The documentation's HTML pages are built in the ``doc/_build/html`` directory from files @@ -206,10 +202,10 @@ Tips for writing Jupyter notebooks that are meant to be converted to reST text f - Use ``_ = ax[0].imshow(...)`` to disable Matplotlib output if a Matplotlib command is the last line in a cell. -- Refer to our API reference with this general MD +- Refer to our API reference with this general markdown syntax. ``[azimuthal_integrator2d()](reference.rst#pyxem.signals.DiffractionSignal2D.azimuthal_integrator2d)``. Remember to add the parentheses ``()``. -- Reference external APIs via standard MD like +- Reference external APIs via standard markdown like ``[Signal2D](http://hyperspy.org/hyperspy-doc/current/api/hyperspy._signals.signal2d.html)``. - The Sphinx gallery thumbnail used for a notebook is set by adding the ``nbsphinx-thumbnail`` tag to a code cell with an image output. The notebook diff --git a/doc/dev_guide/intro.rst b/doc/dev_guide/intro.rst index 114fa0814..a41b69e8a 100644 --- a/doc/dev_guide/intro.rst +++ b/doc/dev_guide/intro.rst @@ -10,14 +10,14 @@ We welcome contributions of all kinds, including bug reports, feature requests, documentation improvements, and code contributions. The best way to get started is to start using pyxem and share your workflows and data with -us and the community. You can do this by adding notebooks pyxem-demos` which will then be hosted in -the :ref:`tutorials` section of the documentation +us and the community. You can do this by adding notebooks to the ``pyxem-demos`` which will then be hosted in +the :doc:`/tutorials/index` section of the documentation If you have snippits of code that you think would be useful to others, you can also add them to the :ref:`examples` section of the documentation. This is a great way to share your workflows and data with the community! -Other wise the :ref:`contributing` section of the documentation contains more information on how to +The :ref:`contributing` section of the documentation contains more information on how to create a pull request and contribute to the code base! diff --git a/doc/intro.rst b/doc/intro.rst index c3f01c461..97bba8969 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -2,7 +2,7 @@ pyxem's Documentation ===================== -Pyxem is an open source project working to bring together tools for the analysis of +Pyxem is an open-source project working to bring together tools for the analysis of data from pixelated electron detectors. Based on the HyperSpy project, pyxem has an active community of users and developers who are working to develop new tools for 4-D, 5-D STEM and other pixelated electron detector data. diff --git a/doc/tutorials/index.rst b/doc/tutorials/index.rst index 3ef6fbdb5..54b1ac52f 100644 --- a/doc/tutorials/index.rst +++ b/doc/tutorials/index.rst @@ -5,7 +5,8 @@ Tutorials Below are a series of tutorials that demonstrate how to use the ``pyxem`` package. The tutorials are written in Jupyter notebooks -and show complete workflows for common tasks in electron microscopy. +and show complete workflows for common tasks in transmission electron microscopy +analysis. For smaller snippets of code, see the Examples section of the documentation. diff --git a/doc/user_guide/distributed_big_data.rst b/doc/user_guide/distributed_big_data.rst index d53ddda01..2ea33c70f 100644 --- a/doc/user_guide/distributed_big_data.rst +++ b/doc/user_guide/distributed_big_data.rst @@ -3,7 +3,7 @@ Big Data --------- -4-D STEM datasets are large and difficult to work with. In ``pyxem`` we get around this by +4-D STEM datasets are large and difficult to work with. In ``pyxem`` we try to get around this by using a lazy loading approach. This means that the data is not loaded into memory until it is needed. @@ -19,7 +19,7 @@ Loading and Plotting a Dataset ------------------------------ Let's start by loading a dataset. We will use the ``load`` function to load a dataset from -hyperspy +HyperSpy .. code-block:: python @@ -27,23 +27,24 @@ hyperspy >>> s = hs.load("big_data.zspy", lazy=True) >>> s -The dataset here is not loaded into memory here so this should happen instantaneously. We can +The dataset here is not loaded into memory here, so this should happen instantaneously. We can then plot the dataset. .. code-block:: python >>> s.plot() -Which (in general) will be very slow. This is because the data is being loaded into memory and a -navigator image is being generated before the plot is shown. In many cases a HAAADF dataset will be -collected as well as a 4-D STEM dataset. In this case we can set the navigator to the HAAADF dataset instead. +Which (in general) will be very slow. This is because entire dataset is loaded into memory (chuck by chunk) +to create a navigator image. In many cases a HAADF dataset will be collected as well as a 4-D STEM dataset. +In this case we can set the navigator to the HAADF dataset instead. .. code-block:: python - >>> haadf = hs.load("haadf.zspy") # load the HAAADF dataset - >>> s.naviagtor = haadf # set the navigator to the HAAADF dataset + >>> haadf = hs.load("haadf.zspy") # load the HAADF dataset + >>> s.navigator = haadf # set the navigator to the HAADF dataset >>> s.plot() # happens instantaneously -This is much faster now to view the dataset! +This is much faster as the navigator doesn't need to be computed and instead only 1 chunk needs to +be loaded into memory before plotting! Distributed Computing diff --git a/doc/user_guide/index.rst b/doc/user_guide/index.rst index a360b4351..c9d5631f9 100644 --- a/doc/user_guide/index.rst +++ b/doc/user_guide/index.rst @@ -27,7 +27,7 @@ cite.rst open_datasets_workflows.rst related_projects.rst - License + License .. include:: intro.rst \ No newline at end of file diff --git a/doc/user_guide/installing.rst b/doc/user_guide/installing.rst index 8482f399c..1f46a3e41 100644 --- a/doc/user_guide/installing.rst +++ b/doc/user_guide/installing.rst @@ -1,15 +1,15 @@ .. _Installation: - +---------------- Installing pyxem ------------------ +---------------- There are a couple of different ways to install pyxem. The easiest way is to use the -hyperspy-bundle. If you don't have much experience with managing python environments, we -highly recommend using the `hyperspy-bundle` -which is a pre-configured python environment that includes pyxem and all its dependencies. +hyperspy-bundle. If you don't have much experience with managing Python environments, we +highly recommend using the `hyperspy-bundle`. +The bundle is a pre-configured Python environment that includes pyxem and all its dependencies. It includes many other packages that are useful for electron microscopy data analysis, such -as py4dSTEM, AbTEM, and hyperspy. It also includes the Jupyter notebook and Jupyter lab pre-configured +as Py4dSTEM, abTEM, and HyperSpy. It also includes the Jupyter notebook and Jupyter lab pre-configured as well as dask-distributed for parallel computing and the ipywidgets for interactive visualisation. @@ -21,12 +21,18 @@ into an existing environment. The easiest way to do this is using conda/mamba. .. note:: Installing some of the visualization tools such as ipympl install much better using - mamba than conda. If you are having trouble installing pyxem, try using mamba instead + mamba than conda. If you are having trouble installing pyxem, try using mamba instead. + + ipympl is a backend for matplotlib that allows for interactive plotting in the Jupyter + but is particularly a pain sometimes. If you have having trouble you can always change + your url from http://localhost:8888/lab to http://localhost:8888/notebooks and use the + classic notebook instead. There are less features but it is more stable in my experience. ``` -conda install -c conda-forge pyxem + conda install -c conda-forge pyxem ``` + Installing using pip -------------------- @@ -34,7 +40,7 @@ You can also install pyxem using pip if you want. In that case you can install p using ``` -pip install pyxem + pip install pyxem ``` Installing from source @@ -44,17 +50,17 @@ If you want to install the development version of pyxem, you can install it from First clone the repository using ``` -git clone https://github.com/pyxem/pyxem.git + git clone https://github.com/pyxem/pyxem.git ``` -Then cd into the pyxem directory and install the dependencies using +Then navigate into the pyxem directory and install the dependencies using ``` -pip install -r requirements.txt + pip install -r requirements.txt ``` Finally, install pyxem using ``` -pip install . -e + pip install -e . ``` diff --git a/doc/user_guide/intro.rst b/doc/user_guide/intro.rst index dd2ff1aa0..bb2ce195c 100644 --- a/doc/user_guide/intro.rst +++ b/doc/user_guide/intro.rst @@ -11,25 +11,25 @@ There are a number of resources available to help you get started with pyxem: - :ref:`User Guide`: The user guide contains more detailed information on how to use pyxem. It helps you get started with pyxem and contains more detailed information on how to use the different features of pyxem. -- :ref:`Examples`: A collection of small scripts and snippets of code to help preform common +- :ref:`Examples`: A collection of small scripts and snippets of code to help perform common operations. This is a good place to start if you want to build your own analysis. - :ref:`Tutorials`: A collection of tutorials and workflows to help you get started with a wide range of analysis techniques. These are more detailed than the examples and are designed as complete workflows. - :ref:`API Reference`: The API reference contains a description of all the functions and classes in pyxem. This is useful if you are looking for a specific function or want to know what - a function does/ what arguments it takes. It also includes some more detailed information + a function does/what arguments it takes. It also includes some more detailed information on what a function does. - :ref:`Developer Guide`: The developer guide contains information on how to contribute to pyxem! Additionally, there is a bibliography of papers that have used pyxem and a list of related projects. -For more information and additional resources, pyxem inherits from HyperSpy, so you can -also check out the `HyperSpy documentation `_. -All of the HyperSpy documentation is relevant to pyxem, but specifically the -`Big Data `_ section has -lots of useful information on how to work with large datasets. +pyxem inherits lots of functionality from HyperSpy. We suggest that you +also check out the `HyperSpy documentation `_ for +more information and additional resources. All of the HyperSpy documentation is relevant to +pyxem. Especially the `Big Data `_ section, +which has lots of useful information on how to work with large datasets. Developers will also find the `HyperSpy Developer Guide `_ diff --git a/doc/user_guide/loading_data.rst b/doc/user_guide/loading_data.rst index b2320713a..ca4874081 100644 --- a/doc/user_guide/loading_data.rst +++ b/doc/user_guide/loading_data.rst @@ -6,11 +6,11 @@ Loading Data Data can be loaded from many different 4-D STEM detectors using the package `rosettasciio`_. The file types currently supported are listed -`here`_ +`here`_. We are always looking to add more detectors to the list. If you have a detector that you would like to see added, please raise an `issue`_ -on the rosettasciio github page and we will do our best to work with you to add it. +on the rosettasciio GitHub page and we will do our best to work with you to add it. We are also looking to add support for faster loading of data from detectors that we already support. This means adding support for distributed file loading, which allows for operating diff --git a/pyxem/data/_data.py b/pyxem/data/_data.py index aa08a4cb9..6a42d3cca 100644 --- a/pyxem/data/_data.py +++ b/pyxem/data/_data.py @@ -25,11 +25,11 @@ import os # Create a downloader object -marshall = pooch.create( +kipper = pooch.create( path=pooch.os_cache("pyxem"), base_url="", version=version.replace(".dev", "+"), - version_dev="develop", + version_dev="main", env="PYXEM_DATA_DIR", registry=_file_names_hash, urls=_urls, @@ -43,11 +43,13 @@ def au_grating(allow_download=False, **kwargs): ---------- **kwargs Keyword arguments passed to :func:`~hyperspy.api.load`. + Examples -------- >>> import pyxem as pxm >>> s = pxm.data.au_grating() - >>> s + >>> print(s) + >>> s.plot() """ grating = Dataset("au_xgrating_100kX.hspy") @@ -62,11 +64,13 @@ def pdnip_glass(allow_download=False, **kwargs): ---------- **kwargs Keyword arguments passed to :func:`~hyperspy.api.load`. + Examples -------- >>> import pyxem as pxm >>> s = pxm.data.pdnip_glass() - >>> s + >>> print(s) + >>> s.plot() """ import zarr @@ -84,11 +88,13 @@ def zrnb_percipitate(allow_download=False, **kwargs): ---------- **kwargs Keyword arguments passed to :func:`~hyperspy.api.load`. + Examples -------- >>> import pyxem as pxm >>> s = pxm.data.zrnb_percipitate() - >>> s + >>> print(s) + >>> s.plot() """ import zarr @@ -106,11 +112,13 @@ def twinned_nanowire(allow_download=False, **kwargs): ---------- **kwargs Keyword arguments passed to :func:`~hyperspy.api.load`. + Examples -------- >>> import pyxem as pxm >>> s = pxm.data.twinned_nanowire() - >>> s + >>> print(s) + >>> s.plot() """ nanowire = Dataset("twinned_nanowire.hdf5") @@ -125,11 +133,13 @@ def sample_with_g(allow_download=False, **kwargs): ---------- **kwargs Keyword arguments passed to :func:`~hyperspy.api.load`. + Examples -------- >>> import pyxem as pxm >>> s = pxm.data.sample_with_g() - >>> s + >>> print(s) + >>> s.plot() """ import zarr @@ -147,11 +157,13 @@ def mgo_nanocrystals(allow_download=False, **kwargs): ---------- **kwargs Keyword arguments passed to :func:`~hyperspy.api.load`. + Examples -------- >>> import pyxem as pxm >>> s = pxm.data.mgo_nanocrystals() - >>> s + >>> print(s) + >>> s.plot() """ import zarr @@ -180,7 +192,7 @@ def __init__( file_relpath = file_relpath self.file_relpath = file_relpath - self.file_cache_path = Path(marshall.path) / self.file_relpath + self.file_cache_path = Path(kipper.path) / self.file_relpath self.expected_md5_hash = _file_names_hash[self.file_relpath_str] @@ -240,13 +252,13 @@ def url(self) -> Union[str, None]: def fetch_file_path_from_collection( self, downloader: pooch.HTTPDownloader ) -> file_path: # pragma: no cover - file_paths = marshall.fetch( + file_paths = kipper.fetch( os.path.join("data", self.collection_name), downloader=downloader, processor=pooch.Unzip(extract_dir=self.file_directory), ) - os.remove(os.path.join(marshall.path, "data", self.collection_name)) + os.remove(os.path.join(kipper.path, "data", self.collection_name)) # Ensure the file is in the collection desired_name = self.file_relpath.name @@ -292,7 +304,7 @@ def fetch_file_path( else: # pragma: no cover raise ValueError( f"File {self.file_path_str} must be re-downloaded from the " - f"repository file {self.url} to your local cache {marshall.path}. " + f"repository file {self.url} to your local cache {kipper.path}. " "Pass `allow_download=True` to allow this re-download." ) else: @@ -304,8 +316,8 @@ def fetch_file_path( else: raise ValueError( f"File {self.file_relpath_str} must be downloaded from the " - f"repository file {self.url} to your local cache {marshall.path}. " + f"repository file {self.url} to your local cache {kipper.path}. " "Pass `allow_download=True` to allow this download." ) - return marshall.fetch(file_path, downloader=downloader) + return kipper.fetch(file_path, downloader=downloader) diff --git a/pyxem/signals/diffraction2d.py b/pyxem/signals/diffraction2d.py index 25c1da9bd..bcd803813 100644 --- a/pyxem/signals/diffraction2d.py +++ b/pyxem/signals/diffraction2d.py @@ -112,7 +112,7 @@ def apply_affine_transformation( Parameters ---------- D : array or Signal2D of arrays - 3x3 :py: (or Signal2D thereof) specifying the affine transform + 3x3 np.array (or Signal2D thereof) specifying the affine transform to be applied. order : 1,2,3,4 or 5 The order of interpolation on the transform. Default is 1. @@ -1194,8 +1194,8 @@ def template_match_with_binary_image( See Also -------- - :meth:`~pyxem.signals.DiffractionSignal2D.template_match_disk` - :meth:`~pyxem.signals.DiffractionSignal2D.template_match_ring` + `pyxem.signals.DiffractionSignal2D.template_match_disk` + `pyxem.signals.DiffractionSignal2D.template_match_ring` """ return self.template_match( diff --git a/pyxem/signals/polar_diffraction2d.py b/pyxem/signals/polar_diffraction2d.py index 8ecda544d..72598ac4c 100644 --- a/pyxem/signals/polar_diffraction2d.py +++ b/pyxem/signals/polar_diffraction2d.py @@ -145,7 +145,7 @@ def get_full_pearson_correlation( From :meth:`~hyperspy.signal.BaseSignal.map` inplace=True means the signal is overwritten. kwargs: dict - Any additional options for the :meth:`~hyperspy.signal.BaseSignal.map` function + Any additional options for the :meth:`~hyperspy.signal.BaseSignal.map` function. Returns ------- correlation: Signal1D, diff --git a/readthedocs.yaml b/readthedocs.yaml index c0c2ee019..3b363bcbf 100644 --- a/readthedocs.yaml +++ b/readthedocs.yaml @@ -13,7 +13,7 @@ sphinx: # Set the version of Python and other tools -# make demos is a custom command to fetch the demo notebooks +# check-demos is a custom command to fetch the demo notebooks # from the pyxem/pyxem-demos repository build: os: ubuntu-22.04 diff --git a/setup.py b/setup.py index 6893e67cb..e0ffc044c 100644 --- a/setup.py +++ b/setup.py @@ -33,6 +33,8 @@ "sphinx-gallery >= 0.6", "sphinxcontrib-bibtex >= 1.0", "sphinx_design", + "sphinx-codeautolink", + "sphinxl" "pydata-sphinx-theme", "hyperspy-gui-ipywidgets", ],