causaliq-core 0.1.0

Core utilities and classes for the CausalIQ ecosystem

causaliq-core

This is a template for creating new CausalIQ repos which provides a new capability and follows CausalIQ development practices.

Status

🚧 Active Development - This repository is currently in active development. It will be updated periodically to align with the latest approaches used in CausalIQ repos. New repos within the CausalIQ project should follow the naming convention causaliq-[capability], e.g. "causaliq-discovery" or "causaliq-analysis".

Features

• 📁 Standardised project structure: following current best practices
• ⌨️ CLI Interface: An initial dummy command-line interface.
• 📖 Documentation framework: using mkdocs with shared CausalIQ branding.
• 🐍 Python setup: providing virtual environments for Python 3.9, 3.10, 3.11 and 3.12.
• 🔬 pytest test framework: for unit, functional and integration testing including code coverage.
• 🔄 Continuous Integration testing: across Python versions and operating systems using GitHub actions

New CausalIQ repo creation

This section provides instructions for creating a completely new CausalIQ repo which offers a new capability. This capability will be referred to as "newcapability" in the following instructions below, but should in practice be a word which meaningfully summarises the capability e.g. "pipeline" or "score".

Prerequisites

• Git
• Latest stable versions of Python 3.9, 3.10. 3.11 and 3.12

Create the new repo on GitHub

• Create the new repo with name causaliq-newcapability specifying this repository (i.e. causaliq-core) as the template with an initial commit message "feat: initial project setup from causaliq-core"

Clone the new repo locally and check that it works

Clone the causaliq-newcapability repo locally as normal

git clone https://github.com/causaliq/causaliq-newcapability.git

Set up the Python virtual environments and activate the default Python virtual environment. You may see messages from VSCode (if you are using it as your IDE) that new Python environments are being created as the scripts/setup-env runs - these messages can be safely ignored at this stage.

scripts/setup-env -Install
scripts/activate

Check that the causaliq-core CLI is working, check that all CI tests pass, and start up the local mkdocs webserver. There should be no errors reported in any of these.

causaliq-core --help
scripts/check_ci
mkdocs serve

Enter http://127.0.0.1:8000/ in a browser and check that the causaliq-core skeleton documentation is visible.

If all of the above works, this confirms that the code from the template repo is working successfully on your system.

Change all references in package to new package name

In the IDE (e.g. VSCode) editor make the following GLOBAL changes to all files and folder names

• replace causaliq-core with causaliq-newcapability in all files (57 changes across 16 files)
• replace causaliq_core with causaliq_newcapability in all files (13 changes across 5 files)
• rename folder src/causaliq_core to src/causaliq_newcapability
• manually delete the src/causaliq-core.egg-info package file
• manually delete all folders under venv (which will contain references to the causaliq-core)

⚠️ Important: Make sure to use underscores for Python package names (causaliq_newcapability) and hyphens for repo names (causaliq-newcapability)

Check newly named package works OK and commit to GitHub

• Remove and re-setup the virtual environments again (which will then contain the package causaliq-newcapability), and activate the default Pyhton virtual environment

scripts/setup-env -Install
scripts/activate

Check the causaliq-newcapability command runs, that all CI checks pass with the new package name, and that mkdocs for the renamed package can be served.

causaliq-newcapability --help
scripts/check_ci
mkdocs serve

This should all work without any errors and the mkdocs should refer to causaliq-newcapability rather than causaliq-core.

This confirms that the package name has been successfully changed to "causaliq-newcapability". These changes can be commited to the new repo with message "refactor: package name changed to causaliq-newcapability"

Start work on new package

The real work of implementing the functionality of this new CausalIQ package can now begin!

Checklist

• GitHub repo created from template
• Repo cloned locally
• Initial tests pass
• All references renamed
• Folder renamed
• venv folders deleted
• Final tests pass
• Commit changes implementing new package name to GitHub
• Start work on the new package functionality!

---

Supported Python Versions: 3.9, 3.10, 3.11, 3.12
Default Python Version: 3.11