Merge pull request #577 from oist/develop-main

Release 2023/09/29 version 1.0.1

docs/conf.py

@@ -43,7 +43,6 @@
     "sphinxcontrib.apidoc",
     "sphinx_autodoc_typehints",
     "myst_parser",
-    "sphinx.ext.autosectionlabel",
     "sphinx.ext.autosummary",
     "sphinx.ext.extlinks",
     "sphinx.ext.autodoc.typehints",

docs/gui/visualize.md

@@ -5,7 +5,7 @@ Visualize
 <img width="400px" src="../_static/visualize/whole.png" alt="Whole" />
 </p>
 
-OptiNiSt visualizes the analysis results by plotly. 
+OptiNiSt visualizes the analysis results by plotly.
 
 
 
@@ -15,8 +15,8 @@ OptiNiSt visualizes the analysis results by plotly.
 <img width="400px" src="../_static/visualize/components/set_display_box.png" alt="SetDisplayBox" />
 </p>
 
-Click the "+" button to create a display box.   
-To add another display box below, click the "+" button shown below. 
+Click the "+" button to create a display box.
+To add another display box below, click the "+" button shown below.
 
 <p align="center">
 <img width="400px" src="../_static/visualize/components/add_column.png" alt="AddColumn" />
@@ -46,7 +46,7 @@ You can select the range of the frame by assigning 1st and last frame numbers. L
 </p>
 
 Click on the PLAY button within the plotting box to play the loaded movie.
-The number indicated on the right of PAUSE button is the frame interval in milliseconds. 
+The number indicated on the right of PAUSE button is the frame interval in milliseconds.
 
 
 ### Customizing visualization parameters
@@ -57,9 +57,9 @@ The number indicated on the right of PAUSE button is the frame interval in milli
 
 Select one of the display boxes by clicking inside of the box. The blue highlight of the box indicates the current selection of the display box. The parameters shown on the left are attached to the currently selected box. Details of the parameter are explained here.
 
-## ROI and timecourse 
-There is a way to link ROI plots and fluorescence time series. 
-Create One box showing ROI and another box showing fluorescence. You can link two boxes by setting `ref image` in the fluorescence box to be the ID of the ROI box. (ID of the box is on the left upper side). By clicking on the ROI of a cell, you can visualize the corresponding fluorescence time course in the fluorescence box. By turning on the `drag select` in ROI box, you can select multiple cells in the image at once. 
+## ROI and timecourse
+There is a way to link ROI plots and fluorescence time series.
+Create One box showing ROI and another box showing fluorescence. You can link two boxes by setting `ref image` in the fluorescence box to be the ID of the ROI box. (ID of the box is on the left upper side). By clicking on the ROI of a cell, you can visualize the corresponding fluorescence time course in the fluorescence box. By turning on the `drag select` in ROI box, you can select multiple cells in the image at once.
 
 
 ## Ref Image
@@ -86,7 +86,7 @@ In one plotting box (ex, the one with ID:0), select a background image such as m
 <img width="200px" src="../_static/tutorials/fig24_selectitem.png" alt="Whole" />
 </p>
 
-In the same plotting box, select cell_roi from the Select Roi pull-downs. Both Suite2P and CaImAn include the process to drop the extracted ROIs that do not meet the criteria. In OptiNiSt, the cell ID is given to all the ROIs. Cell_roi is the ROIs that passed the criteria. 
+In the same plotting box, select cell_roi from the Select Roi pull-downs. Both Suite2P and CaImAn include the process to drop the extracted ROIs that do not meet the criteria. In OptiNiSt, the cell ID is given to all the ROIs. Cell_roi is the ROIs that passed the criteria.
 
 <br>
 <p align="center">
@@ -100,19 +100,26 @@ The plotting box (ID:0) shows the background image and detected cells.
 </p>
 
 In another plotting box (ex, the one with ID:1), select fluorescence from the Select Item pulldown.
-And select 0(same ID with the plotting box of your ROI image) from the ref image pull down. By doing this,  the two plotting boxes are linked. 
+And select 0(same ID with the plotting box of your ROI image) from the ref image pull down. By doing this,  the two plotting boxes are linked.
 
 <br>
 <p align="center">
 <img width="400px" src="../_static/tutorials/fig27_fluo.png" alt="Whole" />
 </p>
 
