Assumptions & Notation
- Examples assume the unzipped folder is pathXcite in your Documents folder.
- If you downloaded a ZIP from GitHub, the folder may be pathXcite-main. Replace the folder name in commands accordingly.
- %HOMEPATH% (Windows) and $HOME (macOS/Linux) refer to your user home folder.
- Commands shown with a leading $ are terminal commands. Type everything after $ (do not include the symbol).
Get the Software
Option A: Download ZIP
- Visit the GitHub repository: sysbio-bioinf/pathXcite.
- Click Code → Download ZIP.
- Unzip the archive (you will get a folder named pathXcite or pathXcite-main).
- Move the folder to Documents (recommended).
Option B: Clone with Git
git clone https://github.com/sysbio-bioinf/pathXcite.git
Expected files: app/, main.py, setup.sh, setup_win.ps1, requirements.txt.
Choose Your Operating System
Step 1: Open PowerShell
- Press ⊞ Win, type PowerShell (or Windows Terminal), then press Enter.
- Alternatively: ⊞ Win + X → choose Windows Terminal.
Step 2: Go to the folder
Assuming the folder is %HOMEPATH%\Documents\pathXcite. If your folder is pathXcite-main, replace the name.
cd "%HOMEPATH%\Documents\pathXcite"
Tip: In File Explorer, right-click the folder background and choose Open in Terminal.
Step 3: First-time setup
Option 1: Double-click setup_win.ps1 in File Explorer (if SmartScreen appears, click More info → Run anyway).
Option 2: Run from PowerShell (with logging)
powershell -ExecutionPolicy Bypass -File ".\setup_win.ps1"
If scripts are blocked for this session:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
What this does: creates a local environment, uses the bundled Python, installs required packages, and launches pathXcite.
Step 4: Subsequent launches
- Open the same folder and double-click setup_win.ps1, or run:
powershell -ExecutionPolicy Bypass -File ".\setup_win.ps1"
Security prompts you might see
- SmartScreen: Click More info → Run anyway.
- “Running scripts is disabled”: Use the one-time bypass above (Process scope only).
Step 1: Open Terminal
- Press ⌘ + Space, type Terminal, then press Return.
- Or open Applications → Utilities → Terminal.
Step 2: Go to the folder
Assuming the folder is $HOME/Documents/pathXcite. If it is pathXcite-main, replace the name.
cd "$HOME/Documents/pathXcite"
Tip: In Finder, drag the folder into the Terminal window to auto-fill the path.
Step 3: Make the installer executable (first time)
chmod +x ./setup.sh
Step 4: Run the installer
./setup.sh
This creates a local environment, uses the bundled Python, installs dependencies, and launches pathXcite.
Step 5: Subsequent launches
./setup.sh
Security prompts you might see
- Gatekeeper: If you see “can't be opened”, open System Settings → Privacy & Security, click Open Anyway, then run again.
- Permission denied: Ensure you ran chmod +x setup.sh.
Step 1: Open Terminal
- Press Ctrl + Alt + T, or search for Terminal in Activities.
Step 2: Go to the folder
Assuming the folder is $HOME/Documents/pathXcite. If it is pathXcite-main, replace the name.
cd "$HOME/Documents/pathXcite"
Step 3: Make the installer executable (first time)
chmod +x ./setup.sh
Step 4: Run the installer
./setup.sh
This creates a local environment, uses the bundled Python, installs dependencies, and launches pathXcite.
Step 5: Subsequent launches
./setup.sh
Common hints
- Permission denied: Ensure you ran chmod +x setup.sh.
- Missing unzip: sudo apt update && sudo apt install unzip (only if you need to unzip via terminal).
Verify the Installation
- After setup completes, pathXcite launches automatically. If it does not, re-run the OS-specific steps above from the correct folder.
- Keep the terminal open during the first run; some packages may finish installing in the background.
If you moved the folder after installing, re-run the installer once in the new location.
Recommended Configuration
Entrez API key (faster metadata)
- Create an API key in your NCBI Account settings.
- In pathXcite, open Settings → Entrez.
- Paste the key and save. Retrieval should be ~3-4× faster.
Gene set libraries
- In Settings → Libraries, download or update Enrichr libraries.
- To use custom terms, add your own .gmt files.
Troubleshooting
- “Permission denied” (macOS/Linux): run chmod +x setup.sh, then try again.
- “Script is disabled” (Windows): run the one-time bypass: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass.
- SmartScreen/Gatekeeper: choose More info → Run anyway (Windows) or Open Anyway in Privacy & Security (macOS).
- Slow first run: set your Entrez API key in Settings and ensure you have an internet connection for package downloads.
- Folder name mismatch: if you used the ZIP, your folder may be pathXcite-main. Adjust the cd command.
Need a walkthrough? See tutorials.