Merge pull request #212 from AI-Planning/docs

Updating documentation

.github/workflows/docs.yml

@@ -28,7 +28,7 @@ jobs:
       - run: pip install pdoc
       # ADJUST THIS: build your documentation into docs/.
       # We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here.
-      - run: pdoc macq --math -o docs
+      - run: pdoc macq --math --docformat google -o docs
 
       - uses: actions/upload-pages-artifact@v3
         with:

README.md

@@ -7,7 +7,7 @@
 
 This library is a collection of tools for planning-like action model acquisition from state trace data. It contains a reimplementation from many existing works, and generalizes some of them to new settings.
 
-## Usage
+## Example Usage
 
 ```python
 from macq import generate, extract
@@ -21,11 +21,11 @@ traces.generate_more(10)
 
 action = traces[0][0].action
 traces.get_usage(action)
-[0.05, 0.05, ..., 0.05]
+# [0.05, 0.05, ..., 0.05]
 
 trace = traces[0]
 len(trace)
-20
+# 20
 
 trace.fluents
 trace.actions
@@ -38,7 +38,7 @@ trace.get_total_cost()
 
 You can find the full scope of papers considered in the survey (implemented and otherwise) at http://macq.planning.domains . This repository of model acquisition techniques will be added to over time.
 
-## Survey Papers
+## Related Survey Papers
 
 - [A Review of Machine Learning for Automated Planning](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.231.4901&rep=rep1&type=pdf) (see Fig 2)
 - [A Review of Learning Planning Action Models](https://hal.archives-ouvertes.fr/hal-02010536/document) (see Tbl 3)

docs/extract/amdn.md

@@ -1,15 +1,3 @@
-# AMDN
+### AMDN
 
-## Usage
-
-```python
-from macq import generate, extract
-
-print(model.details())
-```
-
-**Output:**
-
-```text
-
-```
+Coming soon...

docs/extract/arms.md

@@ -1,6 +1,6 @@
-# ARMS
+### ARMS
 
-## Usage
+#### Usage
 
 ```python
 from macq import generate, extract

docs/extract/extract.md

@@ -9,7 +9,7 @@
 Include the argument `debug=True` to `Extract` to enable debugging for any
 extraction technique.
 
-_Note: debugging output and interfaces are unique to each method._
+**Note**: debugging output and interfaces are unique to each method.
 
 ## Extraction Techniques
 