-Now you can explore the ROI and time course. The color of ROI and corresponding time course is matched. You will know the cell ID by letting your mouse over the cell in the image. Clicking on the cell automatically adds the fluorescence time course of the clicked cell. 
+Now you can explore the ROI and time course. The color of ROI and corresponding time course is matched. You will know the cell ID by letting your mouse over the cell in the image. Clicking on the cell automatically adds the fluorescence time course of the clicked cell.
 <br>
 <p align="center">
 <img width="600px" src="../_static/tutorials/fig28_roifluo.png" alt="Whole" />
 </p>
 
+```{eval-rst}
+.. note::
+  - Cell's ID starts from 0 from version 1.0.0
+
+      - In the previous versions, starts from 1.
+```
+
 If it is tiring to select the cell by clicking one by one, turn on the drag select button on the right in the plotting box of ROI. It enables selecting all the cells within the rectangular area you define.
 
 <br>
@@ -121,20 +128,50 @@ If it is tiring to select the cell by clicking one by one, turn on the drag sele
 </p>
 
 
+### Switch time course plot units
+
+By default, timecourse plot's x axis is frame number. You can switch to time unit by clicking "range unit" in left side bar.
+
+<br>
+<p align="center">
+<img width="600px" src="../_static/visualize/select_timecourse_unit.png" alt="SelectTimeCourseUnit" />
+</p>
+
+If you change unit to "time", plot's x axis is changed to time(sec).
+
+<br>
+<p align="center">
+<img width="600px" src="../_static/visualize/timecourse_time_unit.png" alt="TimeCourseTimeUnit" />
+</p>
+
+The time is calculated from imaging_plane.imaging_rate, in NWB settings.
+
+<br>
+<p align="center">
+<img width="600px" src="../_static/visualize/imaging_rate.png" alt="TimeCourseTimeUnit" />
+</p>
+
+```{eval-rst}
+.. important::
+   The NWB settings parameter ``imaging_rate`` is also used as parameter for frame rate like ``fs`` in suite2p.
+   So, be sure if your imaging_rate is set correctly before running workflow.
+```
+
+
 ## Editing ROI
 
 <p align="center">
 <img width="400px" src="../_static/tutorials/edit-roi/box.png" alt="Whole" />
 </p>
 
-To the edit roi, prepare a plotting box. 
+To the edit roi, prepare a plotting box.
 
 <p align="center">
 <img width="200px" src="../_static/tutorials/fig24_selectitem.png" alt="Whole" />
 </p>
 
 In one plotting box (ex, the one with ID:0), select a background image such as meanImg from the Select Item pulldowns.
-In the same plotting box, select cell_roi from the Select Roi pull-downs. 
+In the same plotting box, select cell_roi from the Select Roi pull-downs.
 
 <br>
 <p align="center">
