Break up getting_started into individual parts for easier digestion

Author: ma-sadeghi

docs/source/advanced_usage.md

@@ -0,0 +1,77 @@
+# Advanced Usage
+
+Alternatively, you can use the individual functions in BEaTmap to perform BET analysis and evaluate the Rouquerol criteria. This allows the user to access more of BEaTmap's functionality, and to customize the analysis.
+
+## Import the dataset
+
+The `import_data` function can be used to import a isotherm data from a .csv file where the first column is relative pressure and the second column is the amount adsorbed.
+
+The function returns a named tuple where the first entry is a dataframe of the imported isotherm, and the 2nd-4th fields are the cross sectional area of the adsorbate, information about the data, and file path, respectively. Indexing of named tuple elements is in order of priority, data used by other function are given priority.
+
+``` python
+import beatmap as bt
+import matplotlib.pylot as plt
+
+# The next line might break if you don't have the fixtures folder
+fpath = bt.utils.get_fixtures_path() / 'vulcan_chex.csv'
+isotherm_data = bt.io.import_data(file=fpath, info='chex on vulcan', a_o=39)
+```
+
+## BET analysis
+
+BET analysis is performed on every relative pressure range within the isotherm data by the `bet` function. The function accepts the dataframe of isotherm data, cross sectional area of the adsorbate, and information about the data (information stored in the named tuple created by the import_data function). Rather than pass individual parameters, this function can accept *isotherm_data (where isotherm_data is a named tuple output by a data import function).
+
+The function returns a named tuple containing the results of BET analysis as well as information about the isotherm (raw data, file path, etc). Again, the indexing of named tuple elements is in order of priority, data used by other function are given priority.
+
+```python
+bet_results = bt.core.bet(
+    iso_df=isotherm_data.iso_df,
+    a_o=isotherm_data.a_o,
+    info=isotherm_data.info
+)
+```
+
+## Rouquerol criteria
+
+The Rouquerol criteria, used to mask out results of BET analysis for invalid relative pressure ranges are evaluated by the `rouq_mask` function. Rather than pass individual parameters, this function can accept `*bet_results` (where bet_results is a named tuple output by the bet function).
+
+The function returns a named tuple containing a numpy mask array, and individual arrays corresponding to the results of each criterion.
+
+
+```python
+mask_results = bt.core.rouq_mask(
+    intercept=bet_results.intercept,
+    iso_df=bet_results.iso_df,
+    nm=bet_results.nm,
+    slope=bet_results.slope,
+    enforce_y_intercept_positive=True,
+    enforce_pressure_increasing=True,
+    enforce_absorbed_amount=True,
+    enforce_relative_pressure=True,
+    enforce_enough_datapoints=True,
+    min_num_points=5
+)
+```
+
+## Supplementary analysis
+
+The `bet_results` and `mask_results` can used to create a heatmap of specific surface area values for each relative pressure range. This visualization concept is the central idea of BEaTmap. The `ssa_heatmap` function requires the named tuples produced by the bet function and the rouq_mask function.
+
+Other figures, such as a plot of experimental data and the model isotherm can be created in this manner. See the documentation for a full summary of figures.
+
+```python
+bt.vis.ssa_heatmap(bet_results, mask_results)
+bt.vis.iso_combo_plot(bet_results, mask_results, save_file=True)
+```
+
+| Specific Surface Area Heatmap | Model Isotherm vs. Experimental Data |
+| --- | --- | 
+| ![](https://github.com/PMEAL/beatmap/assets/14086031/f785b6e4-3df4-4fa6-a6e6-b2bd2da92f96) | ![](https://github.com/PMEAL/beatmap/assets/14086031/33efdd0d-9992-4aed-888e-6e7e401037b0) |
+
+## Export the results
+
+It might be desireable to have a spreadsheet that contains all results of BET analysis and the Rouquerol criteria. This sheet can be created and saved in the parent directory with the `export_processed_data` function.
+
+```python
+bt.io.export_processed_data(bet_results)
+```

docs/source/basic_usage.md

@@ -0,0 +1,36 @@
+# Basic Usage
+
+An "envelope" function, that will import data, perform BET analysis, evaluate the Rouquerol criteria, and produce all figures for the user has been built. The file path, information about the data (later used for naming exported files), and the adsorbate cross sectional area in square Angstrom need to be specified. It allows the user to access much of BEaTmap's functionality in one line.
+
+```python
+import beatmap as bt
+import matplotlib.pylot as plt
+
+# The next line might break if you don't have the fixtures folder
+fpath = bt.utils.get_fixtures_path() / 'vulcan_chex.csv'
+
+rouq_criteria = {
+    "enforce_y_intercept_positive": True,
+    "enforce_pressure_increasing": True,
+    "enforce_absorbed_amount": True,
+    "enforce_relative_pressure": True,
+    "enforce_enough_datapoints": True,
+    "min_num_points": 5
+}
+
+aux_params = {
+    "save_figures": True,
+    "export_data": False,
+    "ssa_gradient": "Greens",
+    "err_gradient": "Greys"
+}
+
+results = bt.run_beatmap(
+    file=fpath,
+    info="chex on vulcan"
+    a_o=39,
+    ssa_criterion="error",
+    **rouq_criteria,
+    **aux_params
+)
+```

docs/source/getting_started.rst

@@ -36,8 +36,9 @@ Contents
 ########
 
 .. toctree::
-    :maxdepth: 1
+   :maxdepth: 1
 
-    getting_started.rst
-    streamlit.rst
-    modules/index.rst
+   installation.md
+   user_guide.rst
+   streamlit.rst
+   modules/index.rst

docs/source/index.rst

@@ -0,0 +1,17 @@
+# Installation
+
+BEaTmap depends heavily on the Scipy Stack. The best way to get a fully functioning environment is to install the [Anaconda Python distribution](https://www.anaconda.com/download/). Be sure to get the **Python 3.9+ version**.
+
+Once you've installed the Anaconda distribution (or the Python distribution of your choice), type and enter the following in a terminal (on Unix-based machines) or a command prompt (on Windows):
+
+    pip install beatmap
+
+Note that on Unix-based machines, `conda` is usually automatically initialized in the terminal. On Windows, you should have a shortcut to the "Anaconda Prompt" in the start menu, which is basically a command prompt initialized with `conda`.
+
+Once initialized, the terminal points to the `base` environment. While you can install BEaTmap in the `base` environment, it is recommended that you create a new environment to avoid accidentally breaking your `base` environment.
+
+If you think you may be interested in contributing to BEaTmap and wish to both *use* and *edit* the source code, then you should clone the [repository](https://github.com/PMEAL/beatmap) to your local machine, and install it using the following `pip` command:
+
+    pip install -e path/to/beatmap/root/folder
+
+For information about contributing, refer to the [contributors guide](https://github.com/PMEAL/beatmap/blob/main/CONTRIBUTING.md).

docs/source/installation.md

@@ -0,0 +1,21 @@
+.. _user_guide:
+
+User Guide
+##########
+
+You can either use BEaTmap's "envelope" function that will automatically
+execute the whole process of a BET analysis and returns the results in form 
+of informative plots and tables, or you can call the individual functions
+yourself. The latter is useful if you want more control over the process
+and possibly want to use the results for further analysis.
+
+If you prefer to go through this guide in the IPython notebook format,
+there's on in the GitHub repository. Click
+`here <https://github.com/PMEAL/beatmap/blob/main/examples/example.ipynb>`_
+to view the notebook.
+
+.. toctree::
+   :maxdepth: 1
+
+   basic_usage.md
+   advanced_usage.md