Sync with tutorial (#30)

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Version 0.4.1 - 0.4.3
+
+- Helper methods to create sample mapping if not provided.
+- Subset operations on samples.
+- Update sphinx configuration to run snippets in the documentation.
+
 ## Version 0.4.0
 
 This is a complete rewrite of the package, following the functional paradigm from our [developer notes](https://github.com/BiocPy/developer_guide#use-functional-discipline).

README.md

@@ -4,19 +4,32 @@
 
 # MultiAssayExperiment
 
-Container class to represent and manage multi-omics genomic experiments. Follows Bioconductor's [MAE R/Package](https://bioconductor.org/packages/release/bioc/html/MultiAssayExperiment.html).
+Container class to represent and manage multi-omics genomic experiments. `MultiAssayExperiment` (MAE) simplifies the management of multiple experimental assays conducted on a shared set of specimens, follows Bioconductor's [MAE R/Package](https://bioconductor.org/packages/release/bioc/html/MultiAssayExperiment.html).
 
 ## Install
 
-Package is published to [PyPI](https://pypi.org/project/multiassayexperiment/)
+To get started, install the package from [PyPI](https://pypi.org/project/multiassayexperiment/)
 
 ```shell
 pip install multiassayexperiment
 ```
 
 ## Usage
 
-First create mock sample data
+An MAE contains three main entities,
+
+- **Primary information** (`column_data`): Bio-specimen/sample information. The `column_data` may provide information about patients, cell lines, or other biological units. Each row in this table represents an independent biological unit. It must contain an `index` that maps to the 'primary' in `sample_map`.
+
+- **Experiments** (`experiments`): Genomic data from each experiment. either a `SingleCellExperiment`, `SummarizedExperiment`, `RangedSummarizedExperiment` or any class that extends a `SummarizedExperiment`.
+
+- **Sample Map** (`sample_map`): Map biological units from `column_data` to the list of `experiments`. Must contain columns,
+    - **assay** provides the names of the different experiments performed on the biological units. All experiment names from experiments must be present in this column.
+    - **primary** contains the sample name. All names in this column must match with row labels from col_data.
+    - **colname** is the mapping of samples/cells within each experiment back to its biosample information in col_data.
+
+    Each sample in ``column_data`` may map to one or more columns per assay.
+
+Let's start by first creating few experiments:
 
 ```python
 from random import random
@@ -67,7 +80,7 @@ sample_map = BiocFrame({
 sample_data = BiocFrame({"samples": ["sample1", "sample2"]}, row_names= ["sample1", "sample2"])
 ```
 
-Now we can create an instance of an MAE -
+Finally, we can create an `MultiAssayExperiment` object:
 
 ```python
 from multiassayexperiment import MultiAssayExperiment

docs/conf.py

@@ -72,14 +72,16 @@
     "sphinx.ext.ifconfig",
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 
 # Enable markdown
-extensions.append("myst_parser")
+# extensions.append("myst_parser")
+extensions.append("myst_nb")
 
 # Configure MyST-Parser
 myst_enable_extensions = [
@@ -311,8 +313,9 @@
     "anndata": ("https://anndata.readthedocs.io/en/latest/", None),
     "biocframe": ("https://biocpy.github.io/BiocFrame", None),
     "genomicranges": ("https://biocpy.github.io/GenomicRanges", None),
-    "singelcellexperiment": ("https://biocpy.github.io/SingleCellExperiment", None),
+    "singlecellexperiment": ("https://biocpy.github.io/SingleCellExperiment", None),
     "summarizedexperiment": ("https://biocpy.github.io/SummarizedExperiment", None),
+    "biocutils": ("https://biocpy.github.io/BiocUtils", None),
 }
 
 print(f"loading configurations for {project} {version} ...", file=sys.stderr)

docs/index.md

@@ -1,10 +1,10 @@
 # MultiAssayExperiment
 
-Container class to represent multiple experiments and assays performed over a set of samples. follows Bioconductor's [MAE R/Package](https://bioconductor.org/packages/release/bioc/html/MultiAssayExperiment.html).
+Container class to represent and manage multi-omics genomic experiments. `MultiAssayExperiment` (MAE) simplifies the management of multiple experimental assays conducted on a shared set of specimens, follows Bioconductor's [MAE R/Package](https://bioconductor.org/packages/release/bioc/html/MultiAssayExperiment.html).
 
 ## Install
 
-Package is published to [PyPI](https://pypi.org/project/multiassayexperiment/)
+To get started, install the package from [PyPI](https://pypi.org/project/multiassayexperiment/)
 
 ```shell
 pip install multiassayexperiment
@@ -15,8 +15,7 @@ pip install multiassayexperiment
 ```{toctree}
 :maxdepth: 2
 
-Overview <readme>
-Tutorial <tutorial>
+Overview <overview>
 Module Reference <api/modules>
 Contributions & Help <contributing>
 License <license>