Access & Basic Usage
Access and Usage
rakaia can be accessed through either downloading standalone builds, or by installing from source.
Standalone executables
The builds download page contains instructions for unpacking and executing rakaia for your specific OS:
Download a rakaia standalone build for your OS (Linux, macOS, Windows)
Install from source
Visit rakaia on GitHub to install rakaia from source (free for non-commercial/academic use):
Requirements
- Minimum: 8 GB RAM, 4 cores, 5-10 GB free disk space, Internet browser (recommended Google Chrome)
- Recommended: 16 GB RAM, 8+ cores, 15-20+ GB free disk space
- For viewing and processing H & E images (rakaia v0.23.0 or greater), an installation of vips for the appropriate OS
Additionally, for users installing from source:
- Python 3.10, 3.11, or 3.12, or conda with one of the Python versions listed (Recommended to use the full Anaconda installer)
Without conda (not recommended)
rakaia can be installed locally without an environment or container, but this is not recommended for dependency management:
cd rakaia
pip install .
With conda
conda is the recommended installation manager for rakaia. To install conda locally, visit this link and select the relevant operating system.
Once conda is installed:
conda create --name rakaia python=3.11
conda activate rakaia
cd rakaia
pip install .
vips for WSI rendering (optional)
To view WSIs such as H&E, an installation of libvips is required, and is not installed through the pip installation above. Users should visit the vips installation page for instructions on installing for a specific OS.
Note: macOS users should install vips using brew as opposed to conda.
Installation failure for ParmED
If installation of the ParmEd library fails (appears to be more prevalent on older versions of macOS), then users should try installing it from conda source:
pip uninstall parmed
conda install -c conda-forge parmed=4.3.0
leidenalg
If installation of the leidenalg library fails ( appears to happen on MacOS with Python 3.12+), then users should try installing it from conda source:
pip uninstall leidenalg
conda install -c conda-forge leidenalg=0.10.2
Updating local installations
From source, rakaia can be updated locally using the following commands. Note that this method requires access to the source code repository. Please contact mwatson@lunenfeld.ca to request repository acces privileges.
# navigate to the directory where you cloned rakaia from github
cd rakaia
git switch main
git pull --all
pip install .
Running rakaia
The ClI options and help screen for running rakaia can be viewed using:
rakaia -h
After installation, rakaia can be run through conda or simply executed using the rakaia command:
conda activate rakaia
rakaia
After a few moments, rakaia should auto open in a new browser window. Otherwise,
the user should then navigate to http://127.0.0.1:5000/ or http://0.0.0.0:5000/ to access rakaia.
The current version of rakaia can also be checked on the command line with the following:
rakaia -v
Custom Ports
Users are able to specify a different port for rakaia web session (the default port remains 5000). Suggested alternative ports are 8050 and 8080. The port can be specified in the CLI with:
rakaia -p 8050
The local URL will then take the form of http://127.0.0.1:{port} such as
http://127.0.0.1:8050/
Local file dialog
Users may also have the option to install and use a local file dialog rendered with
wxPython on local runs. This can be instantiated with the -l CLI option when running rakaia (by default, this feature
is not included):
rakaia -l
IMPORTANT: Due to the limitations of wxPython on multi-threaded systems as well as compatibility problems on different OS options, this feature is not likely to work properly on macOS.
In order to use this feature, users should make sure to install wxPython from the proper download page
Other options
By default, rakaia will run in threaded mode. To disable using a multi-threaded application instance, add -dt as
a command line option (not recommended):
rakaia -dt
rakaia also uses bootstrap-style load screens to indicate that data are being imported or changed (i.e. on an ROI change). To disable
the load screens for data manipulation, use the -dl CLI option:
rakaia -dl
rakaia supports custom default colour swatches that are input by the user. An example using 14 custom colours:
rakaia -sc "#25262b,#868e96,#fa5252,#e64980,#be4bdb,#7950f2,#4c6ef5,#228be6,#15aabf,#12b886,#40c057,#82c91e,#fab005,#fd7e14"
custom color swatches will replace the default color bars used for channel recoloring.
Docker
rakaia can be run using Docker with the following commands (requires an installation of Docker):
cd rakaia
docker build -t rakaia .
# use -d to run detached in the background
docker run -d -p 5000:5000 rakaia:latest rakaia -da
Local file destinations can be mounted for direct access to local filepaths in the containerized environment, such as :
docker run -p 5000:5000 -v /home/:/home/ rakaia:latest rakaia -da
Navigate to the local address http://0.0.0.0:5000/ or http://127.0.0.1:5000/
Note: This configuration is also suitable for deployment on a shared server for multiple concurrent users. Visit the performance and deployment article for more information.
For developers
rakaia can be run in editable mode with either configuration shown below, which permits source code changes to be applied to the application on the fly:
pip install -e .
rakaia
Installing an editable version through pip is also required to run unit tests:
pytest --headless --cov rakaia
Conversely, without app installation, using the app debug mode:
python rakaia/wsgi.py -dv