causaliq-core 0.1.0__tar.gz

causaliq_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CausalIQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

causaliq_core-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: causaliq-core
+Version: 0.1.0
+Summary: Core utilities and classes for the CausalIQ ecosystem
+Author-email: CausalIQ <info@causaliq.org>
+Maintainer-email: "Dr. Ken Kitson" <info@causaliq.org>
+License: MIT
+Project-URL: Homepage, https://github.com/causaliq/causaliq-core
+Project-URL: Documentation, https://github.com/causaliq/causaliq-core#readme
+Project-URL: Repository, https://github.com/causaliq/causaliq-core
+Project-URL: Bug Tracker, https://github.com/causaliq/causaliq-core/issues
+Keywords: causaliq
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: platformdirs>=3.0.0
+Requires-Dist: py-cpuinfo>=9.0.0
+Requires-Dist: psutil>=5.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: isort>=5.10.0; extra == "dev"
+Requires-Dist: flake8>=5.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: types-requests>=2.32.0; extra == "dev"
+Requires-Dist: types-psutil>=5.9.0; extra == "dev"
+Requires-Dist: pandas-stubs>=1.5.0; extra == "dev"
+Requires-Dist: pre-commit>=2.20.0; extra == "dev"
+Requires-Dist: build>=0.8.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-mock>=3.10.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
+Requires-Dist: mkdocstrings==0.30.1; extra == "docs"
+Requires-Dist: mkdocstrings-python==1.18.2; extra == "docs"
+Dynamic: license-file
+
+# causaliq-core
+
+[![Python Support](https://img.shields.io/pypi/pyversions/zenodo-sync.svg)](https://pypi.org/project/zenodo-sync/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+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
+
+```bash
+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.
+
+```text
+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.
+
+```text
+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
+
+```text
+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.
+
+```text
+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

causaliq_core-0.1.0/README.md

@@ -0,0 +1,119 @@
+# causaliq-core
+
+[![Python Support](https://img.shields.io/pypi/pyversions/zenodo-sync.svg)](https://pypi.org/project/zenodo-sync/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+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
+
+```bash
+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.
+
+```text
+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.
+
+```text
+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
+
+```text
+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.
+
+```text
+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

causaliq_core-0.1.0/pyproject.toml

@@ -0,0 +1,175 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "causaliq-core"
+dynamic = ["version"]
+description = "Core utilities and classes for the CausalIQ ecosystem"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "CausalIQ", email = "info@causaliq.org"},
+]
+maintainers = [
+    {name = "Dr. Ken Kitson", email = "info@causaliq.org"},
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+keywords = ["causaliq"]
+requires-python = ">=3.9"
+dependencies = [
+    "click>=8.0.0",
+    "numpy>=1.20.0",
+    "pandas>=1.3.0",
+    "platformdirs>=3.0.0",
+    "py-cpuinfo>=9.0.0",
+    "psutil>=5.8.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-mock>=3.10.0",
+    "black>=22.0.0",
+    "isort>=5.10.0",
+    "flake8>=5.0.0",
+    "mypy>=1.0.0",
+    "types-requests>=2.32.0",
+    "types-psutil>=5.9.0",
+    "pandas-stubs>=1.5.0",
+    "pre-commit>=2.20.0",
+    "build>=0.8.0",
+    "twine>=4.0.0",
+]
+test = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-mock>=3.10.0",
+]
+docs = [
+    "mkdocs>=1.5.0",
+    "mkdocs-material>=9.0.0",
+    "mkdocstrings==0.30.1",
+    "mkdocstrings-python==1.18.2"
+]
+
+[project.urls]
+Homepage = "https://github.com/causaliq/causaliq-core"
+Documentation = "https://github.com/causaliq/causaliq-core#readme"
+Repository = "https://github.com/causaliq/causaliq-core"
+"Bug Tracker" = "https://github.com/causaliq/causaliq-core/issues"
+
+[project.scripts]
+causaliq-core = "causaliq_core.cli:main"
+cqcor = "causaliq_core.cli:main"
+
+[tool.setuptools.dynamic]
+version = {attr = "causaliq_core.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q --strict-markers --cov=causaliq_core --cov-report=term-missing --cov-report=html"
+testpaths = [
+    "tests",
+]
+python_files = [
+    "test_*.py",
+    "*_test.py",
+]
+python_classes = [
+    "Test*",
+]
+python_functions = [
+    "test_*",
+]
+markers = [
+    "unit: Unit tests (fast, no external dependencies)",
+    "functional: Functional tests (CLI behavior, mocked external deps)",
+    "integration: Integration tests (real external dependencies)",
+    "slow: Slow tests that take significant time",
+]
+
+[tool.coverage.run]
+source = ["src/causaliq_core"]
+omit = [
+    "*/tests/*",
+    "*/test_*.py",
+]
+parallel = true
+concurrency = ["thread", "multiprocessing"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]
+
+[tool.black]
+line-length = 79
+target-version = ['py39']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | build
+  | dist
+)/
+'''
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+line_length = 79
+known_first_party = ["causaliq_core"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false

causaliq_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

causaliq_core-0.1.0/src/causaliq_core/__init__.py

@@ -0,0 +1,30 @@
+"""
+causaliq-core: Core utilities and classes for the CausalIQ ecosystem
+"""
+
+__version__ = "0.1.0"
+__author__ = "CausalIQ"
+__email__ = "info@causaliq.org"
+
+# Package metadata
+__title__ = "causaliq-core"
+__description__ = "Core utilities and classes for the CausalIQ ecosystem"
+
+__url__ = "https://github.com/causaliq/causaliq-core"
+__license__ = "MIT"
+
+
+# Version tuple for programmatic access
+VERSION = tuple(map(int, __version__.split(".")))
+
+# Legacy software version constant (migrated from legacy.py)
+SOFTWARE_VERSION: int = 229
+
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "__email__",
+    "VERSION",
+    "SOFTWARE_VERSION",
+]

causaliq_core-0.1.0/src/causaliq_core/cli.py

@@ -0,0 +1,30 @@
+"""Command-line interface for causaliq-core."""
+
+import click
+
+
+@click.command(name="causaliq-core")
+@click.version_option(version="0.1.0")
+@click.argument(
+    "name",
+    metavar="NAME",
+    required=True,
+    nargs=1,
+)
+@click.option("--greet", default="Hello", help="Greeting to use")
+def cli(name: str, greet: str) -> None:
+    """
+    Simple CLI example.
+
+    NAME is the person to greet
+    """
+    click.echo(f"{greet}, {name}!")
+
+
+def main() -> None:
+    """Entry point for the CLI."""
+    cli(prog_name="causaliq-core (cqcor)")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

causaliq_core-0.1.0/src/causaliq_core/graph/__init__.py

@@ -0,0 +1,63 @@
+"""
+Graph-related enums and utilities for CausalIQ Core.
+"""
+
+from enum import Enum
+from typing import Dict, List, Optional
+
+from pandas import DataFrame
+
+# Supported BayeSys versions for graph comparison semantics
+BAYESYS_VERSIONS = ["v1.3", "v1.5+"]
+
+
+def adjmat(columns: Optional[Dict[str, List[int]]] = None) -> DataFrame:
+    """
+    Create an adjacency matrix with specified entries.
+
+    :param dict columns: data for matrix specified by column
+
+    :raises TypeError: if arg types incorrect
+    :raises ValueError: if values specified are invalid
+
+    :returns DataFrame: the adjacency matrix
+    """
+    if (
+        columns is None
+        or not isinstance(columns, dict)
+        or not all([isinstance(c, list) for c in columns.values()])
+        or not all([isinstance(e, int) for c in columns.values() for e in c])
+    ):
+        raise TypeError("adjmat called with bad arg type")
+
+    if not all([len(c) == len(columns) for c in columns.values()]):
+        raise ValueError("some columns wrong length for adjmat")
+
+    valid = [e.value[0] for e in EdgeType]  # valid edge integer codes
+    if not all([e in valid for c in columns.values() for e in c]):
+        raise ValueError("invalid integer values for adjmat")
+
+    adjmat_df = DataFrame(columns, dtype="int8")
+    adjmat_df[""] = list(adjmat_df.columns)
+    return adjmat_df.set_index("")
+
+
+class EdgeMark(Enum):
+    """Supported 'ends' of an edge in a graph."""
+
+    NONE = 0
+    LINE = 1
+    ARROW = 2
+    CIRCLE = 3
+
+
+class EdgeType(Enum):
+    """Supported edge types and their symbols."""
+
+    NONE = (0, EdgeMark.NONE, EdgeMark.NONE, "")
+    DIRECTED = (1, EdgeMark.LINE, EdgeMark.ARROW, "->")
+    UNDIRECTED = (2, EdgeMark.LINE, EdgeMark.LINE, "-")
+    BIDIRECTED = (3, EdgeMark.ARROW, EdgeMark.ARROW, "<->")
+    SEMIDIRECTED = (4, EdgeMark.CIRCLE, EdgeMark.ARROW, "o->")
+    NONDIRECTED = (5, EdgeMark.CIRCLE, EdgeMark.CIRCLE, "o-o")
+    SEMIUNDIRECTED = (6, EdgeMark.CIRCLE, EdgeMark.LINE, "o-")