Touching up the documentation.

AI-Planning · Dec 25, 2024 · 2573e79 · 2573e79
1 parent af70793
commit 2573e79
Show file tree

Hide file tree

Showing 11 changed files with 58 additions and 41 deletions.
diff --git a/README.md b/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)

diff --git a/docs/extract/amdn.md b/docs/extract/amdn.md
@@ -1,15 +1,3 @@
-# AMDN
+### AMDN
 
-## Usage
-
-```python
-from macq import generate, extract
-
-print(model.details())
-```
-
-**Output:**
-
-```text
-
-```
+Coming soon...
diff --git a/docs/extract/arms.md b/docs/extract/arms.md
@@ -1,6 +1,6 @@
-# ARMS
+### ARMS
 
-## Usage
+#### Usage
 
 ```python
 from macq import generate, extract

diff --git a/docs/extract/extract.md b/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
 
 ---
 

diff --git a/docs/extract/locm.md b/docs/extract/locm.md
@@ -1 +1,3 @@
-# LOCM
+### LOCM
+
+Coming soon...
diff --git a/docs/extract/observer.md b/docs/extract/observer.md
@@ -1,6 +1,6 @@
-# Observer
+### Observer
 
-## Usage
+#### Usage
 
 ```python
 from macq import generate, extract

diff --git a/docs/extract/slaf.md b/docs/extract/slaf.md
@@ -1,6 +1,6 @@
-# SLAF
+### SLAF
 
-## Usage
+#### Usage
 
 ```python
 from macq import generate, extract

diff --git a/docs/index.md b/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
diff --git a/macq/__init__.py b/macq/__init__.py
@@ -1,4 +1,7 @@
 """
 .. include:: ../README.md
+
+----
+
 .. include:: ../docs/index.md
 """
diff --git a/macq/generate/__init__.py b/macq/generate/__init__.py
@@ -1,4 +1,5 @@
 from . import pddl
 from .plan import Plan
+import csv
 
-__all__ = ["pddl", "Plan"]
+__all__ = ["pddl", "Plan", "csv"]
diff --git a/macq/generate/csv.py b/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):