Skip to content

quick-start.md

Latest commit

 

History

History
182 lines (119 loc) · 4.83 KB

quick-start.md

File metadata and controls

182 lines (119 loc) · 4.83 KB

Quick Start

Need help? See FAQ & Troubleshooting or post in GitHub Discussions.

Option 1: Pre-Built Executable

Best for: Users who want to run CORE without installing Python or managing dependencies.

1. Download

Download the latest executable for your operating system from the Releases page and unzip the downloaded file.

2. Verify the Installation

Open a terminal in the unzipped directory and run:

Windows (PowerShell):

.\core.exe --help

Linux / Mac:

# Make it executable (one-time setup)
chmod +x ./core

./core --help

Mac users: If you see a security warning, remove the quarantine attribute first:

xattr -rd com.apple.quarantine .

3. (Optional) Update the Cache

Executable releases ship with a pre-populated cache, so you can skip this step and go straight to validation. If you want the latest published rules, see CLI Reference → update-cache for API key setup and options.

Note: Rules published after a release may depend on engine features not present in that executable. When in doubt, wait for the next release rather than updating the cache manually.

4. Run a Validation

Windows:

.\core.exe validate -s sdtmig -v 3-4 -d C:\path\to\datasets

Linux / Mac:

./core validate -s sdtmig -v 3-4 -d /path/to/datasets

5. (Optional) Run a Built-In Test

CORE ships with a self-test command to confirm the executable is working:

# Windows
.\core.exe test-validate json

# Linux/Mac
./core test-validate json

Test files are cleaned up automatically after completion.

Option 2: From Source Code

Best for: Developers, contributors, or users who need the latest features.

Prerequisites

  • Python 3.12 is required. Other versions are not supported. Check your version:
  python --version

Install Python 3.12 from python.org if needed.

  • Git is required to clone the repository. Check your version:
  git --version

Install Git from git-scm.com if needed.

1. Clone the Repository

git clone https://github.com/cdisc-org/cdisc-rules-engine.git
cd cdisc-rules-engine

2. Create and Activate a Virtual Environment

Linux / Mac:

python -m venv venv
source venv/bin/activate

Windows:

python -m venv venv
.\venv\Scripts\Activate

If you have multiple Python versions, use python3.12 -m venv venv explicitly.

3. Install Dependencies

pip install uv
uv pip sync pylock.toml

Note: pylock.toml is a standard format (PEP 751) and can be used with any compatible tool. If you prefer not to use uv, you can install directly from pyproject.toml using standard pip (pip install .) or any other PEP 517-compatible tool such as pip-tools or Poetry. Note that exact version pinning is only guaranteed when using a tool that supports pylock.toml.

4. Populate the Cache

python core.py update-cache

5. Run a Validation

python core.py validate -s sdtmig -v 3-4 -d /path/to/datasets

Supported Dataset Formats

CORE supports the following input formats:

Format Description
XPT SAS Transport Format (version 5)
JSON Dataset-JSON ≥ v1.1 (CDISC standard)
NDJSON Newline Delimited JSON
XLSX Microsoft Excel
CSV CORE Comma Separated Value Test Data

Note: See here for a description of CSV formatting Note: Define-XML files must be provided via --define-xml-path (-dxp), not through the dataset directory.

CLI Command Reference

All commands and flags are documented in the CLI Reference.

Command summary:

Command Purpose
validate Run conformance validation
update-cache Download/refresh rules, CT, and metadata
list-rules List rules available in the cache
list-rule-sets List standards and versions in the cache
list-ct List controlled terminology packages in the cache

Throughout these docs, examples use python core.py. If you're using the executable, replace this with .\core.exe (Windows) or ./core (Linux/Mac).