@@ -183,32 +220,10 @@ NWB file is overwirtten with the ROI edit information.
           - iscell data of deleted ROI changes to False.
 ```
 
-```{eval-rst}
-.. note::
-  ROI's id and index of viewer have different values!
-
-  - id
-
-      - The id of ROI, **starting from 1**.
-      - Shown in
-
-          - VISUALIZE tab.
-          - NWBfile's processing/optinist section.
-
-  - index
-
-      - Numbering of columns and rows in tables, **starting from 0**.
-      - Shown in
-
-          - table when you open NWBfile's timecourse data with viewers like `HDFView <https://www.hdfgroup.org/downloads/hdfview/>`_
-```
-
-
 ## saving plots
 
 <p align="center">
 <img width="200px" src="../_static/tutorials/fig30_saving.png" alt="Whole" />
 </p>
 
 You can save created plots in svg, png, jpeg, or webp format. Please select the format, decide the saving name in the lower area on the left panel, and click the camera mark in the plotting box. Svg format saves the plot as a vector-based graphical format which may be convenient when you need high-resolution figures.
-

docs/gui/workflow.md

@@ -18,8 +18,8 @@ Workflow
 
 <br>
 <p align="center">
-<img width="200px" src="../_static/tutorials/fig3_imagenode.png" alt="imageNode" />
-<img width="200px" src="../_static/workflow/components/imageList.png" alt="imageNode" />
+<img width="250px" src="../_static/tutorials/fig3_imagenode.png" alt="imageNode" />
+<img width="250px" src="../_static/workflow/components/imageList.png" alt="imageNode" />
 </p>
 <br/>
 
@@ -34,15 +34,39 @@ Once the data is accessible, you can view it by following these steps:
 **Note:** Currently, image files with {.tif, .TIF, .tiff, .TIFF} extensions are accepted. Other extensions will be added on request.
 
 #### Directory Setting
-OptiNiSt uses `OPTINIST_DIR` for retrieving data and saving results. OptiNiSt searches for input data in the 'input' directory within `OPTINIST_DIR`. The default `OPTINIST_DIR` is `/tmp/optinist` on your computer.
+OptiNiSt uses `OPTINIST_DIR` for retrieving data and saving results. OptiNiSt searches for input data in the 'input' directory within `OPTINIST_DIR`. The default `OPTINIST_DIR` is `/tmp/studio` on your computer.
 
 Choosing a folder makes all the TIFF files in the shown sequence an input set of continuous frames.
 
 You may not want to modify your original data folder, or you may want to make your data folder visible and accessible to OptiNiSt because imaging data can be large and take time to copy. You can take either strategy in assigning your data path:
 
-1. **Copy your original data file to `OPTINIST_DIR` ** To copy the data to `OPTINIST_DIR`, click on the LOAD button on the node. The LOAD button copies the selected file to your `OPTINIST_DIR/input`. This can be done from the GUI.
+1. **Upload from GUI**
 
-2. **Change the setting of `OPTINIST_DIR` ** `OPTINIST_DIR` is defined in `optinist/optinist/api/dir_path.py`. Change line for `OPTINIST_DIR`, INPUT_DIR, and OUTPUT_DIR according to your demand. Changing `dir_path.py` may also be necessary when running the pipeline on your cluster computers. Also, you can quickly change OPTINIST_DIR by changing the environment variable before launching. The change is effective after relaunching.
+    Click on the LOAD button on the node. The LOAD button copies the selected file to your `OPTINIST_DIR/input`.
+
+    **By this method, you cannot upload multiple files or folder at once**.
+    - If you want to upload multiple files or folder at once, use the method below.
+
+2. **Copy files to `OPTINIST_DIR`**
+
+    Copy your raw data to `OPTINIST_DIR/input/1/` by your OS's file manager or command lines.
+      ```{eval-rst}
+      .. warning::
+          Be sure to copy under ``input/1/``. ``1`` is the default workspace id for :ref:`standalone mode <about-multiuser-mode>`.
+          If you copy under ``input/`` directly, the file cannot be found from GUI.
+      ```
+
+    You can copy folder into the input directory.
+    - If you put folder, you can see the folder from GUI, SELECT IMAGE dialog like this.
+      <br>
+      <p align="center">
+      <img width="400px" src="../_static/workflow/components/put_folder_to_input_dir.png" alt="Put Folder to Input Dir" />
+      </p>
+
+3. **Change the setting of `OPTINIST_DIR`**
+
+    This requires modifying source codes. See [](each-platforms-for-developer) installation guide section.
+    `OPTINIST_DIR` is defined in `optinist/studio/app/dir_path.py`. Change line for `OPTINIST_DIR`, `INPUT_DIR`, and `OUTPUT_DIR` according to your demand. Changing `dir_path.py` may also be necessary when running the pipeline on your cluster computers. Also, you can quickly change `OPTINIST_DIR` by changing the environment variable before launching. The change is effective after relaunching.
 
 #### Other Data Formats As The Input
 

docs/host_for_multiuser/about.md

@@ -1,3 +1,4 @@
+(about-multiuser-mode)=
 About
 =====
 

docs/host_for_multiuser/setup.md

@@ -73,15 +73,15 @@ Follow the steps below to setup `multiuser` mode.
     ```
 3. Create database for your project.
     ```sql
-    CREATE DATABASE {YOUR_DATABASE_NAME};
+    CREATE DATABASE YOUR_DATABASE_NAME;
     ```
 4. Create user for your project.
     ```sql
-    CREATE USER '{DB_USER_NAME}'@'localhost' IDENTIFIED BY '{DB_USER_PASSWORD}';
+    CREATE USER 'DB_USER_NAME'@'localhost' IDENTIFIED BY 'DB_USER_PASSWORD';
     ```
 5. Grant all privileges to the user for the database.
     ```sql
-    GRANT ALL PRIVILEGES ON {YOUR_DATABASE_NAME}.* TO '{DB_USER_NAME}'@'localhost';
+    GRANT ALL PRIVILEGES ON YOUR_DATABASE_NAME.* TO 'DB_USER_NAME'@'localhost';
     ```
 
 ### Set OptiNiSt config
