OTAC User Guide

← Back to OTAC overview

1. What Is OTAC?

OTAC automatically classifies offense descriptions into standardized categories. You provide a list of offense text strings in a CSV file, and OTAC returns a category for each one.

OTAC runs entirely on your computer. No data are ever sent to the internet. All processing is local and private.

---

2. What You Need Before You Start

Requirement	Details
Computer	Windows 10 or later, or Mac (any model from 2016 or later)
Disk space	At least 6 GB free
RAM	At least 8 GB (16 GB recommended)
Internet	Required once during setup to download Docker and build OTAC
Time	About 20–30 minutes the first time. After that, OTAC starts in under 30 seconds.

---

3. Step 1 — Install Docker Desktop

Docker is the technology that runs OTAC. You only need to install it once.

Which version do I download? (Windows)

You need to know whether your computer uses an AMD64 (x64) or ARM64 processor. The vast majority of Windows computers — including nearly all office and home desktops and laptops — are AMD64.

How to check:

1. Press the Windows key + R on your keyboard
2. Type msinfo32 and press Enter
3. A window called "System Information" opens
4. Find the line labeled System Type

If System Type says…	Download this version
x64-based PC	Docker Desktop for Windows — AMD64
ARM-based PC	Docker Desktop for Windows — ARM64

Tip: If you are unsure, choose AMD64 — it is correct for the vast majority of Windows computers.

Which version do I download? (Mac)

1. Click the Apple menu in the top-left corner of your screen
2. Choose About This Mac
3. Look at the Chip or Processor line in the window that opens

If it says…	Download this version
M1, M2, M3, or M4	Docker Desktop for Mac — Apple Silicon
Intel	Docker Desktop for Mac — Intel Chip

Tip: If your Mac was made in 2021 or later, it almost certainly has Apple Silicon (M1 or newer).

Download Docker Desktop

Your computer	Download link
Windows — Intel or AMD Most office computers	Download for Windows (AMD64)
Windows — ARM Newer Surface Pro X, Copilot+ PCs	Download for Windows (ARM64)
Mac — Apple Silicon M1, M2, M3, or M4, made in 2021 or later	Download for Mac (Apple Silicon)
Mac — Intel Made before 2021	Download for Mac (Intel)

Install Docker Desktop

Windows:

1. Run the installer (Docker Desktop Installer.exe)
2. Follow the on-screen prompts — accept all defaults
3. Restart your computer if prompted
4. After restarting, Docker Desktop will launch automatically
5. Look for the Docker whale icon in the system tray (bottom-right of your taskbar)
6. Wait until the icon stops animating — Docker is now ready

Sign-in prompt: Docker may ask you to sign in or create an account. You do not need to sign in — click Skip or Continue without signing in. Docker Desktop is free to use without an account.

Windows Subsystem for Linux (WSL) warning: If you see a message during installation saying "Windows Subsystem for Linux installation is too old" or similar, open a new Command Prompt and run the command Docker suggests — typically wsl --update. Press Enter, wait for it to finish, then restart Docker Desktop.

Mac:

1. Open the downloaded .dmg file
2. Drag the Docker icon into your Applications folder
3. Open Docker from your Applications folder
4. Follow the on-screen prompts (you may be asked for your Mac password)
5. Look for the Docker whale icon in your menu bar (top-right of the screen)
6. Wait until the icon stops animating — Docker is now ready

Sign-in prompt: Docker may ask you to sign in or create an account. You do not need to sign in — click Skip or Continue without signing in. Docker Desktop is free to use without an account.

---

4. Step 2 — Download the OTAC Files

You should have received a ZIP file called OTAC_Desktop.zip. Extract it to get a folder containing:

OTAC_Desktop/
  docker-compose.yml           Configuration file (do not edit)
  Dockerfile.microsoft         Configuration file (do not edit)
  requirements-docker.txt      Configuration file (do not edit)
  otac-0.1.0-py3-none-any.whl  OTAC software package (approximately 80 MB)
  otac_sample.csv              Sample data for testing (100 offenses)
  OTAC_USER_GUIDE.html         This guide (open in any browser)