@@ -19,23 +19,25 @@ _Note: debugging output and interfaces are unique to each method._
 - [AMDN](#amdn)
 - [LOCM](#locm)
 
-.. include:: ../../../docs/templates/extract/observer.md
+----
+
+.. include:: ../../docs/extract/observer.md
 
 ---
 
-.. include:: ../../../docs/templates/extract/slaf.md
+.. include:: ../../docs/extract/slaf.md
 
 ---
 
-.. include:: ../../../docs/templates/extract/arms.md
+.. include:: ../../docs/extract/arms.md
 
 ---
 
-.. include:: ../../../docs/templates/extract/amdn.md
+.. include:: ../../docs/extract/amdn.md
 
 ---
 
-.. include:: ../../../docs/templates/extract/locm.md
+.. include:: ../../docs/extract/locm.md
 
 ---
 

docs/extract/locm.md

@@ -1 +1,3 @@
-# LOCM
+### LOCM
+
+Coming soon...

docs/extract/observer.md

@@ -1,6 +1,6 @@
-# Observer
+### Observer
 
-## Usage
+#### Usage
 
 ```python
 from macq import generate, extract

docs/extract/slaf.md

@@ -1,6 +1,6 @@
-# SLAF
+### SLAF
 
-## Usage
+#### Usage
 
 ```python
 from macq import generate, extract

docs/index.md

@@ -1,22 +1,37 @@
-# Usage Documentation
+# General API
 
 ## Trace Generation
 
-- [VanillaSampling](macq/generate/pddl.html#VanillaSampling)
-- [RandomGoalSampling](macq/generate/pddl.html#RandomGoalSampling)
-- [FDRandomWalkSampling](macq/generate/pddl.html#FDRandomWalkSampling)
+These are the various methods implemented to generate the base trace data.
+
+| Algorithm | Description |
+|---|---|
+| [VanillaSampling](macq/generate/pddl.html#VanillaSampling) | Samples actions uniformly at random |
+| [RandomGoalSampling](macq/generate/pddl.html#RandomGoalSampling) | Samples goals by taking a random subset of a state reached after a random walk |
+| [FDRandomWalkSampling](macq/generate/pddl.html#FDRandomWalkSampling) | Random walk based on a heuristic-driven depth calculation (algorithm introduced in the [FD planning system](https://www.fast-downward.org/)) |
+| [TraceFromGoal](macq/generate/pddl.html#TraceFromGoal) | Generates a trace from a given domain/problem (with a goal state) |
+| [CSV](macq/generate/csv.html) | Reads a CSV file to generate a trace |
 
 ## Tokenization
 
-- [IdentityObservation](macq/observation.html#IdentityObservation)
-- [AtomicPartialObservation](macq/observation.html#AtomicPartialObservation)
+Once trace data is loaded, you can process the traces to produce lists of observations. The methods range from the identity observation (constaining the same data as original traces) to noisy and/or partially observable observations.
+
+| Algorithm | Description |
+|---|---|
+| [IdentityObservation](macq/observation.html#IdentityObservation) | Unmodified versions of the input traces |
+| [PartialObservation](macq/observation.html#PartialObservation) | Observations with a subset of the fluents hidden in the states |
+| [AtomicPartialObservation](macq/observation.html#AtomicPartialObservation) | Similar to `PartialObservation`, except everything is stored as atomic strings (not fluents and parameters) |
+| [ActionObservation](macq/observation.html#ActionObservation) | Observations with only the actions listed (i.e., states discarded) |
+| [NoisyObservation](macq/observation.html#NoisyObservation) | Observations with added noise to the fluents |
+| [NoisyPartialObservation](macq/observation.html#NoisyPartialObservation) | Observations with added noise to the fluents and a subset of the fluents hidden in the states |
+| [NoisyPartialDisorderedParallelObservation](macq/observation.html#NoisyPartialDisorderedParallelObservation) | Observations with added noise to the fluents and a subset of the fluents hidden in the states, with the actions disordered and parallelized |
 
 ## Extraction Techniques
 
+Depending on the observation type, different extraction techniques can be used to extract the relevant information from the observations. These are currently the techniques implemented:
+
 - [Observer](macq/extract.html#observer)
 - [SLAF](macq/extract.html#slaf)
 - [ARMS](macq/extract.html#arms)
 - [AMDN](macq/extract.html#amdn)
 - [LOCM](macq/extract.html#locm)
-
-# API Documentation

macq/__init__.py

@@ -1,4 +1,7 @@
 """
 .. include:: ../README.md
+
+----
+
 .. include:: ../docs/index.md
 """

macq/generate/__init__.py

@@ -1,4 +1,5 @@
 from . import pddl
 from .plan import Plan
+import csv
 
-__all__ = ["pddl", "Plan"]
+__all__ = ["pddl", "Plan", "csv"]

macq/generate/csv.py

@@ -10,7 +10,13 @@
 
 
 def load(fname: str, act_col: str, plan_id_col: str = None):
-    """Loads a trace file as a csv into a `TraceList`.
+    """Loads a trace file as a CSV into a `TraceList`.
+
+    The CSV file should have the following properties:
+
+    - An action column that contains the action names.
+    - Fluent columns with cells containing 0 or 1.
+    - (optionally) A plan ID column that contains the plan ID to separate the traces.
 
     Args:
         fname (str):

pyproject.toml

@@ -1,3 +1,65 @@
 [build-system]
 requires = ["setuptools", "wheel"]
 build-backend = "setuptools.build_meta"
+
+[project]
+name = "macq"
+version = "0.3.11"
+description = "Action model acquisition from state trace data."
+# author="Ethan Callanan, Rebecca De Venezia, Victoria Armstrong, Alison Parades, Tathagata Chakraborti, Christian Muise",
+authors = [
+    {name = "Ethan Callanan"},
+    {name = "Rebecca De Venezia"},
+    {name = "Victoria Armstrong"},
+    {name = "Alison Parades"},
+    {name = "Tathagata Chakraborti"},
+    {name = "Christian Muise", email = "[email protected]"},
+]
+maintainers = [
+    {name = "Christian Muise", email = "[email protected]"}
+]
+readme = "README.md"
+license = {file = "LICENSE"}
+keywords = ["planning", "action model acquisition"]
+requires-python = ">=3.8"
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3 :: Only",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "tarski",
+    "requests",
+    "rich",
+    "nnf",
+    "python-sat",
+    "bauhaus",
+    "numpy",
+    "clingo",
+    "graphviz",
+    "networkx",
+    "pydot",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "flake8",
+    "black",
+    "pre-commit",
+]
+
+[project.urls]
+Homepage = "https://macq.planning.domains"
+Documentation = "https://ai-planning.github.io/macq/"
+Repository = "https://github.com/ai-planning/macq"

setup.py

@@ -1,67 +1,5 @@
-from setuptools import setup, find_packages
 
-VERSION = "0.3.10"
+from setuptools import setup
 
-NAME = "macq"
 
-DESCRIPTION = "Action model acquisition from state trace data."
-
-DEPENDENCIES = [
-    "tarski",
-    "requests",
-    "rich",
-    "nnf",
-    "python-sat",
-    "bauhaus",
-    "numpy",
-    "clingo",
-    "graphviz",
-    "networkx",
-    "pydot",
-]
-
-DEV_DEPENDENCIES = [
-    "pytest",
-    "pytest-cov",
-    "flake8",
-    "black",
-    "pre-commit",
-]
-
-CLASSIFIERS = [
-    "Intended Audience :: Science/Research",
-    "Topic :: Scientific/Engineering",
-    "Topic :: Scientific/Engineering :: Mathematics",
-    "Programming Language :: Python",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3 :: Only",
-    "License :: OSI Approved :: MIT License",
-    "Operating System :: OS Independent",
-]
-
-with open("LICENSE", "r", encoding="utf-8") as f:
-    LICENSE = f.read()
-
-with open("README.md", "r", encoding="utf-8") as f:
-    LONG_DESCRIPTION = f.read()
-
-setup(
-    name=NAME,
-    version=VERSION,
-    author="Ethan Callanan, Rebecca De Venezia, Victoria Armstrong, Alison Parades, Tathagata Chakraborti, Christian Muise",
-    author_email="[email protected]",
-    license="MIT",
-    description=DESCRIPTION,
-    long_description=LONG_DESCRIPTION,
-    long_description_content_type="text/markdown",
-    keywords="planning model acquisition trace",
-    url="https://github.com/ai-planning/macq",
-    classifiers=CLASSIFIERS,
-    python_requires=">=3.9",
-    install_requires=DEPENDENCIES,
-    extras_require={"dev": DEV_DEPENDENCIES},
-)
+setup()