@@ -130,13 +130,13 @@ Follow the steps below to setup `multiuser` mode.
 3. Insert initial data
 
     ```bash
-    mysql -u {DB_USER_NAME} -p
+    mysql -u DB_USER_NAME -p
     ```
     ```sql
-    USE {YOUR_DATABASE_NAME};
-    INSERT INTO organization (name) VALUES ('{YOUR_ORGANIZATION_NAME}');
+    USE YOUR_DATABASE_NAME;
+    INSERT INTO organization (name) VALUES ('YOUR_ORGANIZATION_NAME');
     INSERT INTO roles (id, role) VALUES (1, 'admin'), (20, 'operator');
-    INSERT INTO users (uid, organization_id, name, email, active, ) VALUES ('{USER_UID}', 1, '{YOUR_EMAIL}', '{YOUR_PASSWORD}', 1);
+    INSERT INTO users (uid, organization_id, name, email, active, ) VALUES ('USER_UID', 1, 'YOUR_EMAIL', 'YOUR_PASSWORD', 1);
     INSERT INTO user_roles (user_id, role_id) VALUES (1, 1);
     ```
     - USER_UID is the user uid you created in the previous step ([Create admin user for the project](#create-admin-user-for-the-project)).

docs/installation/docker.md

@@ -26,20 +26,20 @@ Pull the latest docker image from docker hub.
 docker pull oistncu/optinist
 ```
 Start docker container.
-```
-docker run -it --shm-size=2G --name optinist_container -d -p 8000:8000 --restart=unless-stopped oistncu/optinist:latest python main.py --host 0.0.0.0 --port 8000
-```
-
-Execute in terminal
-```
-docker exec -it optinist_container /bin/bash
-```
-
-### Set saving directory
-
-Optinist default saving directory is `/tmp/optinist`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
 ```bash
-export OPTINIST_DIR="your_saving_dir"
+docker run -it --shm-size=2G \
+-v /your/saving/dir:/app/studio_data \  # Please set your saving directory
+--env OPTINIST_DIR="/app/studio_data" \
+--name optinist_container -d -p 8000:8000 --restart=unless-stopped \
+oistncu/optinist:latest \
+python main.py --host 0.0.0.0 --port 8000
+```
+
+```{eval-rst}
+.. note::
+    Please set ``/your/saving/dir`` to your local directory.
+    Without this, OptiNiSt's data will lost when you stop docker container or reboot your PC.
+    By the command above (``-v`` option), you can mount your local directory to docker container.
 ```
 
 ## 2. Access to backend

docs/installation/docker_for_developer.md

@@ -50,3 +50,5 @@ Under maintenance...
 ```
 
 Done!
+
+If you will make PRs, please see the [](Contributing) section.

docs/installation/each_platforms_for_developer.md

@@ -1,3 +1,4 @@
+(each-platforms-for-developer)=
 Each Platforms for Developer
 =================
 
@@ -62,9 +63,11 @@ conda config --set channel_priority strict
 pip install -e '.[dev]'
 ```
 
+If you will make PRs, please see the [](Contributing) section.
+
 ### Set saving directory
 
-Optinist default saving directory is `/tmp/optinist`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
+Optinist default saving directory is `/tmp/studio`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
 ```
 export OPTINIST_DIR="your_saving_dir"
 ```
@@ -91,12 +94,15 @@ INFO:     Waiting for application startup.
 INFO:     Application startup complete.
 ```
 
+- If you won't develop the frontend code, launch browser and go to http://localhost:8000
+
 ## 3. Run frontend
 
 Open new terminal window, and go to `frontend` directory.
 
 ```
-cd optinist/frontend
+# from optinist root directory
+cd frontend
 ```
 
 Then install packages and run.

docs/installation/each_platforms_for_developer_use_mamba.md

@@ -98,7 +98,7 @@ pip install -e '.[dev]'
 
 ### Set saving directory
 
-Optinist default saving directory is `/tmp/optinist`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
+Optinist default saving directory is `/tmp/studio`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
 ```
 export OPTINIST_DIR="your_saving_dir"
 ```

docs/installation/linux.md

@@ -60,7 +60,7 @@ pip install optinist
 
 ### Set saving directory
 
-Optinist default saving directory is `/tmp/optinist`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
+Optinist default saving directory is `/tmp/studio`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
 ```
 export OPTINIST_DIR="your_saving_dir"
 ```

docs/installation/mac.md

@@ -49,7 +49,7 @@ pip install optinist
 
 ### Set saving directory
 
-Optinist default saving directory is `/tmp/optinist`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
+Optinist default saving directory is `/tmp/studio`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
 ```
 export OPTINIST_DIR="your_saving_dir"
 ```

docs/installation/windows.md

@@ -163,7 +163,7 @@ pip install optinist
 
 #### Set saving directory
 
-Optinist default saving directory is `/tmp/optinist`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
+Optinist default saving directory is `/tmp/studio`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
 ```
 export OPTINIST_DIR="your_saving_dir"
 ```