Place this folder somewhere easy to find, such as your Desktop or Documents folder.

Choose a simple folder path. Avoid spaces or special characters in the path.

Good: C:\Users\Jane\Documents\OTAC_Desktop

Avoid: C:\Users\Jane\My Files\OTAC (v2)!

---

5. Step 3 — Start OTAC

Windows

To start or run OTAC, Docker Desktop must be running. Confirm the Docker whale icon is visible in your taskbar (bottom-right) and has stopped animating before continuing.

1. Make sure Docker Desktop is running — look for the whale icon in your taskbar (bottom-right). Wait for it to stop animating before continuing.
2. Open Command Prompt or Terminal (press Windows key, type cmd or Terminal, press Enter).
3. Navigate to the OTAC_Desktop folder by typing the command below and pressing Enter. Replace the path with the location where you saved the OTAC_Desktop folder.

cd "C:\Users\YourName\Documents\OTAC_Desktop"

Not sure where you saved it? Search for OTAC_Desktop in File Explorer, right-click the folder, choose Properties, and look at the Location field.

4. Verify Docker is ready by running docker info and pressing Enter. Docker will print several lines — scroll up in the command window to see if the block of text starts with the word Client:. If it does, Docker is ready. If you see an error, open Docker Desktop, wait for the whale icon to stop animating, and try again.
5. Run the following command, then keep the terminal window open while OTAC is running:

docker compose up --build

First time only: The first build takes 20–30 minutes and requires an internet connection. You will see messages scrolling — this is normal. Do not close the terminal window until the build finishes.

Windows firewall prompt: During the first build, Windows may show a pop-up asking if you want to allow "Docker Desktop Backend" to communicate on public and private networks. Click Allow to continue.

When OTAC is ready, open http://localhost:8501 in your browser.

Mac

To start or run OTAC, Docker Desktop must be running. Confirm the Docker whale icon is visible in your menu bar (top-right) and has stopped animating before continuing.

1. Make sure Docker Desktop is running — look for the whale icon in your menu bar (top-right). Wait for it to stop animating before continuing.
2. Open Terminal (press Command+Space, type Terminal, press Enter).
3. Navigate to the OTAC_Desktop folder by typing the command below and pressing Enter. Replace the path with the location where you saved the OTAC_Desktop folder.

cd ~/Documents/OTAC_Desktop

Not sure where you saved it? Search for OTAC_Desktop in Finder, right-click the folder, and choose Get Info to see the full path.

4. Verify Docker is ready by running docker info and pressing Return. Docker will print several lines — scroll up in the Terminal window to see if the block of text starts with the word Client:. If it does, Docker is ready. If you see an error, open Docker Desktop, wait for the whale icon to stop animating, and try again.
5. Run the following command, then keep the Terminal window open while OTAC is running:

docker compose up --build

First time only: The first build takes 20–30 minutes and requires an internet connection. You will see messages scrolling — this is normal. Do not close the Terminal window until the build finishes.

When OTAC is ready, open http://localhost:8501 in your browser.

---

6. Using OTAC

OTAC opens to the Single Coder tab by default. There are two tabs at the top of the page:

Tab	What it does
Single Coder (default)	Type one offense description and OTAC predicts its category instantly — no file upload needed
Bulk Coder	Upload a CSV or XLSX file to classify many offenses at once — a table at a time

Single Coder

Type an offense description into the text box. OTAC will display predicted categories immediately. Use this to test individual offenses or check a single case without preparing a file.

Bulk Coder — Uploading a File

To classify a list of offenses, click the Bulk Coder tab first — the file upload option only appears there.

Steps

