Getting Started with the ADM Health Check Tool¶

What is the ADM Health Check Tool?¶

The ADM Health Check Tool makes it easy to run the ADM Health Check and create individual model reports without coding. You will need to have Python and install pdstools, but you do not need to run a (data science) development environment, and there is no need to create a script - it is all configured from a user-friendly interface.

The application provides:

ADM Health Check: A generic overview of ADM models in your system, including charts like the “Bubble Chart” and many more, with recommendations
Individual Model Reports: Detailed views of individual Bayesian ADM models, including binning details of all predictors
No coding required: Everything is configured through a web-based UI
Excel Export: An Excel file with the model and predictor details for further analysis
Automatic report generation: Downloads ready-to-use HTML and Excel reports

Installation¶

Before installing the Python components, you need to install these external applications:

Quarto: Download from Quarto releases (v1.3.450 or later)
Pandoc: Download from Pandoc.org

These are standalone applications, not Python libraries, and must be installed separately on your system.

Installation¶

To use the stand-alone health check application, you need to install several Python components. Choose your preferred Python package manager:

We have a strong preference for uv as it’s fast, reliable, and handles Python versions automatically.

Step 1: Install uv

If you haven’t yet, install uv from https://github.com/astral-sh/uv. We recommend using the standalone installer, as it has a uv self update function.

Step 2: Install the pdstools applications as uv tool

The simplest method of running the Health Check application is by installing it to your system as a tool:

uv tool install 'pdstools[app]'

This will install the pdstools application globally on your system, making the pdstools command available from any terminal.

Note

You do not need to create a virtual environment with this method - uv handles that for you. This assures global access and avoids dependency conflicts.

Note

If you are a developer and want to contribute to the codebase, consider using the “uv + venv” method instead to install the app into a local virtual environment.

We have a strong preference for uv as it’s fast, reliable, and handles Python versions automatically.

Step 1: Install uv

If you haven’t yet, install uv from https://github.com/astral-sh/uv. We recommend using the standalone installer, as it has a uv self update function.

Step 2: Create a virtual environment

Navigate to your desired directory and run:

uv venv

Step 3: Install pdstools with app dependencies

uv pip install 'pdstools[app]'

Note

If you don’t have Python or no compatible version installed, uv will automatically install a compatible version for you.

This is the traditional Python approach using pip with virtual environments.

Step 1: Create a virtual environment

Navigate to your desired directory and run:

python -m venv .venv

Step 2: Activate the virtual environment

On macOS/Linux:

source .venv/bin/activate

On Windows:

.venv\Scripts\activate

Step 3: Upgrade pip (recommended)

python -m pip install --upgrade pip

Step 4: Install pdstools with app dependencies

pip install --upgrade 'pdstools[app]'

Remember: Always activate your virtual environment before working with the application:

source .venv/bin/activate (macOS/Linux)
.venv\Scripts\activate (Windows)

⚠️ Warning: Installing packages globally can lead to dependency conflicts. We strongly recommend using virtual environments (see other tabs).

Step 1: Upgrade pip (recommended)

python -m pip install --upgrade pip

Step 2: Install pdstools with app dependencies globally

pip install --upgrade 'pdstools[app]'

Consider using virtual environments: Global installations can cause conflicts with other Python projects. Consider switching to the “uv” or “pip + venv” methods for better project isolation.

Launching the Application¶

Once everything is installed, you can launch the Health Check application:

From any terminal, simply run:

pdstools

This will prompt you to open either the ADM Health Check or the Decision Analysis Tool. Choose the Health Check option.

uv run pdstools

First activate your virtual environment, then:

pdstools

pdstools

The app should open up in your system browser. On first run, you may get a promotional message from Streamlit asking for your email address - you can leave this empty if you want. If the app does not open automatically, simply copy the Local URL from your terminal and paste it into your browser.

Using the Application¶

Step 1: Navigate to Health Check

In the app, navigate to the Health Check tab (in the left pane). This shows instructions.

Step 2: Import Your Data

Use the Data import section on the Health Check home page to load your ADM data. The app loads a sample automatically on first launch, and you can replace it by uploading your own files directly. If your files are already on disk, expand File paths (optional) and provide either the folder containing the ADM export files or the individual file paths.

Note

If you haven’t downloaded the ADM Datamart yet, see How to export the ADM Datamart for instructions.

Direct file upload: Upload the Model Snapshot, optional Predictor Binning snapshot, and optional Prediction Table through the web interface.
File paths: Provide the folder path where the ADM files are located (e.g., /User/Downloads/), or provide individual paths. The tool will automatically find the relevant files in a configured folder.
CDH Sample: For testing, you can use the sample that loads automatically on first launch.

Advanced import settings are available for non-standard exports, including custom delimiters, quote characters, encodings, timestamp parsing, and missing required field repairs.

Note

There is no need to extract ZIP files - the application will handle that automatically.

Step 3: Configure Report Options (Optional)

On the Generate Health Check page, the Health Check options section lets you set the customer name, output type, working directory, temporary-file handling, and whether JavaScript/CSS should be embedded into a single document. If you kept processed parquet files during import, the working directory defaults to the same HC folder used for those files. The Excel export and individual model reports use the same working directory.

Step 4: Generate and Download Reports

Click “Generate” to create the ADM Health Check report. The download button will appear when generation is finished. The downloaded report will appear in your browser’s default download location as an HTML file that you can open in any web browser.

Upgrading pdstools¶

If you already had an older version of pdstools, make sure to upgrade to the latest version:

uv tool upgrade pdstools

uv pip install --upgrade 'pdstools[app]'

First activate your virtual environment, then:

pip install --upgrade 'pdstools[app]'

pip install --upgrade 'pdstools[app]'

Troubleshooting¶

Application doesn’t start

Ensure you have installed all dependencies (Quarto, Pandoc, pdstools with app dependencies)
Check that you’re using a compatible Python version (3.10 or higher)
If using virtual environments, make sure it’s activated

Reports fail to generate

Verify your ADM datamart files are in the correct format
Ensure Quarto and Pandoc are properly installed and accessible from the command line
Check the application logs in the terminal for specific error messages

For more help: - Check the example ADM analysis - Raise an issue on GitHub.