From 21636ed7478f6e24673c7bb40959d351b7c5ab98 Mon Sep 17 00:00:00 2001 From: Jake Rosenberg Date: Mon, 27 Oct 2025 15:31:02 -0500 Subject: [PATCH] move technical details to 'Publishing Notebooks' section --- .../tools/jupyterhub/publishingnotebooks.md | 41 +++++++++++++++---- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/user-guide/docs/tools/jupyterhub/publishingnotebooks.md b/user-guide/docs/tools/jupyterhub/publishingnotebooks.md index b3773986..8a06a372 100644 --- a/user-guide/docs/tools/jupyterhub/publishingnotebooks.md +++ b/user-guide/docs/tools/jupyterhub/publishingnotebooks.md @@ -4,15 +4,38 @@ More and more researchers are publishing projects that contain Jupyter Notebooks As you plan for publishing a Jupyter Notebook, please consider the following issues: -1. The DesignSafe publication process involves copying the contents of your project at the time of publication to a read only space within the Published projects section of the Data Depot (i.e., this directory can be accessed at NHERI-Published in JupyterHub). Any future user of your notebook will access it in the read only Published projects section. Therefore, any local path you are using while developing your notebook that is accessing a file from a private space (e.g., "MyData", "MyProjects") will need to be replaced by an absolute path to the published project. - - Consider this example: you are developing a notebook in PRJ-0000 located in your "MyProjects" directory and you are reading a csv file living in this project at this path: - - /home/jupyter/MyProjects/PRJ-0000/Foo.csv - - Before publishing the notebook, you must change the path to this csv file to: - - /home/jupyter/NHERI-Published/PRJ-0000/Foo.csv +1. The DesignSafe publication process involves copying the contents of your project at the time of publication to a read only space within the Published projects section of the Data Depot (i.e., this directory can be accessed at NHERI-Published in JupyterHub). Any future user of your notebook will access it in the read-only Published projects section. By using relative paths in your Jupyter notebook, you can improve its portability and reproducibility. An **absolute path** starts with the `/` character and contains the complete address of the file starting from the root of your file system, for example: + ``` + /home/usr/data.csv + ``` + In contrast, a **relative path** describes the path of a file *relative* to the current open file or working directory. If a Jupyter notebook and its associated data are moved or copied to a different device, any absolute paths used in the notebook are at risk of becoming inaccessible. However, as long as the local directory structure is preserved, notebooks that refer to relative paths will continue to work in any computational environment. Here is an example of a directory structure that might exist in a DesignSafe project: + ``` + /corral/projects/NHERI/projects/PRJ-1234/ + ├─ notebooks/ + │ ├─ notebook.ipynb + │ ├─ readme_files/ + │ │ ├─ README.md + ├─ data/ + │ ├─ my_data.csv/ + ``` + The absolute path of the README file on this file system is: + ``` + /corral/projects/NHERI/projects/PRJ-1234/notebooks/readme_files/README.md + ``` + The path of this file *relative* to the notebook file `notebook.ipynb` is: + ``` + ./readme_files/README.md + ``` + The `./` at the start of the relative path denotes that the path starts in the same directory as the Jupyter notebook. That is, `./` is equivalent here to the absolute path `/corral/projects/NHERI/projects/PRJ-1234/notebooks/`. + Sometimes, we need to construct a relative path for a file in a higher level of the directory tree. The absolute path of `my_data.csv` is the following: + ``` + /corral/projects/NHERI/projects/PRJ-1234/data/my_data.csv + ``` + To construct this path *relative* to `notebook.ipynb`, we can use: + ``` + ../data/my_data.csv + ``` + The `../` at the start of this path denotes that we are moving one level higher in the directory tree, to the folder that *contains* the `notebooks` directory. In other words, relative to `notebook.ipynb`, the path `../` corresponds to the absolute path `/corral/projects/NHERI/projects/PRJ-1234/`. 1. The published area is a read-only space. In the published section, users can run notebooks, but the notebook is not allowed to write any file to this location. If the notebook needs to write a file, you as the author of the notebook should make sure the notebook is robust to write the file in each user directory. [Here is an example of a published notebook](https://doi.org/10.17603/ds2-v310-qc53){ target="_blank" } that writes files to user directories. Furthermore, since the published space is read-only, if a user wants to revise, enhance or edit the published notebook they will have to copy the notebook to their mydata and continue working on the copied version of the notebook located in their mydata. To ensure that users understand these limitations, we require a readme file be published within the project that explains how future users can run and take advantage of the Jupyter Notebook.