1. Click the Bulk Coder tab at the top of the OTAC page
2. OTAC accepts a plain-text CSV file or an Excel XLSX document. Click Browse files and upload your CSV or XLSX file.
3. OTAC can accept a file with a single column of offense strings, or a file with multiple columns as long as one of them contains offense strings. If your file has multiple columns, select the offense text column from the dropdown that appears.
4. To increase classification speed, OTAC will use only the offense string column and will automatically deduplicate repeated offense strings before processing.
5. Click Compute Predictions
6. A Sample Output table appears below the button showing predicted categories for the first 50 rows
7. Scroll to the bottom of the sample table and click Download data as CSV to save the full results to your computer
8. The downloaded file will contain only the deduplicated offense strings, predicted offense classifications, and confidence scores. If your original file had other columns, you will need to merge the predictions back into your full data using the offense strings as a linking key.

Try It With the Sample File First

The OTAC_Desktop folder includes otac_sample.csv with 100 sample offense strings. Open the Bulk Coder tab and upload it to confirm everything is working before using your own data.

---

7. Stopping OTAC

When you are finished, stop OTAC to free up memory on your computer.

1. Press Ctrl + C (Windows) or Control + C (Mac) in the terminal window where OTAC is running
2. Then run docker compose down to remove containers and fully free memory

OTAC also stops automatically when you shut down or restart your computer. You do not need to stop it manually before shutting down.

---

8. Troubleshooting

"Docker is not installed"

Docker Desktop has not been installed. Follow the instructions in Step 1 to download and install it.

"Docker is installed but not running"

Docker Desktop is installed but not currently open.

• Windows: Search for "Docker Desktop" in the Start menu and open it. Wait for the whale icon to appear in the taskbar.
• Mac: Open Docker Desktop from your Applications folder. Wait for the whale icon to appear in the menu bar.

Then run docker compose up --build again.

The browser opens but shows an error or a blank page

OTAC may still be loading. Wait 30–60 seconds and refresh your browser (press F5 on Windows or Cmd + R on Mac).

OTAC takes a long time to start (after the first build)

1. Press Ctrl + C (Windows) or Control + C (Mac) in the terminal window to stop OTAC, then run docker compose down
2. Make sure Docker Desktop is fully started (the whale icon should not be animating)
3. Start OTAC again

"Docker build failed" during first-time setup

Common causes:

• No internet connection — OTAC requires internet access during the first build only.
• Corporate firewall — Your organization's firewall may be blocking Docker. Contact your IT department and ask them to allow access to Docker Hub.
• Not enough disk space — OTAC requires approximately 5–6 GB of free disk space.

OTAC opened but the page looks broken or incomplete

1. Refresh the page in your browser
2. Stop OTAC and start it again
3. Try a different browser (Chrome, Edge, or Firefox)

Getting more help

OTAC is provided as a free tool. BJS does not provide technical support. For detailed troubleshooting steps and command-line diagnostics, see the Command-Line Reference section of this guide.

---

9. Command-Line Reference

This section provides detailed command-line instructions for starting, stopping, and troubleshooting OTAC. Use these steps any time you need more control or clearer error messages.

Start OTAC from the Terminal (Windows)

Step 1: Open Command Prompt

1. Press Windows key + R
2. Type cmd and press Enter
3. A black window opens (Command Prompt)

Step 2: Navigate to OTAC Folder

Type this command (replace with your actual path):

cd C:\Users\YourName\Desktop\OTAC_Desktop

Press Enter

Example: If your username is "jsmith" and OTAC is on your Desktop:

cd C:\Users\jsmith\Desktop\OTAC_Desktop

Step 3: Check Docker is Running

Type:

docker info

Press Enter

If you see Docker information: Docker is running. Continue to Step 4.

If you see an error: Docker is not running. Start Docker Desktop:

1. Press Windows key
2. Type "Docker Desktop"
3. Press Enter
4. Wait for the whale icon to stop animating
5. Try docker info again

Step 4: Start OTAC

Type the following and press Enter:

docker compose up --build

The --build flag rebuilds the image if anything has changed. On first run this takes 20–30 minutes. Subsequent runs take under 30 seconds.

Keep the terminal window open. When you see output indicating the server is ready, open http://localhost:8501 in your browser.

Stop OTAC (Windows)

1. Press Ctrl + C in the terminal window to interrupt OTAC
2. Then navigate to the OTAC_Desktop folder if needed and run:

