From f03cf08c51f9ccfbc26af12263307c6c2e79e514 Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Sun, 2 Mar 2025 16:30:59 -0500
Subject: [PATCH 01/19] Create ENVIRONMENT_SETUP.md
---
ENVIRONMENT_SETUP.md | 3 +++
1 file changed, 3 insertions(+)
create mode 100644 ENVIRONMENT_SETUP.md
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.md
new file mode 100644
index 00000000..ebb8a31b
--- /dev/null
+++ b/ENVIRONMENT_SETUP.md
@@ -0,0 +1,3 @@
+Please follow the instructions below to set up an appropriate environment to use PyHyperScattering. All of these setup steps should be run in a terminal, not a Jupyter notebook.
+
+This notebook has been tested in a local JupyterLab notebook using the Anaconda distribution (https://www.anaconda.com/download) on a Windows computer. The instructions below *might* work on other platforms (e.g., NSLS II Jupyterhub, Google Colab), but there are no guarantees; recently, the NSLS II Jupyterhub has been especially incompatible PyHyperScattering.
From 266a4c591b137186b2fb84e237a12c65fe385e3e Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Sun, 2 Mar 2025 16:39:24 -0500
Subject: [PATCH 02/19] Added full set of instructions
---
ENVIRONMENT_SETUP.md | 70 +++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 69 insertions(+), 1 deletion(-)
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.md
index ebb8a31b..ca61e6ba 100644
--- a/ENVIRONMENT_SETUP.md
+++ b/ENVIRONMENT_SETUP.md
@@ -1,3 +1,71 @@
Please follow the instructions below to set up an appropriate environment to use PyHyperScattering. All of these setup steps should be run in a terminal, not a Jupyter notebook.
-This notebook has been tested in a local JupyterLab notebook using the Anaconda distribution (https://www.anaconda.com/download) on a Windows computer. The instructions below *might* work on other platforms (e.g., NSLS II Jupyterhub, Google Colab), but there are no guarantees; recently, the NSLS II Jupyterhub has been especially incompatible PyHyperScattering.
+These instructions have been tested for the use of PyHyperScattering in a local JupyterLab notebook using the Anaconda distribution (https://www.anaconda.com/download) on a Windows computer. The instructions below *might* work for other platforms (e.g., NSLS II Jupyterhub, Google Colab), but there are no guarantees; recently, the NSLS II Jupyterhub has been especially incompatible PyHyperScattering.
+
+To aid this workflow, download Git (https://git-scm.com/download/win). Then in the command prompt (not Anaconda Prompt), run ```winget install --id Git.Git -e --source winget```. After this, if you are able to run ```git --version``` and have a version number outputted, the installation was successful. If Anaconda Prompt was open, it may need to be restarted.
+
+- Open the Anaconda Prompt. Do not use the terminal feature after opening JupyterLab.
+
+- Identify the current conda environment, which appears in parenthases at the beginning of the command prompt. If a conda environment that is not base and is not the desired environment is active, deactivate the conda environment. Do not deactivate the base environment.
+ ```
+ conda deactivate
+ ```
+
+- Create a new environment if a suitable one does not exist. Replace ```YOUR_ENVIRONMENT_NAME``` with a an environment name of choice that does not contain any spaces. If needed, the ```...``` can be replaced with other conda packages to be installed in this environment. The current notebook was run with the ```...``` omitted. After loading some packages, you will be asked if you want to proceed. Enter y (yes).
+ ```
+ conda create -n YOUR_ENVIRONMENT_NAME ipykernel ...
+ ```
+ If there already is an appropriate environment, skip this step. The purpose of the conda environment is to contain the necessary package versions that will enable data reduction and not conflict with other packages.
+
+- Activate the desired environment. After running this command, the selected environment name should appear in parentheses in the command prompt.
+ ```
+ conda activate YOUR_ENVIRONMENT_NAME
+ ```
+ If you do not remember your environment name, you can run ```conda env list``` to display a list of environments that currently exist. If there is an environment you want to delete, first ensure it is not active, and then run ```conda remove -n YOUR_ENVIRONMENT_NAME --all```. The flat ```--all``` removes the entire environment.
+
+- Run the following to add the environment to your Jupyter notebook selection. The display name and environment name do not have to be the same.
+ ```
+ python -m ipykernel install --user --name YOUR_ENVIRONMENT_NAME --display-name YOUR_ENVIRONMENT_NAME
+ ```
+
+- Check the Python version. Use version 3.11 or lower.
+ ```
+ python --version
+ ```
+ If needed, install the correct Python version.
+ ```
+ conda install python==3.11
+ ```
+ This step may be possible to run prior to creating and activating the environment, but this notebook was tested with Python installed after activating the new environment.
+ If a CondaSSL error is encountered during this step, the following solution can be run, and then Python installation can be retried: https://github.com/conda/conda/issues/8273
+
+- Inside the selected environment, install PyHyperScattering and any other necessary packages.
+ - ```pip install pyhyperscattering[bluesky]``` installs PyHyperScattering along with Bluesky-related dependencies needed to access the NSLS II Tiled database. In some cases, it may be necessary to clone and check out a later PyHyperScattering commit or branch instead of the default version. Below are some examples.
+ - ```pip install "git+https://github.com/usnistgov/PyHyperScattering.git#egg=PyHyperScattering[bluesky]"``` installs the latest commit on the main branch.
+ - ```pip install "git+https://github.com/usnistgov/PyHyperScattering.git@Issue170_UpdateDatabrokerImports#egg=PyHyperScattering[bluesky]"``` installs the latest commit on the branch named ```Issue170_UpdateDatabrokerImports```.
+ - ```pip install "git+https://github.com/usnistgov/PyHyperScattering.git@6657973#egg=PyHyperScattering[bluesky]"``` installs commit ```6657973```.
+ - ```pip install pyhyperscattering[ui]``` installs the necessary dependencies to draw a mask. Make sure to install the ```[ui]``` dependencies of the same version/branch/commit of PyHyperScattering used to install the ```[bluesky]``` dependencies.
+ - ```pip install jupyterlab``` is required if using the anaconda distribution but might not be necessary in other cases (e.g., NSLS II JupyterHub, Google Colab)
+ - If planning to test/edit spreadsheet, install the following packages:
+ - ```pip install "git+https://github.com/NSLS-II-SST/rsoxs_scans.git@rsoxsIssue18_SimplifyScans"``` installs the local RSoXS codebase used to set up spreadsheets.
+
+If there are errors during installation or later on, it might be necessary to install additional packages and then retry the pip installs. Below is a list of what might be needed.
+ - Microsoft C++ Build Tools (https://visualstudio.microsoft.com/visual-cpp-build-tools/). This is installed outside the Anaconda prompt. Computer should be restarted after this installation.
+ - ```pip install --upgrade holoviews``` This may be necessary if mask drawing is not working. The ```--upgrade``` is necessary to ensure that the package will get upgraded even if some version of it is currently installed.
+ - ```pip install natsort``` allows use of the natsort package, but is not necessary for the main functioning of PyHyperScattering.
+
+- Start up JupyterLab from the Anaconda command prompt. Do not open JupyterLab using Anaconda's GUI menu.
+ ```
+ jupyter-lab
+ ```
+
+- When prompted to select a kernel, choose the desired environment. If not prompted, ensure that the kernel on the top right-hand corner of the page is set to the correct environment name.
+
+
+Additional resources:
+- Full list of PyHyperScattering dependencies: https://github.com/usnistgov/PyHyperScattering/blob/main/pyproject.toml
+- Further guidance on creating and managing environments: https://jupyter.nsls2.bnl.gov/hub/guide
+- Conda documentation: https://docs.conda.io/projects/conda/en/stable/
+- Xarray documentation: https://docs.xarray.dev/en/stable/
+- Numpy documentation: https://numpy.org/doc/2.1/
+- MatPlotLib documentation: https://matplotlib.org/stable/index.html
From a14ae43e181e753e68596382ed594ea359e3f2c1 Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Sun, 2 Mar 2025 16:39:56 -0500
Subject: [PATCH 03/19] Added a bullet point.
---
ENVIRONMENT_SETUP.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.md
index ca61e6ba..b6055157 100644
--- a/ENVIRONMENT_SETUP.md
+++ b/ENVIRONMENT_SETUP.md
@@ -2,7 +2,7 @@ Please follow the instructions below to set up an appropriate environment to use
These instructions have been tested for the use of PyHyperScattering in a local JupyterLab notebook using the Anaconda distribution (https://www.anaconda.com/download) on a Windows computer. The instructions below *might* work for other platforms (e.g., NSLS II Jupyterhub, Google Colab), but there are no guarantees; recently, the NSLS II Jupyterhub has been especially incompatible PyHyperScattering.
-To aid this workflow, download Git (https://git-scm.com/download/win). Then in the command prompt (not Anaconda Prompt), run ```winget install --id Git.Git -e --source winget```. After this, if you are able to run ```git --version``` and have a version number outputted, the installation was successful. If Anaconda Prompt was open, it may need to be restarted.
+- To aid this workflow, download Git (https://git-scm.com/download/win). Then in the command prompt (not Anaconda Prompt), run ```winget install --id Git.Git -e --source winget```. After this, if you are able to run ```git --version``` and have a version number outputted, the installation was successful. If Anaconda Prompt was open, it may need to be restarted.
- Open the Anaconda Prompt. Do not use the terminal feature after opening JupyterLab.
From dd98ee9b5f2b2d7600aa684bc649a5a107cdf3b8 Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Sun, 2 Mar 2025 16:40:46 -0500
Subject: [PATCH 04/19] Updated indentation
---
ENVIRONMENT_SETUP.md | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.md
index b6055157..ba4f324e 100644
--- a/ENVIRONMENT_SETUP.md
+++ b/ENVIRONMENT_SETUP.md
@@ -49,10 +49,10 @@ These instructions have been tested for the use of PyHyperScattering in a local
- If planning to test/edit spreadsheet, install the following packages:
- ```pip install "git+https://github.com/NSLS-II-SST/rsoxs_scans.git@rsoxsIssue18_SimplifyScans"``` installs the local RSoXS codebase used to set up spreadsheets.
-If there are errors during installation or later on, it might be necessary to install additional packages and then retry the pip installs. Below is a list of what might be needed.
- - Microsoft C++ Build Tools (https://visualstudio.microsoft.com/visual-cpp-build-tools/). This is installed outside the Anaconda prompt. Computer should be restarted after this installation.
- - ```pip install --upgrade holoviews``` This may be necessary if mask drawing is not working. The ```--upgrade``` is necessary to ensure that the package will get upgraded even if some version of it is currently installed.
- - ```pip install natsort``` allows use of the natsort package, but is not necessary for the main functioning of PyHyperScattering.
+ If there are errors during installation or later on, it might be necessary to install additional packages and then retry the pip installs. Below is a list of what might be needed.
+ - Microsoft C++ Build Tools (https://visualstudio.microsoft.com/visual-cpp-build-tools/). This is installed outside the Anaconda prompt. Computer should be restarted after this installation.
+ - ```pip install --upgrade holoviews``` This may be necessary if mask drawing is not working. The ```--upgrade``` is necessary to ensure that the package will get upgraded even if some version of it is currently installed.
+ - ```pip install natsort``` allows use of the natsort package, but is not necessary for the main functioning of PyHyperScattering.
- Start up JupyterLab from the Anaconda command prompt. Do not open JupyterLab using Anaconda's GUI menu.
```
From 86470dd297c5c4e98d9de8192a129c7fa564ebaf Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Sun, 2 Mar 2025 16:41:29 -0500
Subject: [PATCH 05/19] Update ENVIRONMENT_SETUP.md
---
ENVIRONMENT_SETUP.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.md
index ba4f324e..9dbdaffa 100644
--- a/ENVIRONMENT_SETUP.md
+++ b/ENVIRONMENT_SETUP.md
@@ -46,8 +46,6 @@ These instructions have been tested for the use of PyHyperScattering in a local
- ```pip install "git+https://github.com/usnistgov/PyHyperScattering.git@6657973#egg=PyHyperScattering[bluesky]"``` installs commit ```6657973```.
- ```pip install pyhyperscattering[ui]``` installs the necessary dependencies to draw a mask. Make sure to install the ```[ui]``` dependencies of the same version/branch/commit of PyHyperScattering used to install the ```[bluesky]``` dependencies.
- ```pip install jupyterlab``` is required if using the anaconda distribution but might not be necessary in other cases (e.g., NSLS II JupyterHub, Google Colab)
- - If planning to test/edit spreadsheet, install the following packages:
- - ```pip install "git+https://github.com/NSLS-II-SST/rsoxs_scans.git@rsoxsIssue18_SimplifyScans"``` installs the local RSoXS codebase used to set up spreadsheets.
If there are errors during installation or later on, it might be necessary to install additional packages and then retry the pip installs. Below is a list of what might be needed.
- Microsoft C++ Build Tools (https://visualstudio.microsoft.com/visual-cpp-build-tools/). This is installed outside the Anaconda prompt. Computer should be restarted after this installation.
@@ -62,6 +60,8 @@ These instructions have been tested for the use of PyHyperScattering in a local
- When prompted to select a kernel, choose the desired environment. If not prompted, ensure that the kernel on the top right-hand corner of the page is set to the correct environment name.
+
+
Additional resources:
- Full list of PyHyperScattering dependencies: https://github.com/usnistgov/PyHyperScattering/blob/main/pyproject.toml
- Further guidance on creating and managing environments: https://jupyter.nsls2.bnl.gov/hub/guide
From aab3bcfcef01602b28765e2626403e3a15d3fa12 Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Sun, 2 Mar 2025 16:41:52 -0500
Subject: [PATCH 06/19] Removed a bullet and added extra lines
---
ENVIRONMENT_SETUP.md | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.md
index 9dbdaffa..4553ce33 100644
--- a/ENVIRONMENT_SETUP.md
+++ b/ENVIRONMENT_SETUP.md
@@ -61,7 +61,8 @@ These instructions have been tested for the use of PyHyperScattering in a local
-
+
+
Additional resources:
- Full list of PyHyperScattering dependencies: https://github.com/usnistgov/PyHyperScattering/blob/main/pyproject.toml
- Further guidance on creating and managing environments: https://jupyter.nsls2.bnl.gov/hub/guide
From 18884ad54f38db31a523f879f6536b9d4b05bc0b Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Sun, 2 Mar 2025 16:42:55 -0500
Subject: [PATCH 07/19] Added some extra blank lines.
---
ENVIRONMENT_SETUP.md | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.md
index 4553ce33..850f59fa 100644
--- a/ENVIRONMENT_SETUP.md
+++ b/ENVIRONMENT_SETUP.md
@@ -2,6 +2,9 @@ Please follow the instructions below to set up an appropriate environment to use
These instructions have been tested for the use of PyHyperScattering in a local JupyterLab notebook using the Anaconda distribution (https://www.anaconda.com/download) on a Windows computer. The instructions below *might* work for other platforms (e.g., NSLS II Jupyterhub, Google Colab), but there are no guarantees; recently, the NSLS II Jupyterhub has been especially incompatible PyHyperScattering.
+
+
+
- To aid this workflow, download Git (https://git-scm.com/download/win). Then in the command prompt (not Anaconda Prompt), run ```winget install --id Git.Git -e --source winget```. After this, if you are able to run ```git --version``` and have a version number outputted, the installation was successful. If Anaconda Prompt was open, it may need to be restarted.
- Open the Anaconda Prompt. Do not use the terminal feature after opening JupyterLab.
@@ -63,6 +66,7 @@ These instructions have been tested for the use of PyHyperScattering in a local
+
Additional resources:
- Full list of PyHyperScattering dependencies: https://github.com/usnistgov/PyHyperScattering/blob/main/pyproject.toml
- Further guidance on creating and managing environments: https://jupyter.nsls2.bnl.gov/hub/guide
From 06ac6dd8271e4e6bf61b27e1e306f721948f0757 Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Sun, 2 Mar 2025 16:46:42 -0500
Subject: [PATCH 08/19] Changed some wording regarding python installation.
---
ENVIRONMENT_SETUP.md | 1 -
1 file changed, 1 deletion(-)
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.md
index 850f59fa..810e2982 100644
--- a/ENVIRONMENT_SETUP.md
+++ b/ENVIRONMENT_SETUP.md
@@ -39,7 +39,6 @@ These instructions have been tested for the use of PyHyperScattering in a local
```
conda install python==3.11
```
- This step may be possible to run prior to creating and activating the environment, but this notebook was tested with Python installed after activating the new environment.
If a CondaSSL error is encountered during this step, the following solution can be run, and then Python installation can be retried: https://github.com/conda/conda/issues/8273
- Inside the selected environment, install PyHyperScattering and any other necessary packages.
From f72f27c9ef16bacbe2934d21a3cdbc33958f4351 Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Sun, 2 Mar 2025 16:47:57 -0500
Subject: [PATCH 09/19] Fixed capitalization
---
ENVIRONMENT_SETUP.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.md
index 810e2982..44e304e0 100644
--- a/ENVIRONMENT_SETUP.md
+++ b/ENVIRONMENT_SETUP.md
@@ -47,7 +47,7 @@ These instructions have been tested for the use of PyHyperScattering in a local
- ```pip install "git+https://github.com/usnistgov/PyHyperScattering.git@Issue170_UpdateDatabrokerImports#egg=PyHyperScattering[bluesky]"``` installs the latest commit on the branch named ```Issue170_UpdateDatabrokerImports```.
- ```pip install "git+https://github.com/usnistgov/PyHyperScattering.git@6657973#egg=PyHyperScattering[bluesky]"``` installs commit ```6657973```.
- ```pip install pyhyperscattering[ui]``` installs the necessary dependencies to draw a mask. Make sure to install the ```[ui]``` dependencies of the same version/branch/commit of PyHyperScattering used to install the ```[bluesky]``` dependencies.
- - ```pip install jupyterlab``` is required if using the anaconda distribution but might not be necessary in other cases (e.g., NSLS II JupyterHub, Google Colab)
+ - ```pip install jupyterlab``` is required if using the Anaconda distribution but might not be necessary in other cases (e.g., NSLS II JupyterHub, Google Colab)
If there are errors during installation or later on, it might be necessary to install additional packages and then retry the pip installs. Below is a list of what might be needed.
- Microsoft C++ Build Tools (https://visualstudio.microsoft.com/visual-cpp-build-tools/). This is installed outside the Anaconda prompt. Computer should be restarted after this installation.
From cce88b8bf1c787f8604cdb8b8561285a6d860e08 Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Sun, 2 Mar 2025 16:50:20 -0500
Subject: [PATCH 10/19] Added a bullet.
---
ENVIRONMENT_SETUP.md | 2 ++
1 file changed, 2 insertions(+)
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.md
index 44e304e0..779d9ff5 100644
--- a/ENVIRONMENT_SETUP.md
+++ b/ENVIRONMENT_SETUP.md
@@ -61,6 +61,8 @@ These instructions have been tested for the use of PyHyperScattering in a local
- When prompted to select a kernel, choose the desired environment. If not prompted, ensure that the kernel on the top right-hand corner of the page is set to the correct environment name.
+- Proceed to using a Jupyter notebook of choice to reduce and analyze data.
+
From 9405c8c8ff9679e509f159ef9d56788efe493500 Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Mon, 3 Mar 2025 21:29:00 -0500
Subject: [PATCH 11/19] Create environment_setup.rst
---
docs/source/getting_started/environment_setup.rst | 12 ++++++++++++
1 file changed, 12 insertions(+)
create mode 100644 docs/source/getting_started/environment_setup.rst
diff --git a/docs/source/getting_started/environment_setup.rst b/docs/source/getting_started/environment_setup.rst
new file mode 100644
index 00000000..fb53679b
--- /dev/null
+++ b/docs/source/getting_started/environment_setup.rst
@@ -0,0 +1,12 @@
+Set up Python
+================
+
+Please follow the instructions below to set up an appropriate environment to use PyHyperScattering. All of these setup steps should be run in a terminal, not a Jupyter notebook.
+
+These instructions have been tested for the use of PyHyperScattering in a local JupyterLab notebook using the Anaconda distribution (https://www.anaconda.com/download) on a Windows computer. The instructions below *might* work for other platforms (e.g., NSLS II Jupyterhub, Google Colab), but there are no guarantees; recently, the NSLS II Jupyterhub has been especially incompatible PyHyperScattering.
+
+
+ Download Git
+ ---------------
+
+
From aed3ffafe22c09313ffb161a94961064951435fa Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Mon, 3 Mar 2025 21:31:14 -0500
Subject: [PATCH 12/19] Trying to apply formatting
---
docs/source/getting_started/environment_setup.rst | 2 ++
1 file changed, 2 insertions(+)
diff --git a/docs/source/getting_started/environment_setup.rst b/docs/source/getting_started/environment_setup.rst
index fb53679b..b5436b15 100644
--- a/docs/source/getting_started/environment_setup.rst
+++ b/docs/source/getting_started/environment_setup.rst
@@ -1,3 +1,5 @@
+.. _Set_up_Python:
+
Set up Python
================
From ce04198add861cdc6640e2e68c299f442467cbe3 Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Mon, 3 Mar 2025 21:33:52 -0500
Subject: [PATCH 13/19] Trying to make headers
---
docs/source/getting_started/environment_setup.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/source/getting_started/environment_setup.rst b/docs/source/getting_started/environment_setup.rst
index b5436b15..7a2b35ed 100644
--- a/docs/source/getting_started/environment_setup.rst
+++ b/docs/source/getting_started/environment_setup.rst
@@ -1,7 +1,7 @@
.. _Set_up_Python:
Set up Python
-================
+=============
Please follow the instructions below to set up an appropriate environment to use PyHyperScattering. All of these setup steps should be run in a terminal, not a Jupyter notebook.
@@ -9,6 +9,6 @@ These instructions have been tested for the use of PyHyperScattering in a local
Download Git
- ---------------
+ ------------
From 2cfc014f1d7d52a83fa073102cd2d8ddedd987f7 Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Mon, 3 Mar 2025 21:40:57 -0500
Subject: [PATCH 14/19] Added instructions to create and activate environment
---
.../getting_started/environment_setup.rst | 43 ++++++++++++++++---
1 file changed, 36 insertions(+), 7 deletions(-)
diff --git a/docs/source/getting_started/environment_setup.rst b/docs/source/getting_started/environment_setup.rst
index 7a2b35ed..8b394163 100644
--- a/docs/source/getting_started/environment_setup.rst
+++ b/docs/source/getting_started/environment_setup.rst
@@ -3,12 +3,41 @@
Set up Python
=============
-Please follow the instructions below to set up an appropriate environment to use PyHyperScattering. All of these setup steps should be run in a terminal, not a Jupyter notebook.
+Please follow the instructions below to set up an appropriate environment to use PyHyperScattering. All of these setup steps should be run in a terminal, not a Jupyter notebook.
-These instructions have been tested for the use of PyHyperScattering in a local JupyterLab notebook using the Anaconda distribution (https://www.anaconda.com/download) on a Windows computer. The instructions below *might* work for other platforms (e.g., NSLS II Jupyterhub, Google Colab), but there are no guarantees; recently, the NSLS II Jupyterhub has been especially incompatible PyHyperScattering.
+These instructions have been tested for the use of PyHyperScattering in a local JupyterLab notebook using the Anaconda distribution (https://www.anaconda.com/download) on a Windows computer. The instructions below *might* work for other platforms (e.g., NSLS II Jupyterhub, Google Colab), but there are no guarantees; recently, the NSLS II Jupyterhub has been especially incompatible PyHyperScattering.
-
- Download Git
- ------------
-
-
+Download Git
+------------
+
+To aid this workflow, download Git (https://git-scm.com/download/win). Then in the command prompt (not Anaconda Prompt), run ``winget install --id Git.Git -e --source winget``. After this, if you are able to run ``git --version`` and have a version number outputted, the installation was successful. If Anaconda Prompt was open, it may need to be restarted.
+
+Create and activate an environment
+----------------------------------
+
+- Open the Anaconda Prompt. Do not use the terminal feature after opening JupyterLab.
+
+- Identify the current conda environment, which appears in parenthases at the beginning of the command prompt. If a conda environment that is not base and is not the desired environment is active, deactivate the conda environment. Do not deactivate the base environment.
+ .. code-block:: bash
+
+ conda deactivate
+
+- Create a new environment if a suitable one does not exist. Replace ``YOUR_ENVIRONMENT_NAME`` with a an environment name of choice that does not contain any spaces. If needed, the ``...`` can be replaced with other conda packages to be installed in this environment. The current notebook was run with the ``...`` omitted. After loading some packages, you will be asked if you want to proceed. Enter y (yes).
+ .. code-block:: bash
+
+ conda create -n YOUR_ENVIRONMENT_NAME ipykernel ...
+
+ If there already is an appropriate environment, skip this step. The purpose of the conda environment is to contain the necessary package versions that will enable data reduction and not conflict with other packages.
+
+- Activate the desired environment. After running this command, the selected environment name should appear in parentheses in the command prompt.
+ .. code-block:: bash
+
+ conda activate YOUR_ENVIRONMENT_NAME
+
+ If you do not remember your environment name, you can run ``conda env list`` to display a list of environments that currently exist. If there is an environment you want to delete, first ensure it is not active, and then run ``conda remove -n YOUR_ENVIRONMENT_NAME --all``. The flat ``--all`` removes the entire environment.
+
+- Run the following to add the environment to your Jupyter notebook selection. The display name and environment name do not have to be the same.
+ .. code-block:: bash
+
+ python -m ipykernel install --user --name YOUR_ENVIRONMENT_NAME --display-name YOUR_ENVIRONMENT_NAME
+
From 4c53e279c5e1038e50a8b19c5d553f34c0413a6b Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Mon, 3 Mar 2025 22:13:04 -0500
Subject: [PATCH 15/19] Deleting .md file and moving to docs
---
ENVIRONMENT_SETUP.md | 77 --------------------------------------------
1 file changed, 77 deletions(-)
delete mode 100644 ENVIRONMENT_SETUP.md
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.md
deleted file mode 100644
index 779d9ff5..00000000
--- a/ENVIRONMENT_SETUP.md
+++ /dev/null
@@ -1,77 +0,0 @@
-Please follow the instructions below to set up an appropriate environment to use PyHyperScattering. All of these setup steps should be run in a terminal, not a Jupyter notebook.
-
-These instructions have been tested for the use of PyHyperScattering in a local JupyterLab notebook using the Anaconda distribution (https://www.anaconda.com/download) on a Windows computer. The instructions below *might* work for other platforms (e.g., NSLS II Jupyterhub, Google Colab), but there are no guarantees; recently, the NSLS II Jupyterhub has been especially incompatible PyHyperScattering.
-
-
-
-
-- To aid this workflow, download Git (https://git-scm.com/download/win). Then in the command prompt (not Anaconda Prompt), run ```winget install --id Git.Git -e --source winget```. After this, if you are able to run ```git --version``` and have a version number outputted, the installation was successful. If Anaconda Prompt was open, it may need to be restarted.
-
-- Open the Anaconda Prompt. Do not use the terminal feature after opening JupyterLab.
-
-- Identify the current conda environment, which appears in parenthases at the beginning of the command prompt. If a conda environment that is not base and is not the desired environment is active, deactivate the conda environment. Do not deactivate the base environment.
- ```
- conda deactivate
- ```
-
-- Create a new environment if a suitable one does not exist. Replace ```YOUR_ENVIRONMENT_NAME``` with a an environment name of choice that does not contain any spaces. If needed, the ```...``` can be replaced with other conda packages to be installed in this environment. The current notebook was run with the ```...``` omitted. After loading some packages, you will be asked if you want to proceed. Enter y (yes).
- ```
- conda create -n YOUR_ENVIRONMENT_NAME ipykernel ...
- ```
- If there already is an appropriate environment, skip this step. The purpose of the conda environment is to contain the necessary package versions that will enable data reduction and not conflict with other packages.
-
-- Activate the desired environment. After running this command, the selected environment name should appear in parentheses in the command prompt.
- ```
- conda activate YOUR_ENVIRONMENT_NAME
- ```
- If you do not remember your environment name, you can run ```conda env list``` to display a list of environments that currently exist. If there is an environment you want to delete, first ensure it is not active, and then run ```conda remove -n YOUR_ENVIRONMENT_NAME --all```. The flat ```--all``` removes the entire environment.
-
-- Run the following to add the environment to your Jupyter notebook selection. The display name and environment name do not have to be the same.
- ```
- python -m ipykernel install --user --name YOUR_ENVIRONMENT_NAME --display-name YOUR_ENVIRONMENT_NAME
- ```
-
-- Check the Python version. Use version 3.11 or lower.
- ```
- python --version
- ```
- If needed, install the correct Python version.
- ```
- conda install python==3.11
- ```
- If a CondaSSL error is encountered during this step, the following solution can be run, and then Python installation can be retried: https://github.com/conda/conda/issues/8273
-
-- Inside the selected environment, install PyHyperScattering and any other necessary packages.
- - ```pip install pyhyperscattering[bluesky]``` installs PyHyperScattering along with Bluesky-related dependencies needed to access the NSLS II Tiled database. In some cases, it may be necessary to clone and check out a later PyHyperScattering commit or branch instead of the default version. Below are some examples.
- - ```pip install "git+https://github.com/usnistgov/PyHyperScattering.git#egg=PyHyperScattering[bluesky]"``` installs the latest commit on the main branch.
- - ```pip install "git+https://github.com/usnistgov/PyHyperScattering.git@Issue170_UpdateDatabrokerImports#egg=PyHyperScattering[bluesky]"``` installs the latest commit on the branch named ```Issue170_UpdateDatabrokerImports```.
- - ```pip install "git+https://github.com/usnistgov/PyHyperScattering.git@6657973#egg=PyHyperScattering[bluesky]"``` installs commit ```6657973```.
- - ```pip install pyhyperscattering[ui]``` installs the necessary dependencies to draw a mask. Make sure to install the ```[ui]``` dependencies of the same version/branch/commit of PyHyperScattering used to install the ```[bluesky]``` dependencies.
- - ```pip install jupyterlab``` is required if using the Anaconda distribution but might not be necessary in other cases (e.g., NSLS II JupyterHub, Google Colab)
-
- If there are errors during installation or later on, it might be necessary to install additional packages and then retry the pip installs. Below is a list of what might be needed.
- - Microsoft C++ Build Tools (https://visualstudio.microsoft.com/visual-cpp-build-tools/). This is installed outside the Anaconda prompt. Computer should be restarted after this installation.
- - ```pip install --upgrade holoviews``` This may be necessary if mask drawing is not working. The ```--upgrade``` is necessary to ensure that the package will get upgraded even if some version of it is currently installed.
- - ```pip install natsort``` allows use of the natsort package, but is not necessary for the main functioning of PyHyperScattering.
-
-- Start up JupyterLab from the Anaconda command prompt. Do not open JupyterLab using Anaconda's GUI menu.
- ```
- jupyter-lab
- ```
-
-- When prompted to select a kernel, choose the desired environment. If not prompted, ensure that the kernel on the top right-hand corner of the page is set to the correct environment name.
-
-- Proceed to using a Jupyter notebook of choice to reduce and analyze data.
-
-
-
-
-
-
-Additional resources:
-- Full list of PyHyperScattering dependencies: https://github.com/usnistgov/PyHyperScattering/blob/main/pyproject.toml
-- Further guidance on creating and managing environments: https://jupyter.nsls2.bnl.gov/hub/guide
-- Conda documentation: https://docs.conda.io/projects/conda/en/stable/
-- Xarray documentation: https://docs.xarray.dev/en/stable/
-- Numpy documentation: https://numpy.org/doc/2.1/
-- MatPlotLib documentation: https://matplotlib.org/stable/index.html
From 13ca473bce484c966dd8805ca5fffc1203a25cae Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Mon, 3 Mar 2025 22:14:28 -0500
Subject: [PATCH 16/19] Copied over contents of .md file to .rst formatting.
Would like to change text color, but haven't figured that out yet.
---
.../getting_started/environment_setup.rst | 91 +++++++++++++++++--
1 file changed, 84 insertions(+), 7 deletions(-)
diff --git a/docs/source/getting_started/environment_setup.rst b/docs/source/getting_started/environment_setup.rst
index 8b394163..67c96bbb 100644
--- a/docs/source/getting_started/environment_setup.rst
+++ b/docs/source/getting_started/environment_setup.rst
@@ -17,27 +17,104 @@ Create and activate an environment
- Open the Anaconda Prompt. Do not use the terminal feature after opening JupyterLab.
-- Identify the current conda environment, which appears in parenthases at the beginning of the command prompt. If a conda environment that is not base and is not the desired environment is active, deactivate the conda environment. Do not deactivate the base environment.
+- Identify the current conda environment, which appears in parentheses at the beginning of the command prompt. If a conda environment that is not base and is not the desired environment is active, deactivate the conda environment. Do not deactivate the base environment.
+
.. code-block:: bash
- conda deactivate
+ conda deactivate
- Create a new environment if a suitable one does not exist. Replace ``YOUR_ENVIRONMENT_NAME`` with a an environment name of choice that does not contain any spaces. If needed, the ``...`` can be replaced with other conda packages to be installed in this environment. The current notebook was run with the ``...`` omitted. After loading some packages, you will be asked if you want to proceed. Enter y (yes).
+
.. code-block:: bash
-
- conda create -n YOUR_ENVIRONMENT_NAME ipykernel ...
+ conda create -n YOUR_ENVIRONMENT_NAME ipykernel ...
+
If there already is an appropriate environment, skip this step. The purpose of the conda environment is to contain the necessary package versions that will enable data reduction and not conflict with other packages.
- Activate the desired environment. After running this command, the selected environment name should appear in parentheses in the command prompt.
+
.. code-block:: bash
-
- conda activate YOUR_ENVIRONMENT_NAME
+
+ conda activate YOUR_ENVIRONMENT_NAME
If you do not remember your environment name, you can run ``conda env list`` to display a list of environments that currently exist. If there is an environment you want to delete, first ensure it is not active, and then run ``conda remove -n YOUR_ENVIRONMENT_NAME --all``. The flat ``--all`` removes the entire environment.
- Run the following to add the environment to your Jupyter notebook selection. The display name and environment name do not have to be the same.
+
.. code-block:: bash
+
+ python -m ipykernel install --user --name YOUR_ENVIRONMENT_NAME --display-name YOUR_ENVIRONMENT_NAME
+
+Install packages and dependencies
+---------------------------------
+
+Install Python
+~~~~~~~~~~~~~~
- python -m ipykernel install --user --name YOUR_ENVIRONMENT_NAME --display-name YOUR_ENVIRONMENT_NAME
+Check the Python version. Use version 3.11 or lower for PyHyperScattering to work.
+
+.. code-block:: bash
+
+ python --version
+
+If needed, install the correct Python version.
+
+.. code-block:: bash
+
+ conda install python==3.11
+If a CondaSSL error is encountered during this step, the following solution can be run, and then Python installation can be retried: https://github.com/conda/conda/issues/8273
+
+Install PyHyperScattering
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``pip install pyhyperscattering[bluesky]`` installs PyHyperScattering along with Bluesky-related dependencies needed to access the NSLS II Tiled database. In some cases, it may be necessary to clone and check out a later PyHyperScattering commit or branch instead of the default version. Below are some examples.
+
+- ``pip install "git+https://github.com/usnistgov/PyHyperScattering.git#egg=PyHyperScattering[bluesky]"`` installs the latest commit on the main branch.
+
+- ``pip install "git+https://github.com/usnistgov/PyHyperScattering.git@Issue170_UpdateDatabrokerImports#egg=PyHyperScattering[bluesky]"`` installs the latest commit on the branch named ``Issue170_UpdateDatabrokerImports``.
+
+- ``pip install "git+https://github.com/usnistgov/PyHyperScattering.git@6657973#egg=PyHyperScattering[bluesky]"`` installs commit ``6657973``.
+
+``pip install pyhyperscattering[ui]`` installs the necessary dependencies to draw a mask. Make sure to install the ``[ui]`` dependencies of the same version/branch/commit of PyHyperScattering used to install the ``[bluesky]`` dependencies.
+
+Install JupyterLab
+~~~~~~~~~~~~~~~~~~
+
+``pip install jupyterlab`` is required if using the Anaconda distribution but might not be necessary in other cases (e.g., NSLS II JupyterHub, Google Colab)
+
+Other installs
+~~~~~~~~~~~~~~
+
+If there are errors during installation or later on, it might be necessary to install additional packages and then retry the pip installs. Below is a list of what might be needed.
+
+- Microsoft C++ Build Tools (https://visualstudio.microsoft.com/visual-cpp-build-tools/). This is installed outside the Anaconda prompt. Computer should be restarted after this installation.
+
+- ``pip install --upgrade holoviews`` This may be necessary if mask drawing is not working. The ``--upgrade`` is necessary to ensure that the package will get upgraded even if some version of it is currently installed.
+
+- ``pip install natsort`` allows use of the natsort package, but is not necessary for the main functioning of PyHyperScattering.
+
+
+Open JupyterLab
+---------------
+
+- Start up JupyterLab from the Anaconda command prompt. Do not open JupyterLab using Anaconda's GUI menu.
+
+ .. code-block:: bash
+
+ jupyter-lab
+
+- When prompted to select a kernel, choose the desired environment. If not prompted, ensure that the kernel on the top right-hand corner of the page is set to the correct environment name.
+
+- Proceed to using a Jupyter notebook of choice to reduce and analyze data.
+
+
+Additional resources
+--------------------
+- Full list of PyHyperScattering dependencies: https://github.com/usnistgov/PyHyperScattering/blob/main/pyproject.toml
+- Further guidance on creating and managing environments: https://jupyter.nsls2.bnl.gov/hub/guide
+- Conda documentation: https://docs.conda.io/projects/conda/en/stable/
+- Xarray documentation: https://docs.xarray.dev/en/stable/
+- Numpy documentation: https://numpy.org/doc/2.1/
+- MatPlotLib documentation: https://matplotlib.org/stable/index.html
+
From 3c1f16a6561281c80cefcbeb805d77552bb8506c Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Mon, 31 Mar 2025 11:54:17 -0400
Subject: [PATCH 17/19] Checked that pip installing PyHyperScattering with
[bluesky,ui] works the same as pip installing with bluesky and ui on separate
lines
---
docs/source/getting_started/environment_setup.rst | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/docs/source/getting_started/environment_setup.rst b/docs/source/getting_started/environment_setup.rst
index 67c96bbb..b2aada6d 100644
--- a/docs/source/getting_started/environment_setup.rst
+++ b/docs/source/getting_started/environment_setup.rst
@@ -68,7 +68,7 @@ If a CondaSSL error is encountered during this step, the following solution can
Install PyHyperScattering
~~~~~~~~~~~~~~~~~~~~~~~~~
-``pip install pyhyperscattering[bluesky]`` installs PyHyperScattering along with Bluesky-related dependencies needed to access the NSLS II Tiled database. In some cases, it may be necessary to clone and check out a later PyHyperScattering commit or branch instead of the default version. Below are some examples.
+``pip install pyhyperscattering[bluesky, ui]`` installs PyHyperScattering. The ``bluesky`` portion installs Bluesky-related dependencies needed to access the NSLS II Tiled database. The ``ui`` portion installs the necessary dependencies to draw a mask. In some cases, it may be necessary to clone and check out a later PyHyperScattering commit or branch instead of the default version. Below are some examples.
- ``pip install "git+https://github.com/usnistgov/PyHyperScattering.git#egg=PyHyperScattering[bluesky]"`` installs the latest commit on the main branch.
@@ -76,7 +76,6 @@ Install PyHyperScattering
- ``pip install "git+https://github.com/usnistgov/PyHyperScattering.git@6657973#egg=PyHyperScattering[bluesky]"`` installs commit ``6657973``.
-``pip install pyhyperscattering[ui]`` installs the necessary dependencies to draw a mask. Make sure to install the ``[ui]`` dependencies of the same version/branch/commit of PyHyperScattering used to install the ``[bluesky]`` dependencies.
Install JupyterLab
~~~~~~~~~~~~~~~~~~
From 6b749255752126f136adcbd88d8832aebf96dae9 Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Mon, 31 Mar 2025 11:55:07 -0400
Subject: [PATCH 18/19] Propagated some changes from prior commit
---
docs/source/getting_started/environment_setup.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/source/getting_started/environment_setup.rst b/docs/source/getting_started/environment_setup.rst
index b2aada6d..b47a4402 100644
--- a/docs/source/getting_started/environment_setup.rst
+++ b/docs/source/getting_started/environment_setup.rst
@@ -70,11 +70,11 @@ Install PyHyperScattering
``pip install pyhyperscattering[bluesky, ui]`` installs PyHyperScattering. The ``bluesky`` portion installs Bluesky-related dependencies needed to access the NSLS II Tiled database. The ``ui`` portion installs the necessary dependencies to draw a mask. In some cases, it may be necessary to clone and check out a later PyHyperScattering commit or branch instead of the default version. Below are some examples.
-- ``pip install "git+https://github.com/usnistgov/PyHyperScattering.git#egg=PyHyperScattering[bluesky]"`` installs the latest commit on the main branch.
+- ``pip install "git+https://github.com/usnistgov/PyHyperScattering.git#egg=PyHyperScattering[bluesky, ui]"`` installs the latest commit on the main branch.
-- ``pip install "git+https://github.com/usnistgov/PyHyperScattering.git@Issue170_UpdateDatabrokerImports#egg=PyHyperScattering[bluesky]"`` installs the latest commit on the branch named ``Issue170_UpdateDatabrokerImports``.
+- ``pip install "git+https://github.com/usnistgov/PyHyperScattering.git@Issue170_UpdateDatabrokerImports#egg=PyHyperScattering[bluesky, ui]"`` installs the latest commit on the branch named ``Issue170_UpdateDatabrokerImports``.
-- ``pip install "git+https://github.com/usnistgov/PyHyperScattering.git@6657973#egg=PyHyperScattering[bluesky]"`` installs commit ``6657973``.
+- ``pip install "git+https://github.com/usnistgov/PyHyperScattering.git@6657973#egg=PyHyperScattering[bluesky, ui]"`` installs commit ``6657973``.
Install JupyterLab
From 9387954e07128ab66a256d3489a3c817ba1a04a9 Mon Sep 17 00:00:00 2001
From: PriyankaKetkarBNL <155195376+PriyankaKetkarBNL@users.noreply.github.com>
Date: Wed, 2 Apr 2025 13:01:16 -0400
Subject: [PATCH 19/19] Removed comma
---
docs/source/getting_started/environment_setup.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/source/getting_started/environment_setup.rst b/docs/source/getting_started/environment_setup.rst
index b47a4402..0cef4ddc 100644
--- a/docs/source/getting_started/environment_setup.rst
+++ b/docs/source/getting_started/environment_setup.rst
@@ -68,7 +68,7 @@ If a CondaSSL error is encountered during this step, the following solution can
Install PyHyperScattering
~~~~~~~~~~~~~~~~~~~~~~~~~
-``pip install pyhyperscattering[bluesky, ui]`` installs PyHyperScattering. The ``bluesky`` portion installs Bluesky-related dependencies needed to access the NSLS II Tiled database. The ``ui`` portion installs the necessary dependencies to draw a mask. In some cases, it may be necessary to clone and check out a later PyHyperScattering commit or branch instead of the default version. Below are some examples.
+``pip install pyhyperscattering[bluesky,ui]`` installs PyHyperScattering. The ``bluesky`` portion installs Bluesky-related dependencies needed to access the NSLS II Tiled database. The ``ui`` portion installs the necessary dependencies to draw a mask. In some cases, it may be necessary to clone and check out a later PyHyperScattering commit or branch instead of the default version. Below are some examples.
- ``pip install "git+https://github.com/usnistgov/PyHyperScattering.git#egg=PyHyperScattering[bluesky, ui]"`` installs the latest commit on the main branch.