You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
PolyglotDB is the Python API for interacting with Polyglot databases and is installed through ``pip``. There are other
18
-
dependencies that must be installed prior to using a Polyglot database, depending on the user's platform.
19
+
PolyglotDB is the Python API for interacting with Polyglot databases and is installed through ``conda-forge`` or ``pip``.
19
20
20
21
.. note::
21
22
22
-
Another way to use Polyglot functionality is through setting up an `ISCAN server`_.
23
+
`ISCAN`_ is a separate project built on top of PolyglotDB that provides a web-based interface for corpus management and analysis.
23
24
An Integrated Speech Corpus Analysis (ISCAN) server can be set up on a lab's central server, or you can run it on your
24
25
local computer as well (though many
25
-
of PolyglotDB's algorithms benefit from having more processors and memory available). Please see the ISCAN
26
-
documentation for more information on setting it up (http://iscan.readthedocs.io/en/latest/getting_started.html).
26
+
of PolyglotDB's algorithms benefit from having more processors and memory available). Please see the `ISCAN
27
+
documentation`_ for more information on setting it up.
27
28
The main feature benefits of ISCAN are multiple Polyglot databases (separating out different corpora and allowing any
28
29
of them to be started or shutdown), graphical interfaces for inspecting data, and a user authentication system with different levels
29
30
of permission for remote access through a web application.
@@ -40,66 +41,81 @@ If you don't have conda installed on your device:
40
41
#. Install either Anaconda, Miniconda, or Miniforge (`Conda Installation`_)
41
42
#. Make sure your conda is up to date :code:`conda update conda`
42
43
43
-
.. warning::
44
+
.. _add_conda_to_path:
45
+
46
+
.. Note::
44
47
45
-
On Windows, you must use the Anaconda Prompt or Miniforge Prompt to effectively manage and execute conda commands.
46
-
This is crucial to avoid potential issues specific to the Windows environment and to ensure that all functionalities work as intended.
48
+
On Windows, it is recommended to use the Anaconda Prompt or Miniforge Prompt to manage and execute conda commands effectively.
49
+
This is because, by default, installing Anaconda or Miniforge does not add the conda command to your system's PATH environment variable.
50
+
However, if you prefer to use the regular Windows Command Prompt or run Python scripts directly from your IDE, you will need to manually add the necessary directories to your PATH.
51
+
To do so, follow these steps:
47
52
53
+
#. Open the Start Menu and search for ``Environment Variables``.
54
+
#. Click on ``Edit the system environment variables``.
55
+
#. In the System Properties window, click on the ``Environment Variables`` button.
56
+
#. In the Environment Variables window, find the ``Path`` variable in the ``User variables`` or ``System variables`` section and select it.
57
+
#. Click ``Edit``, then ``New``, and add the following two paths (adjust to your installation):
48
58
49
-
Quick Installation via conda-forge (Recommended):
59
+
#. ``C:\Users\YourUsername\Anaconda3``
60
+
#. ``C:\Users\YourUsername\Anaconda3\Scripts``
61
+
62
+
After completing these steps, you should be able to use conda in the Windows Command Prompt and configure your IDE accordingly.
63
+
64
+
**Quick Installation via conda-forge (Recommended)**:
50
65
51
66
#. You can install PolyglotDB using a single Conda command :code:`conda create -n polyglotdb -c conda-forge polyglotdb python=3.12`
#. Install PolyglotDB via :code:`pip install -e .`, which will install the ``pgdb`` utility that can be run inside your conda environment
61
76
and manages a local database.
62
77
78
+
**Using the Conda Environment in your IDE's integrated terminal**: (VSCode example)
79
+
80
+
If you are using an IDE, you may encounter issues where the IDE's default Python interpreter is different from the one set up in your Conda environment.
81
+
This can lead to errors such as missing packages, even if you've installed everything correctly in Conda.
82
+
In such cases, you need to manually set the Python interpreter in your IDE to point to the one used by your Conda environment.
83
+
If you are on Windows, make sure you have completed :ref:`this step<add_conda_to_path>` so that the Conda environment is accessible from your IDE's terminal.
84
+
For Visual Studio Code, follow these steps (a similar process applies to most other IDEs):
85
+
86
+
#. Make sure you have the Python extension installed in VSCode.
87
+
#. Open VSCode and open Command Palette (``Ctrl+Shift+p`` on Windows or ``cmd+shift+p`` on Mac), then choose ``Python: Select Interpreter``.
88
+
#. Select the interpreter corresponding to your Conda environment (e.g., ``conda-env:polyglotdb``).
89
+
#. Open a new terminal in VSCode. If the environment is not activated automatically, run :code:`conda activate polyglotdb`
90
+
91
+
Now, you can run PolyglotDB commands and scripts directly within VSCode's integrated terminal.
92
+
63
93
.. _local_setup:
64
94
65
95
Set up local database
66
96
---------------------
67
97
68
98
Installing the PolyglotDB package also installs a utility script (``pgdb``) that is then callable from the command line inside your conda environment.
69
99
The ``pgdb`` command allows for the administration of a single Polyglot database (install/start/stop/uninstall).
70
-
Using ``pgdb`` requires that several prerequisites be installed first, and the remainder of this section will detail how
71
-
to install these on various platforms.
72
-
Please be aware that using the ``pgdb`` utility to set up a database is not recommended for larger groups or those needing
73
-
remote access.
74
-
See the `ISCAN server`_ for a more fully featured solution.
75
-
76
-
Mac & Linux
77
-
```````````
78
-
#. Make sure you are inside the dedicated conda environment just created. If not, activate it via :code:`conda activate polyglotdb`
79
-
#. Inside your conda environment, run :code:`pgdb install /path/to/where/you/want/data/to/be/stored`, or
80
-
:code:`pgdb install` to save data in the default directory.
81
-
82
-
.. warning::
83
-
84
-
Do not use ``sudo`` with this command on Macs, as it will lead to permissions issues later on.
100
+
``pgdb install`` is a separate step that installs the actual local database backend, including Neo4j and InfluxDB. This is necessary to run PolyglotDB locally.
85
101
86
-
Once you have installed PolyglotDB, to start it run :code:`pgdb start`.
87
-
Likewise, you can close PolyglotDB by running :code:`pgdb stop`.
102
+
Installing the local database
103
+
`````````````````````````````
88
104
89
-
To uninstall, run :code:`pgdb uninstall`
90
-
91
-
Windows
92
-
```````
93
-
94
-
#. Make sure you are running as an Administrator (right-click on Anaconda Prompt/Miniforge Prompt and select "Run as administrator"), as Neo4j will be installed as a Windows service.
95
-
#. If you had to reopen a command prompt in Step 1, reactivate your conda environment via: :code:`conda activate polyglotdb`.
105
+
#. Make sure you are inside the dedicated conda environment just created. If not, activate it via :code:`conda activate polyglotdb`
96
106
#. Inside your conda environment, run :code:`pgdb install /path/to/where/you/want/data/to/be/stored`, or
97
107
:code:`pgdb install` to save data in the default directory.
98
108
99
-
To start/stop the database, you likewise have to use an administrator command prompt before entering the commands :code:`pgdb start`
100
-
or :code:`pgdb stop`.
109
+
.. Warning::
110
+
#. On Windows, make sure you are running as an Administrator (right-click on Anaconda Prompt/Miniforge Prompt/Command Prompt/Your IDE and select "Run as administrator"), as Neo4j will be installed as a Windows service.
111
+
#. Do not use ``sudo`` with ``pgdb install`` on Macs, as it will lead to permissions issues later on.
112
+
113
+
Managing the local database
114
+
```````````````````````````
101
115
102
-
To uninstall, run :code:`pgdb uninstall` (also requires an administrator command prompt).
116
+
To start the database :code:`pgdb start`
117
+
To stop the database :code:`pgdb stop`
118
+
To uninstall the database :code:`pgdb uninstall`
103
119
104
120
105
121
To view your conda environments:
@@ -122,7 +138,7 @@ Steps to use PolyglotDB
122
138
Now that you have set up the PolyglotDB environment and installed local databases,
123
139
follow these steps each time you use PolyglotDB:
124
140
125
-
#. Navigate to your working directory, either in your IDE or via the command line. (On Windows, use Anaconda Prompt/Miniforge Prompt.)
141
+
#. Navigate to your working directory, either in your IDE or via the command line.
126
142
#. Activate the conda environment: :code:`conda activate polyglotdb`.
127
143
#. Start the local databases: :code:`pgdb start`.
128
144
#. Write your Python scripts inside this working directory.
@@ -132,22 +148,21 @@ follow these steps each time you use PolyglotDB:
132
148
133
149
.. _docker_install:
134
150
135
-
Docker Environment
136
-
===================
151
+
Alternative Installation (Using Docker Environment)
Running PolyglotDB in a `Docker`_ container is a great way to maintain a consistent environment, isolate dependencies, and streamline your setup process. This section will guide you through setting up and using PolyglotDB within Docker.
154
+
Running PolyglotDB in a `Docker`_ container is a great way to maintain a consistent environment, isolate dependencies, and streamline your setup process.
155
+
This section will guide you through setting up and using PolyglotDB within Docker. Note that this method is an alternative to the default installation with conda environment.
139
156
140
157
Prerequisites
141
158
-------------
142
159
143
-
Before starting, ensure that Docker is installed on your system. You can check if Docker is installed and verify its version by running the following command in your terminal:
160
+
Before starting, ensure that Docker is installed on your system. You can check if Docker is installed by running the following command in your terminal:
144
161
145
162
.. code:: bash
146
163
147
164
docker version
148
165
149
-
Make sure your Docker Engine version is **19.03.0** or higher.
150
-
151
166
Setting Up the Docker Container
152
167
-------------------------------
153
168
@@ -166,6 +181,7 @@ Follow these steps to get your Docker container up and running:
166
181
**Note for Mac Users:**
167
182
If you're using a Mac, you might need to run :code:`docker compose run polyglotdb`
168
183
184
+
The docker compose run automatically starts the databases server therefore there's no extra steps to set up the databases.
169
185
This command launches an interactive shell inside the `polyglotdb` container, allowing you to execute PolyglotDB scripts directly.
170
186
171
187
3. **Working with the Default Folder Structure:**
@@ -211,6 +227,28 @@ Follow these steps to get your Docker container up and running:
211
227
However, if you want to preserve your scripts after shutting down the container,
212
228
ensure you save them in the directory mounted to your device (default: ``/polyglotdb``).
213
229
230
+
- **Note when writing your scripts**:
231
+
232
+
#. It is important to **avoid** using absolute paths in your scripts when working with Docker.
233
+
This is because the Docker container has its own internal filesystem, so absolute paths from your host machine
234
+
(e.g., ``/home/user/documents/my_corpus``) will not be valid inside the container.
235
+
Instead, always use relative paths based on the current working directory inside the container.
236
+
Additionally, you must place all files you want to reference (such as corpus folders, Praat scripts, etc.)
237
+
inside the directory that is mounted to the Docker container, which is the ``polyglotdb-docker`` directory by default.
238
+
239
+
.. code:: python
240
+
241
+
import os
242
+
corpus_root ='./data/my_corpus'
243
+
# Now you can use corpus_root to access files in the my_corpus folder
244
+
245
+
#. The Docker setup comes with several pre-installed tools inside the `polyglotdb` container located at `/pgdb/tools`:
246
+
247
+
1. `Praat`_: Installed at `/pgdb/tools/praat`, environment variable `praat`. In your script, you can reference it by :code:`os.environ.get('praat')`.
248
+
2. `Reaper`_: Installed at `/pgdb/tools/reaper`, environment variable `reaper`. In your script, you can reference it by :code:`os.environ.get('reaper')`.
249
+
250
+
251
+
214
252
5. **Stopping the Docker Containers:**
215
253
216
254
To stop the Docker containers, first exit the `polyglotdb` shell by running:
@@ -226,6 +264,7 @@ Follow these steps to get your Docker container up and running:
226
264
docker compose down
227
265
228
266
.. _Changing the Default Storage Location:
267
+
229
268
Changing the Default Storage Location
230
269
-------------------------------------
231
270
@@ -265,11 +304,3 @@ You can also change the working directory by modifying the `docker-compose.yml`
265
304
- /path/to/your/working/directory:/polyglotdb
266
305
267
306
By doing this, the specified directory on your device will be mounted to the Docker container under `/polyglotdb`. To access PolyglotDB scripts and data within the container, ensure they are placed inside your chosen directory.
268
-
269
-
Pre-installed Tools
270
-
-------------------
271
-
272
-
The Docker setup comes with several pre-installed tools inside the `polyglotdb` container located at `/pgdb/tools`:
273
-
274
-
1. `Praat`_: Installed at `/pgdb/tools/praat`, environment variable `praat`. In your script, you can reference it by :code:`os.environ.get('praat')`.
275
-
2. `Reaper`_: Installed at `/pgdb/tools/reaper`, environment variable `reaper`. In your script, you can reference it by :code:`os.environ.get('reaper')`.
0 commit comments