docker compose down

Start OTAC from Terminal (Mac)

Step 1: Open Terminal

1. Press Command + Space to open Spotlight
2. Type Terminal and press Enter

Step 2: Navigate to OTAC Folder

Type this command and press Enter, replacing the path with where you extracted OTAC_Desktop:

cd ~/Documents/OTAC_Desktop

Step 3: Check Docker is Running

docker info

If you see Docker information: Docker is running. Continue to Step 4.

If you see an error: Open Docker Desktop from your Applications folder, wait for the whale icon to stop animating, then try again.

Step 4: Start OTAC

Type the following and press Enter:

docker compose up --build

Keep the Terminal window open. When ready, open http://localhost:8501 in your browser.

Stop OTAC (Mac)

1. Press Control + C in the Terminal window to interrupt OTAC
2. Then run:

docker compose down

Checking if OTAC is Running

To see if OTAC is currently running, open Command Prompt (Windows) or Terminal (Mac) and type:

docker ps

If OTAC is running, you'll see a line with "otac_app" in it.

If OTAC is not running, you'll see only the header line (CONTAINER ID, IMAGE, etc.) with no containers listed.

Viewing OTAC Logs (Troubleshooting)

If OTAC isn't working properly, you can view the logs:

docker compose logs

This shows all the messages from OTAC. Look for lines that say "ERROR" or "FAILED" — these indicate problems.

To see live logs as they happen:

docker compose logs -f

Press Ctrl + C to stop viewing logs.

Common Manual Command Issues

"docker: command not found" or "'docker' is not recognized"

• Docker is not installed, or not in your PATH
• Install Docker Desktop and restart your computer

"Cannot connect to the Docker daemon"

• Docker Desktop is not running
• Start Docker Desktop and wait for it to be ready

"no configuration file provided"

• You're not in the OTAC folder
• Use cd command to navigate to the correct folder

"port 8501 is already in use"

• OTAC is already running
• Either use it (go to http://localhost:8501) or stop it first (docker compose down)

---

10. Frequently Asked Questions

Is my data sent to the internet?

No. OTAC runs entirely on your local computer. Your offense data never leaves your machine.

Do I need to be connected to the internet to use OTAC?

Only during the very first setup (building the Docker image). After that, OTAC works completely offline.

Can I run OTAC on multiple computers?

Yes. Copy the entire OTAC_Desktop folder to each computer. Each computer needs Docker Desktop installed, and each will build the Docker image the first time (10–20 minutes per computer).

How do I know which version of OTAC I have?

The version number is in the package filename: otac-0.1.0-py3-none-any.whl — the 0.1.0 is the version.

Does OTAC require a GPU?

No. OTAC uses a model that runs on standard CPUs and does not require a graphics card.

How long does classification take?

File size	Approximate time
100 rows	10–30 seconds
1,000 rows	1–3 minutes
10,000 rows	10–20 minutes

Can multiple people use OTAC at the same time from different computers?

Sometimes, but this depends on your network and security settings. If OTAC is running on one computer, another person may be able to access it from the same local network by opening:

http://[that-computer's-IP-address]:8501

However, this may not work on government, corporate, VPN, or managed networks. Firewalls, endpoint security tools, network segmentation, or blocked ports may prevent other computers from connecting.

For most users, the supported setup is to run OTAC locally on their own computer. Do not expose OTAC to a shared network unless your organization's IT or security team has approved that use.

What is the best format for my CSV?

The simplest format is a single-column CSV with just the offense text descriptions — one row per offense. With only one column, OTAC automatically selects it and you can go straight to clicking Compute Predictions.

If your existing data file has multiple columns, that works, too. After uploading, OTAC displays a dropdown listing all text columns — select the one containing the offense descriptions, then click Compute Predictions. Both .csv and .xlsx files are accepted.

Will OTAC start automatically when I turn on my computer?

No. Docker Desktop will start automatically at login (default behavior), but OTAC itself will not run until you open a terminal, navigate to the OTAC_Desktop folder, and run docker compose up --build.

---