diff --git a/docs/source/desktop.md b/docs/source/desktop.md
index 01d10408..e541e399 100644
--- a/docs/source/desktop.md
+++ b/docs/source/desktop.md
@@ -4,11 +4,11 @@ BMDS Desktop is a graphical user interface to execute dose-response modeling on
BMDS Desktop is identical to [BMDS Online](https://bmdsonline.epa.gov), with a few additional features:
-* Analyses (dose response analyses) and data storage is fully offline
+* Analyses (dose response analyses) and data storage are fully offline
* Database files (projects) are single files containing all analyses
* Within a project, analyses can be labelled and organized
-Follow the [installation](installation.md) guide to install the software. Make sure to create the [BMDS Desktop Manager](./installation.md#the-bmds-desktop-manager) shortcut. To start BMDS Desktop, double-click the shortcut and then enter option `1` to start the application:
+Follow the [installation](installation.md) guide to install the software. Make sure to create the [BMDS Desktop Manager](./installation.md#create-the-bmds-desktop-manager-shortcut) shortcut. To start BMDS Desktop, double-click the shortcut and then enter option `1` to start the application:
```{figure} _static/img/bmds-desktop-manager.jpg
:alt: BMDS Desktop Manager
@@ -29,7 +29,7 @@ The BMDS Desktop Startup Interface is the gateway to create a BMDS project and s
```{figure} _static/img/desktop-startup.jpg
:alt: Screenshot of BMDS Desktop Startup
-BMDS Desktop Startup Interface. On startup, you see a list existing projects that have been run with BMDS Desktop; you can create new projects from this screen as well. Navigate the interface using your keyboard or mouse.
+BMDS Desktop Startup Interface. On startup, you see a list of existing projects that have been run with BMDS Desktop. You can create new projects from this screen as well. Navigate the interface using your keyboard or mouse.
```
Each project in BMDS Desktop contains all of that project's analyses stored in a single file. You can create a single project and store all of your analyses in a single file, or multiple projects - one project per chemical, for example.
@@ -43,7 +43,7 @@ BMDS Desktop Project Creation. Create a new project by specifying a path and a d
```
:::{important}
-Creating a new project creates an accompanying database file at the path and filename specified if it does not already exist. Database files should have the `.db` extension. BMDS Desktop also creates other files with different extensions in that directory- `.db-shm` and `.db-wal`. **Do not delete those files -** they allow multiple users to work with the same project concurrently.
+Creating a new project creates an accompanying database file at the path and filename specified if it does not already exist. Database files should have the `.db` extension. BMDS Desktop also creates other files with different extensions in that directory, such as `.db-shm` and `.db-wal`. **Do not delete those files -** they allow multiple users to work with the same project concurrently.
:::
You can also update a database's location, in the event that you moved the database to a new directory. Updating the database refreshes the path/location so BMDS Desktop can find it again; the updating process does not change the file's contents.
@@ -52,8 +52,7 @@ Deleting a project from the BMDS Desktop Startup Interface deletes its entry in
## BMDS Desktop Application
-After at least one project has been created, press the "Start"
- button to run the project. Starting a project will open a new BMDS Desktop tab in your default browser. For a new project, initial startup may take up to a minute for the browser tab to appear.
+After at least one project has been created, select the "Start" button to run the project. Starting a project will open a new BMDS Desktop tab in your default browser. For a new project, initial startup may take up to a minute before the browser tab appears.
You can run only one BMDS Desktop project at a time.
diff --git a/docs/source/development.md b/docs/source/development.md
index 2e595a15..3d825d75 100644
--- a/docs/source/development.md
+++ b/docs/source/development.md
@@ -1,6 +1,6 @@
# Development
-Like layers of an onion, there are multiple BMDS products that can be developed, each of which require slightly different build steps and tooling. A description of each of the environments is described below.
+BMDS consists of multiple products, each of which requires slightly different build steps and tooling. The following sections describe each of those environments.
## Building and testing `pybmds`
@@ -21,11 +21,11 @@ python -m pip install -U pip
python -m pip install -e ".[dev,docs]"
```
-This will install the package and all dependencies, including building the C++ `bmdscore` shared object which will require a compiler and related dependencies installed and configured for your local setup.
+This will install the package and all dependencies, including building the C++ `bmdscore` shared object, which will require a compiler and related dependencies to be installed and configured for your local setup.
:::{tip}
-If you want to skip building `bmdscore` locally, you can set an environment variable `SKIP_BUILD=1` in your python environment; this will allow you to install the package but skip compilation of the shared object.
+If you want to skip building `bmdscore` locally, you can set the environment variable `SKIP_BUILD=1` in your Python environment. Setting this variable will allow you to install the package but skip compilation of the shared object.
:::
@@ -39,9 +39,9 @@ py.test
py.test -k test_my_special_test_name
```
-There is a built-in Makefile, ``make``, that runs many common utility methods for developing the application. You can run tests by running `make test`, run code formatting using `make format`, or build documentation using `make docs`. For more details or other built-in actions, view the `Makefile` (or the `make.bat` file for Windows).
+There is a built-in Makefile, ``make``, that runs many common utility methods for developing the application. You can run tests by running `make test`, run code formatting using `make format`, or build documentation using `make docs`. For more details on other built-in actions, view the `Makefile` (or the `make.bat` file for Windows).
-Github Actions are in place to execute whenever code a pull-request is submitted to check code formatting and successful tests. When code is merged into the `main` branch, a wheel artifact is created and stored on github. We use [cibuildwheel](https://cibuildwheel.pypa.io/en/stable/) to build wheel packages in Windows, Mac, and Linux using Github Actions.
+Github Actions are in place to execute whenever a pull-request is submitted to check code formatting and successful tests. When code is merged into the `main` branch, a wheel artifact is created and stored on github. We use [cibuildwheel](https://cibuildwheel.pypa.io/en/stable/) to build wheel packages in Windows, macOS, and Linux using Github Actions.
## Build and testing in `bmdscore`
@@ -68,7 +68,7 @@ See [documentation](https://github.com/USEPA/BMDS-UI/blob/main/docs/development.
## Documentation
-Documentation is generated using [Sphinx](https://www.sphinx-doc.org/). Narrative text is written in markdown; any examples of using `pybmds` are written in jupyter notebooks and are executing when building documentation; the returned notebook with any output (such as figures or output tables) are rendered directly in the documentation.
+Documentation is generated using [Sphinx](https://www.sphinx-doc.org/). Narrative text is written in Markdown; any examples of using `pybmds` are written in jupyter notebooks and are executing when building documentation; the returned notebook with any output (such as figures or output tables) are rendered directly in the documentation.
To build documentation, there are a few different commands available in the `make` file:
diff --git a/docs/source/index.md b/docs/source/index.md
index 2c62203d..1703816d 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -3,13 +3,15 @@
-The U.S. EPA [BMDS Online](https://bmdsonline.epa.gov) is a web application which allows users to execute the Benchmark Dose Modeling Software using a using a Graphical User Interface (GUI) on your web browser, no installation required. If you'd prefer to run the software on your computer, **BMDS Desktop** is the same application running locally. The Python package **bmds-ui** installs BMDS Desktop.
+The U.S. EPA [BMDS Online](https://bmdsonline.epa.gov) is a web application that enables users to execute the Benchmark Dose Modeling Software using a Graphical User Interface (GUI) on your web browser, no installation required.
-The Python package **pybmds** allows execution of dose-response models in a scripting environment. The package includes dose-response models for multiple types of dose-response data, including dichotomous, continuous, nested dichotomous, and cancer (including multitumor modeling). It is the underlying execution engine for BMDS Online and BMDS Desktop.
+If you'd prefer to run the software on your computer, **BMDS Desktop** is the same application running locally. The Python package **bmds-ui** installs BMDS Desktop.
+
+The Python package **pybmds** enables execution of dose-response models in a scripting environment. The package includes dose-response models for multiple types of dose-response data, including dichotomous, continuous, nested dichotomous, and cancer (including multitumor modeling). `pybmds` is the underlying execution engine for BMDS Online and BMDS Desktop.
**Highlights:**
-* Dose response modeling for multiple dataset types (continuous, dichotomous, nested dichotomous, cancer, multitumor)
+* Dose-response modeling for multiple dataset types (continuous, dichotomous, nested dichotomous, cancer, multitumor)
* Plotting and summary table capabilities
* Model recommendation logic
* Reporting in Microsoft Excel and Microsoft Word reports
@@ -28,7 +30,7 @@ pip install bmds-ui
The above command will not work until we are cleared for public release; please follow the detailed [installation guide](./installation.md). This message will be removed prior to official release.
:::
-**If you are new to installing Python packages** and wish to use `pybmds` or BMDS Desktop for multiple projects, then please follow the detailed [installation guide](./installation.md). The installation guide makes it easy to configure your computer including adding a shortcut to start and update the application. It also describes possible issues and solutions that may arise during installation.
+**If you are new to installing Python packages** and wish to BMDS Desktop or `pybmds`, then please follow the detailed [installation guide](./installation.md). The installation guide makes it easy to configure your computer, and describes possible issues and solutions that may arise during installation.
An example dose-response modeling session using `pybmds`:
diff --git a/docs/source/installation.md b/docs/source/installation.md
index 1555e84c..ea9d3f84 100644
--- a/docs/source/installation.md
+++ b/docs/source/installation.md
@@ -2,22 +2,22 @@
We recommend installing `bmds-ui` on your computer; this makes it possible to run both **BMDS Desktop** for a user interface and **pybmds** for scripting.
-This guide describes the basics for a user new to Python, from how to install Python, to setting up an environment, to installing the specific packages. A [simplified installer script](simplified-installer) is also available which reduces the amount of scripting required for installation.
+This guide describes the basics for a user new to Python, from how to install Python, to setting up an environment, to installing the specific packages. A [simplified installer script](simplified-installer) is also available that reduces the amount of command line typing required for installation.
:::{note}
-This guide documents a standard installation process for packages in the Python ecosystem. If you know someone who uses Python, they can likely help! If you need support, please [contact us](https://ecomments.epa.gov/bmds).
+This guide documents a standard installation process for packages in the Python ecosystem. If you know someone who uses Python, they can likely help! If you need support, please go to the [BMDS web site](https://www.epa.gov/bmds) and select the Contact Us link.
:::
(part-1)=
## Part 1 - Install Python
-You can install Python from [python.org](https://www.python.org/downloads/)[^disclaimer], [Anaconda](https://www.anaconda.com/download)[^disclaimer], or anywhere else you or your organization prefers. In general, using an Anaconda style distribution (e.g., Anaconda, Miniconda, Miniforge, etc.) may make things simpler as environment management is more tightly integrated into the software (described [below](part-2)).
+You can install Python from [python.org](https://www.python.org/downloads/)[^disclaimer], [Anaconda](https://www.anaconda.com/download)[^disclaimer], or anywhere else you or your organization prefers. In general, using an Anaconda style distribution (e.g., Anaconda, Miniconda, Miniforge, etc.) may make installation simpler as environment management is more tightly integrated into the software (described [below](part-2)).
* If installing Python from [python.org](https://www.python.org/downloads/)[^disclaimer], make sure that Python is added to your path (this is an option on Windows installers). If possible, use the most recent version available; the minimum supported version is 3.11.0 (released in 2022).
-* If installing a Conda distribution, make sure it is relatively recent version (released within the last 3 years).
+* If installing a Conda distribution, make sure it is a relatively recent version (released within the last 3 years).
(open-terminal)=
-After installing, open a terminal to check that either `python` or `conda` is available from your terminal. Follow the appropriate guide below, depending on your method of installing (click the tab below).
+After installing, open a terminal to check that either `python` or `conda` is available from your terminal. Select the appropriate guide below, depending on your method of installing.
::::{tab-set}
:::{tab-item} Anaconda
@@ -30,17 +30,19 @@ In the terminal, confirm that `conda` is available:
conda --version
```
-This should return a version, for example `conda 24.7.1`. Conda can install different versions of Python, and you should be able to install a version that is compatible with `pybmds` and BMDS Desktop as long as your conda installation is not too old.
+This should return a conda version, for example `conda 24.7.1`. Conda can install different versions of Python, and you should be able to install a version that is compatible with `pybmds` and BMDS Desktop as long as the conda installation is not too old.
If you see a conda version after typing this command, you’re ready for the next step! Otherwise, check the [FAQ](faq) for possible solutions.
:::
:::{tab-item} Python
-On Windows:
-* In the Start menu search for and run the "Command Prompt". Make sure to use the "Command Prompt" instead of "Powershell".
+**On Windows:**
+
+* In the Start menu, search for and run the "Command Prompt". Make sure to use the "Command Prompt" instead of "Powershell".
+
+**On Mac/Linux:**
-On Mac/Linux:
* You can use the built-in Terminal, or any other application you're comfortable with.
In the terminal, confirm that `python` is available:
@@ -49,7 +51,7 @@ In the terminal, confirm that `python` is available:
python --version
```
-This should return a version, for example `Python 3.12.6`. The minimum supported version of Python for `pybmds` and BMDS Desktop is Python 3.11.0; anything more recent than this should work.
+This should return a Python version, for example `Python 3.13.0`. The minimum supported version of Python for `pybmds` and BMDS Desktop is Python 3.11.0; anything more recent than this also should work.
If you see a Python version after typing this command, you’re ready for the next step! Otherwise, check the [FAQ](faq) for possible solutions.
@@ -61,7 +63,7 @@ If you see a Python version after typing this command, you’re ready for the ne
We recommend creating a [virtual environment](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments) for BMDS Desktop and pybmds.
-Virtual environments are essentially copies of Python, but you can have multiple environments on the same computer. In addition, each environment can contain different packages with different versions of those packages.
+Virtual environments are essentially copies of Python, and you can have multiple environments on the same computer. In addition, each environment can contain different packages with different versions of those packages.
Using virtual environments instead of installing in the "root" Python environment has several advantages:
@@ -75,16 +77,16 @@ Python virtual environments are simple to create, but the steps are specific dep
:::{tab-item} Anaconda
-There is one decision you'll need to make when creating an environment:
+There is one decision you'll need to make when creating an environment: **the environment name**.
-1. The environment name. You can use any name for the environment; in the example below we use the name `bmds-desktop`. If you plan on installing multiple versions of BMDS Desktop simultaneously, you may want to add the version to the name, for example, `bmds-desktop-24-1`. You cannot rename an environment after you create it (but you can delete or create a new one).
+You can use any name for the environment; in the example below we use the name `bmds-desktop`. If you plan on installing multiple versions of BMDS Desktop simultaneously, you may want to add the version to the name, for example, `bmds-desktop-24-1`. You cannot rename an environment after you create it (but you can delete or create a new one).
An example setup is below:
```bash
# create an environment named `bmds-desktop`
-# with Python 3.12 in the environment
-conda create --name bmds-desktop python=3.12
+# with Python 3.13 in the environment
+conda create --name bmds-desktop python=3.13
```
This creates an environment (by default in a path in your home directory). Anaconda manages switching or moving among environments.
@@ -95,10 +97,10 @@ This creates an environment (by default in a path in your home directory). Anac
There are two decisions you'll need to make when creating a virtual environment:
-1. The location of the environment on your computer. You will want to put this environment in your home folder, but ideally not in folders managed by cloud-syncing software such as OneDrive or Dropbox. Environments create many small files that do not need to be backed up, and backing up will hinder the performance of your cloud sync application and may slow down your computer. In the example below, we make a new `dev` folder in your home directory, but you can use other locations.
-2. The environment name. You can use any name for the environment; in the example below we use the name `bmds-desktop`. However, if you plan on installing multiple versions of BMDS Desktop simultaneously, you may want to add the version to the name, for example, `bmds-desktop-24-1`. You cannot rename an environment after you create it (but you can delete or create another one).
+1. **The location of the environment on your computer.** You will want to put this environment in your home folder, but ideally not in folders managed by cloud-syncing software such as OneDrive or Dropbox. Environments create many small files that do not need to be backed up; backing them up may hinder the performance of your cloud sync application and may slow down your computer. In the example below, we make a new `dev` folder in the home directory, but you can use other locations.
+2. **The environment name.** You can use any name for the environment; in the example below we use the name `bmds-desktop`. However, if you plan on installing multiple versions of BMDS Desktop simultaneously, you may want to add the version to the name, for example, `bmds-desktop-24-1`. You cannot rename an environment after you create it (but you can delete or create another one).
-An example setup is below. First, navigate to the folder we want to create the environment in (where `USERNAME` is your username):
+An example setup is below. First, navigate to the folder where we want to create the environment (where `USERNAME` is your username):
```batch
cd C:\Users\USERNAME
@@ -120,18 +122,20 @@ The instructions above create a virtual environment here: `C:\Users\USERNAME\dev
There are two decisions you'll need to make when creating a virtual environment:
-1. The location of the environment on your computer. You will want to put this environment in your home folder, but ideally not in folders managed by cloud-syncing software such as OneDrive or Dropbox. Environments create many small files that do not need to be backed up, and backing up will hinder the performance of your cloud sync application and may slow down your computer. In the example below, we make a new `dev` folder in your home directory, but you can use other locations.
-2. The environment name. You can use any name for the environment; in the example below we use the name `bmds-desktop`. However, if you plan on installing multiple versions of BMDS Desktop simultaneously, you may want to add the version to the name, for example, `bmds-desktop-24-1`. You cannot rename an environment after you create it (but you can delete or create another one)
+1. **The location of the environment on your computer.** You will want to put this environment in your home folder, but ideally not in folders managed by cloud-syncing software such as OneDrive or Dropbox. Environments create many small files that do not need to be backed up; backing them up may hinder the performance of your cloud sync application and may slow down your computer. In the example below, we make a new `dev` folder in the home directory, but you can use other locations.
+2. **The environment name.** You can use any name for the environment; in the example below we use the name `bmds-desktop`. However, if you plan on installing multiple versions of BMDS Desktop simultaneously, you may want to add the version to the name, for example, `bmds-desktop-24-1`. You cannot rename an environment after you create it (but you can delete or create another one)
An example setup is below:
```bash
-# create a dev folder in your home directory
-cd ~
+cd ~ # navigate to your home directory
mkdir dev
cd dev
+```
-# create a virtual environment named `bmds-desktop`
+And then create the environment:
+
+```bash
python -m venv bmds-desktop
```
@@ -149,7 +153,7 @@ The instructions above create a virtual environment here: `~/dev/bmds-desktop`.
(activate-venv)=
### Activating an environment
-After creating an environment, you'll need to activate the environment. Activating the environment means that, instead of looking at the global python environment and anything that may be installed there, your system looks at the contents within the environment you specified.
+After creating an environment, you'll need to activate the environment. Activating the environment means that, instead of looking at the global Python environment and anything that may be installed there, your system looks at the contents within the environment you specified.
::::{tab-set}
@@ -161,7 +165,7 @@ You'll need to remember the environment name you created and then activate it:
conda activate bmds-desktop
```
-If successful, you should see the environment name in front of your terminal in parenthesis, e.g.:
+If successful, you should see the environment name in front of your terminal prompt in parenthesis, e.g.:
```bash
(bmds-desktop) $
@@ -172,7 +176,7 @@ If successful, you should see the environment name in front of your terminal in
:::{tab-item} Python (Windows)
-You'll need change directories to where you created the virtual environment, and then activate it:
+Change the directory to where you created the virtual environment, and then activate it:
```batch
cd C:\Users\USERNAME\dev
@@ -180,7 +184,7 @@ cd C:\Users\USERNAME\dev
bmds-desktop\Scripts\activate
```
-If successful, you should see the environment name in front of your terminal in parenthesis, e.g.:
+If successful, you should see the environment name in front of your terminal prompt in parenthesis, e.g.:
```batch
(bmds-desktop) C:\Users\USERNAME\dev>
@@ -190,19 +194,18 @@ If successful, you should see the environment name in front of your terminal in
:::{tab-item} Python (Mac/Linux)
-You'll need change directories to where you created the virtual environment, and then activate it:
+Change the directory to where you created the virtual environment, and then activate it:
```bash
-# change directories to the location you created the environment
cd ~/dev
-# activate the environment
+
bmds-desktop/bin/activate
```
-If successful, you should see the environment name in front of your terminal in parenthesis, e.g.:
+If successful, you should see the environment name in front of your terminal prompt in parenthesis, e.g.:
```bash
-(bmds-desktop) $
+(bmds-desktop) ~/dev/bmds-desktop $
```
:::
@@ -225,7 +228,7 @@ With Python installed and a virtual environment created, you're ready to install
:::{admonition} NOTE - for internal EPA testing
:class: tip
-This portion of the guide should be used as as we develop pre-release versions. Recommended for EPA staff. Please check the FAQ below with any questions, or reach out to [Andy Shapiro](mailto:shapiro.andy@epa.gov) for any feedback. If anything is missing from the guide or anything is confusing, please let us know! This will be removed when we can officially release.
+This portion of the guide should be used as we develop pre-release versions. Recommended for EPA staff. Please check the FAQ below with any questions, or reach out to [Andy Shapiro](mailto:shapiro.andy@epa.gov) for any feedback. If anything is missing from the guide or anything is confusing, please let us know! This will be removed when we can officially release.
---
@@ -264,9 +267,11 @@ If no version is specified, `pip` will install the latest version.
After installation, you're ready to use BMDS Desktop and `pybmds`.
(desktop-shortcut)=
-### The BMDS Desktop Manager
+### Create the BMDS Desktop Manager Shortcut
+
+Starting BMDS Desktop may be difficult for users who do not frequently use the terminal. Therefore, we've created the BMDS Desktop Manager that enables you to start or upgrade BMDS Desktop by double clicking an icon on your Desktop.
-Starting the application may be difficult for users who do not frequently use the terminal. Therefore, we've created the BMDS Desktop Manager that allows you to start BMDS Desktop (or upgrade it) by double clicking an icon on your Desktop. To create the shortcut:
+Follow the prior steps to install BMDS Desktop. With the environment active, create the shortcut:
```bash
bmds-desktop --create-shortcut
@@ -278,7 +283,7 @@ The following confirmation message is displayed:
BMDS Desktop Manager Created:
-----------------------------
- C:\Users\USER\dev\bmds-desktop-bmds-desktop-manager.bat
+ C:\Users\USERNAME\dev\bmds-desktop-bmds-desktop-manager.bat
Opening this file will start BMDS Desktop.
You can move this file or create a shortcut to it.
@@ -294,7 +299,9 @@ To start the BMDS Desktop, double-click the BMDS Desktop Manager shortcut icon.
(part-4)=
## Part 4 - Starting BMDS Desktop
-To use BMDS Desktop, [open a terminal](open-terminal) and [activate](activate-venv) an environment. Then start the application:
+It is recommended to start BMDS Desktop using the BMDS Desktop Shortcut Manager, described in the prior [section](desktop-shortcut).
+
+Alternatively, you can start BMDS Desktop from your terminal. To use BMDS Desktop, [open a terminal](open-terminal), and [activate](activate-venv) an environment. Then start the application:
```bash
bmds-desktop
@@ -371,18 +378,18 @@ bmds-desktop
(simplified-installer)=
## Simplified installer
-The simplified installer (experimental) may simplify the installation process by automating the installation process and using reasonable defaults. If you wish to have multiple versions of BMDS Desktop installed at the same time on your computer, the simplified installer script may be too simple and you may need to follow the detailed guide.
+The simplified installer (experimental) uses automation and reasonable defaults to streamline the installation process. However, if you wish to have multiple versions of BMDS Desktop installed at the same time on your computer, the simplified installer script may be too simple and you may need to follow the [detailed guide](part-1).
-1. Install Python and open your terminal, following [Part 1](part-1) of the guide below. Install the most recent version available from [https://python.org](https://python.org).
+1. Install Python and open your terminal, following [Part 1](part-1) of the installation guide. Install the most recent version available from [https://python.org](https://python.org).
2. Download the installation script. Move the downloaded file to the same location that is open in your terminal. Then, run the command:
```
python install-bmds-desktop.py
```
-3. The script will install BMDS Desktop, and then will create a BMDS Desktop Manager file. Create a shortcut to the [BMDS Desktop Manager](desktop-shortcut) so you can open BMDS Desktop in the future or update to a more recent version.
+3. The script will install BMDS Desktop, and then will create a BMDS Desktop Manager file. Create a shortcut or alias to the [BMDS Desktop Manager](desktop-shortcut).
After running the installation script and creating a shortcut to the BMDS Desktop Manager, you shouldn't need to open your terminal in the future to update or run BMDS Desktop.
-To uninstall, open your terminal and navigate to the installation script as described above, but run the command below:
+To uninstall BMDS Desktop, open your terminal and navigate to the installation script as described above, and run the following command:
```
python install-bmds-desktop.py --uninstall
@@ -409,12 +416,12 @@ python install-bmds-desktop.py --uninstall
**Python** is a programming language commonly used for many different software products, from data science to websites. The `pybmds` and `bmds-ui` packages are written in the Python language and you must have a version of Python installed on your computer to use these packages.
-A Python **package** is essentially a folder of code you download that enables you to extend the Python programming language to perform a specific predefined operations in that package. In the context of BMDS, we have developed two packages:
+A Python **package** is essentially a folder of code you download that enables you to extend the Python programming language to perform specific predefined operations in that package. In the context of BMDS, we have developed two packages:
* `pybmds`, which allows you to execute dose-response models in Python scripts, and
-* `bmds-ui` which builds a user-interface for dose-response modeling. The BMDS Desktop application and [BMDS Online](https://bmdsonline.epa.gov) use the same package, configured differently.
+* `bmds-ui`, which builds a user-interface for dose-response modeling. The BMDS Desktop application and [BMDS Online](https://bmdsonline.epa.gov) use the same package, but configured differently.
-The **pip** tool which is built into Python, allows a user to install Python packages from the internet. Packages are available to all Python users on [pypi.org](https://pypi.org) (this is Python's equivalent to R's [CRAN](https://cran.r-project.org/)).
+The **pip** tool built into Python, allows a user to install Python packages from the internet. Packages are available to all Python users on [pypi.org](https://pypi.org) (this is Python's equivalent to R's [CRAN](https://cran.r-project.org/)).
A Python **virtual environment** makes it easy to set up multiple Python projects on your computer at the same time, making it easy to switch between projects. Environments also make it easier for your computer to find Python packages associated with a particular application.
@@ -430,7 +437,7 @@ To troubleshoot this error (instructions assume Windows 11):
1. Locate where Python was installed on your computer. Open Windows Explorer and search for `python.exe`.
2. Copy the complete path of where `python.exe` is found (up to the directory only; do not include the filename). You will add this folder location to your default Path.
-3. In the Start Menu, search for "environment" and then click the "Edit environment variables for your account" item. The system should open the "Environment Variables" dialog. This will enable you to update the Path variable *without* needing administrative rights.
+3. In the Start Menu, search for "environment" and then click the "Edit environment variables for your account" item (as shown in the following screening). The system should open the "Environment Variables" dialog. This will enable you to update the Path variable *without* needing administrative rights.
```{figure} _static/img/windows-edit-enviro-1.jpg
:alt: Screenshot of how to find the "Edit environment variables for your account" icon
```
@@ -439,7 +446,7 @@ To troubleshoot this error (instructions assume Windows 11):
:alt: Screenshot of User Environment Variables
```
5. Select the Path variable and then the Edit button to display the "Edit environment variable" dialog.
-6. In the "Edit environment variable" dialog, select New to create a new line in the display. Click inside the new line to select it and paste the folder path you copied from Step 2 above.
+6. In the "Edit environment variable" dialog (shown in the following screenshot), select New to create a new line in the display. Click inside the new line to select it and paste the folder path you copied from Step 2 above. Select OK to save your changes and close the dialog.
```{figure} _static/img/windows-edit-enviro-3.jpg
:alt: Screenshot of adding a new directory to the Path User environment variable
```
@@ -456,12 +463,10 @@ To troubleshoot this error (instructions assume Windows 11):
4. In a new Finder window, navigate to the root of your home folder under Users. You will need to add a path to a special file named ".zprofile". So-called *dot-files* are typically hidden in the standard Finder view. Press the keyboard shortcut Shift + Command + . (period) to toggle the display of any dot-files in the folder.
5. Use TextEdit to open the .zprofile file if it exists or use TextEdit to create a new text file and save it as .zprofile in the root of your home folder.
6. In either case, add the following line to the bottom of the .zprofile file:
-
```bash
export PATH="$PATH:/path/to/python/"
```
-
- where /path/to/python is the python directory containing the Python executable. You can paste the path you copied in Step 3.
+ where `/path/to/python` is the directory containing the Python executable. You can paste the path you copied in Step 3.
7. Restart your terminal and enter the command `python --version` and the Python version number should now appear! Continue with the installation.
@@ -471,7 +476,7 @@ To troubleshoot this error (instructions assume Windows 11):
You may see a Syntax Error message if you've started the Python interpreter and then typed installation commands not written in the Python language.
-From within the Python interpreter, you can write Python scripts using `pybmds`. However, it's not where you want to be for the installation guide. For installing BMDS Desktop, you need to be in a terminal in a location where Python can be executed. The good news is, if you're inside a Python interpreter, you're in the correct place for installation, but you'll need to exit the interpreter.
+From within the Python interpreter, you can write Python scripts using `pybmds`. However, the Python interpreter is not where you want to be for the installation guide. For installing BMDS Desktop, you need to be in a terminal in a location where Python can be executed. The good news is, if you're inside a Python interpreter, you're in the correct place for installation, but you'll need to exit the interpreter.
To exit the interactive Python interpreter and return to your terminal, type `exit()` and press Enter.
@@ -487,7 +492,7 @@ Follow the guide on [opening terminals](open-terminal) above.
(path-not-found)=
#### I got an error: `bmds-desktop: path not found`
-Variations may include: `'bmds-desktop' is not recognized as an internal or external command,
+Variations on this error may include: `'bmds-desktop' is not recognized as an internal or external command,
operable program or batch file`.
To fix, [activate](activate-venv) your Python virtual environment after successfully installing BMDS Desktop.
@@ -527,11 +532,13 @@ python -m pip install --upgrade bmds-ui --index-url https://gitlab.epa.gov/api/v
(multiple-versions)=
### Installing Multiple Versions of BMDS Desktop
-It is possible to install multiple versions of BMDS Desktop on your computer. You can even run different version of BMDS Desktop for different projects. For example, you may start an assessment using one version of BMDS Desktop and continue using that version for consistency, but may want to use a newer version for a different assessment. You can install the same version of BMDS Desktop in multiple separate environments, with each dedicated to a specific assessment project. That way, all datasets and results are clustered in their own isolated, reproducible environment.
+It is possible to install multiple versions of BMDS Desktop on your computer. You can even run different versions of BMDS Desktop for different projects.
+
+For example, you may start an assessment using one version of BMDS Desktop and continue using that version for consistency, but may want to use a newer version for a different assessment. Or, you can install the same version of BMDS Desktop in multiple separate environments, with each dedicated to a specific assessment project. That way, all datasets and results are clustered in their own isolated, reproducible environment.
Follow the [environment guide](part-2) above and create a new environment for each version. Then, activate the environment.
-You cannot install multiple versions of BMDS Desktop in the same environment.
+However, note the following constraint: you **cannot** install multiple versions of BMDS Desktop in the same environment. An environment can hold only one version of BMDS Desktop at a time, but you can create multiple environments on your computer.
(uninstalling-bmds-desktop)=
### Uninstalling BMDS Desktop
@@ -567,7 +574,7 @@ Open the path to your virtual environment using Windows Explorer and delete the
(writing-pybmds-code)=
### Writing pybmds Code
-You have many options for running the `pybmds` software. The package is a standard Python package which means if you're familiar with Python, you can use any approach for writing code you may already be familiar with.
+You have many options for running the `pybmds` software. The package is a standard Python package. If you're familiar with Python, you can use any approach for writing code you may already be familiar with.
If you are new to the Python ecosystem, you can use one of the following commonly used development environments - [jupyterlab](https://jupyter.org/)[^disclaimer], Microsoft [Visual Studio Code](https://code.visualstudio.com/)[^disclaimer], or Posit [Positron](https://github.com/posit-dev/positron)[^disclaimer].
diff --git a/docs/source/logic.md b/docs/source/logic.md
index 08c7e33c..c265b9bc 100644
--- a/docs/source/logic.md
+++ b/docs/source/logic.md
@@ -5,7 +5,7 @@ A BMDS session has a set of automated rules for recommending a best-fitting mode
1. USEPA BMDS technical guidance ([EPA 2012](https://www.epa.gov/risk/benchmark-dose-technical-guidance))
2. [Wignall et al. 2014](http://dx.doi.org/10.1289/ehp.1307539)
-When configuring a session, a user selects which models and model recommendations are enabled. If enabled, the recommendation logic has reasonable defaults, but you can also manually configure the logic by to turning on/off individual checks and threshold values. Results are extracted from model outputs, and models are placed into one of three possible bins, depending on the results and the bin recommendation logic:
+When configuring a session, a user selects which models and model recommendations are enabled. If enabled, the recommendation logic has reasonable defaults, but you can also manually configure the logic by turning on/off individual checks and threshold values. Results are extracted from model outputs, and models are placed into one of three possible bins, depending on the results and the bin recommendation logic:
1. **Failure**: model did not successfully complete
2. **Nonviable model**: model successfully completed, but there are serious issues
@@ -13,12 +13,13 @@ When configuring a session, a user selects which models and model recommendation
If at least one viable model exists, then it may be selected as a best-fitting model. This would be consistent with the workflow diagram below:
-
-
-**Model binning and recommendation. From [Wignall et al. 2014](http://dx.doi.org/10.1289/ehp.1307539).**
+```{figure} _static/img/logic.png
+:alt: Recommendation logic diagram
+Model binning and recommendation. From [Wignall et al. 2014](http://dx.doi.org/10.1289/ehp.1307539).
+```
If one and only one model is in the viable model bin, it is selected as the best-fitting model. If there are multiple models in the viable bin, then, consistent with [EPA 2012](https://www.epa.gov/risk/benchmark-dose-technical-guidance), either the model with the lowest Akaike information criterion (AIC) or benchmark dose lower confidence limit (BMDL) is selected. If the range of BMDL values is sufficiently close (<3 fold different), the AIC value is used, otherwise, the BMDL value is used.
-It is possible that some models may collapse into other models. For example, if a Power model doesn't use the power-term after parameter optimization, then it may be equivalent to a Linear model. Or, a 3rd order Polynomial may only use its first two polynomials, and therefore would be equivalent to a 2nd order Polynomial. In these two examples, equivalent models will have identical AIC and BMDL values. In such cases, the recommendation logic will pick the model with the fewest number of parameters available for curve-fitting *a priori* to parameter optimization.
+It is possible that some models may collapse into other models. For example, if a Power model doesn't use the power-term after parameter optimization, then it may be equivalent to a Linear model. Or, a 3rd-order Polynomial may only use its first two polynomials, and therefore would be equivalent to a 2nd-order Polynomial. In these two examples, equivalent models will have identical AIC and BMDL values. In such cases, the recommendation logic will pick the model with the fewest number of parameters available for curve-fitting *a priori* to parameter optimization.
Therefore, in the examples above, the Linear and Polynomial 2 model will be selected as opposed to the Power or Polynomial 3 models, respectively.
diff --git a/docs/source/quickstart.ipynb b/docs/source/quickstart.ipynb
index 24ac6e62..11eb6376 100644
--- a/docs/source/quickstart.ipynb
+++ b/docs/source/quickstart.ipynb
@@ -14,7 +14,8 @@
"%matplotlib inline\n",
"import warnings\n",
"from IPython.display import display\n",
- "warnings.filterwarnings('ignore')\n",
+ "\n",
+ "warnings.filterwarnings(\"ignore\")\n",
"# tag: remove-cell applied"
]
},
@@ -27,7 +28,7 @@
"\n",
"The `pybmds` package is designed for those familiar with basic scripting in languages like R or Python. In Python there are many different environments (jupyter notebooks, ipython, RStudio, Sypder, etc) commonly used for scripting; the example below will work in any of them. \n",
"\n",
- "This guide is recommended for people with general familiarity with scripting.\n",
+ "The following example is recommended for people already familiar with scripting.\n",
"\n",
"To create a dataset and fit a suite of dose-response models to the dataset:"
]
@@ -87,7 +88,7 @@
"id": "e41b8b61",
"metadata": {},
"source": [
- "Detailed outputs are available with the `results` attribute on each model, or you can view a quick text summary output of the model fit:\n"
+ "Detailed outputs are available with the `results` attribute on each model, or you can view a text summary of the model fit:\n"
]
},
{
diff --git a/docs/source/recipes/batch.ipynb b/docs/source/recipes/batch.ipynb
index d30cd3aa..af26e9ae 100644
--- a/docs/source/recipes/batch.ipynb
+++ b/docs/source/recipes/batch.ipynb
@@ -163,7 +163,7 @@
"source": [
"## Session batch execution\n",
"\n",
- "Alternatively, you could run a session that executes a suite of models and returns the best fitting result:"
+ "Alternatively, you could run a session that executes a suite of models and returns the best-fitting result:"
]
},
{
@@ -274,7 +274,7 @@
],
"metadata": {
"kernelspec": {
- "display_name": "Python 3 (ipykernel)",
+ "display_name": "venv",
"language": "python",
"name": "python3"
},
diff --git a/docs/source/recipes/continuous.ipynb b/docs/source/recipes/continuous.ipynb
index e56e84b8..9ef7ec99 100644
--- a/docs/source/recipes/continuous.ipynb
+++ b/docs/source/recipes/continuous.ipynb
@@ -22,7 +22,8 @@
"%matplotlib inline\n",
"import warnings\n",
"from IPython.display import display\n",
- "warnings.filterwarnings('ignore')\n",
+ "\n",
+ "warnings.filterwarnings(\"ignore\")\n",
"# tag: remove-cell applied"
]
},
@@ -54,7 +55,7 @@
" doses=[0, 25, 50, 75, 100],\n",
" ns=[20, 20, 20, 20, 20],\n",
" means=[6, 8, 13, 25, 30],\n",
- " stdevs=[4, 4.3, 3.8, 4.4, 3.7]\n",
+ " stdevs=[4, 4.3, 3.8, 4.4, 3.7],\n",
")\n",
"\n",
"# create a session\n",
@@ -106,7 +107,7 @@
" doses=[0, 25, 50, 75, 100],\n",
" ns=[20, 20, 20, 20, 20],\n",
" means=[6, 8, 13, 25, 30],\n",
- " stdevs=[4, 4.3, 3.8, 4.4, 3.7]\n",
+ " stdevs=[4, 4.3, 3.8, 4.4, 3.7],\n",
")\n",
"dataset.plot()"
]
@@ -122,7 +123,7 @@
"\n",
"You can fit a specific model to the dataset and plot/print the results. The printed results will include the BMD, BMDL, BMDU, p-value, AIC, etc. \n",
"\n",
- "For example, to fit the Hill model, run the code below and plot the results:"
+ "For example, to fit the Hill model, run the following code and plot the results:"
]
},
{
@@ -146,7 +147,7 @@
"id": "ecbf6e53-9533-4eb8-b4e3-0f37e481fcd8",
"metadata": {},
"source": [
- "Run the code below to print an output report:"
+ "To view an output report:"
]
},
{
@@ -219,10 +220,10 @@
" settings={\n",
" \"bmr\": 0.1,\n",
" \"bmr_type\": pybmds.ContinuousRiskType.RelativeDeviation,\n",
- " \"disttype\": pybmds.ContinuousDistType.normal_ncv\n",
- " }\n",
+ " \"disttype\": pybmds.ContinuousDistType.normal_ncv,\n",
+ " },\n",
")\n",
- "model.settings.priors.update('k', max_value=3)\n",
+ "model.settings.priors.update(\"k\", max_value=3)\n",
"print(model.settings.tbl())\n",
"print(model.priors_tbl())"
]
@@ -246,8 +247,8 @@
},
"outputs": [],
"source": [
- "continuous.Polynomial(dataset, settings = {\"degree\": 2})\n",
- "continuous.Polynomial(dataset, settings = {\"degree\": 3})"
+ "continuous.Polynomial(dataset, settings={\"degree\": 2})\n",
+ "continuous.Polynomial(dataset, settings={\"degree\": 3})"
]
},
{
@@ -296,7 +297,7 @@
"outputs": [],
"source": [
"model = continuous.Hill(dataset)\n",
- "model.settings.priors.update('n', initial_value=1, min_value=1, max_value=1)\n",
+ "model.settings.priors.update(\"n\", initial_value=1, min_value=1, max_value=1)\n",
"print(model.priors_tbl())"
]
},
@@ -326,7 +327,7 @@
" doses=[0, 25, 50, 75, 100],\n",
" ns=[20, 20, 20, 20, 20],\n",
" means=[6, 8, 13, 25, 30],\n",
- " stdevs=[4, 4.3, 3.8, 4.4, 3.7]\n",
+ " stdevs=[4, 4.3, 3.8, 4.4, 3.7],\n",
")\n",
"\n",
"session = pybmds.Session(dataset=dataset)\n",
@@ -338,7 +339,7 @@
"# recommend a best-fitting model\n",
"session.recommend()\n",
"\n",
- "#print recommended model and plot recommended model with dataset\n",
+ "# print recommended model and plot recommended model with dataset\n",
"model_index = session.recommender.results.recommended_model_index\n",
"if model_index:\n",
" model = session.models[model_index]\n",
@@ -394,11 +395,11 @@
"source": [
"session = pybmds.Session(dataset=dataset)\n",
"session.add_default_models(\n",
- " settings = {\n",
+ " settings={\n",
" \"disttype\": pybmds.ContinuousDistType.normal_ncv,\n",
" \"bmr_type\": pybmds.ContinuousRiskType.AbsoluteDeviation,\n",
" \"bmr\": 2,\n",
- " \"alpha\": 0.1\n",
+ " \"alpha\": 0.1,\n",
" }\n",
")"
]
@@ -457,7 +458,7 @@
"source": [
"### Model recommendation and selection\n",
"\n",
- "The `pybmds` package may recommend a best fitting model based on a decision tree, but expert judgment may be required for model selection. To run model recommendation and view a recommended model, if one is recommended:"
+ "The `pybmds` package may recommend a best-fitting model based on a decision tree, but expert judgment may be required for model selection. To run model recommendation and view a recommended model, if one is recommended:"
]
},
{
@@ -479,7 +480,7 @@
"id": "aefc97ca",
"metadata": {},
"source": [
- "You can select a best fitting model and output reports generated will indicate this selection. This is a manual action. The example below selects the recommended model, but any model in the session could be selected."
+ "You can select a best-fitting model and output reports generated will indicate this selection. This is a manual action. The example below selects the recommended model, but any model in the session could be selected."
]
},
{
@@ -495,7 +496,7 @@
],
"metadata": {
"kernelspec": {
- "display_name": "Python 3 (ipykernel)",
+ "display_name": "venv",
"language": "python",
"name": "python3"
},
diff --git a/docs/source/recipes/custom-excel-exports.ipynb b/docs/source/recipes/custom-excel-exports.ipynb
index a94fe14e..d31e28f9 100644
--- a/docs/source/recipes/custom-excel-exports.ipynb
+++ b/docs/source/recipes/custom-excel-exports.ipynb
@@ -18,7 +18,8 @@
"%matplotlib inline\n",
"%env TQDM_DISABLE=1\n",
"import warnings\n",
- "warnings.filterwarnings('ignore')\n",
+ "\n",
+ "warnings.filterwarnings(\"ignore\")\n",
"# tag: remove-cell applied"
]
},
@@ -100,8 +101,10 @@
" sess.add_model(Model, settings)\n",
"\n",
" option_sets = [\n",
- " (pybmds.ContinuousRiskType.RelativeDeviation, 0.1, pybmds.ContinuousDistType.normal),\n",
- " (pybmds.ContinuousRiskType.RelativeDeviation, 0.1, pybmds.ContinuousDistType.normal_ncv),\n",
+ " (pybmds.ContinuousRiskType.RelativeDeviation, 0.1, \n",
+ " pybmds.ContinuousDistType.normal),\n",
+ " (pybmds.ContinuousRiskType.RelativeDeviation, 0.1, \n",
+ " pybmds.ContinuousDistType.normal_ncv),\n",
" ]\n",
" sessions = []\n",
" for option_set in option_sets:\n",
@@ -156,7 +159,7 @@
},
"outputs": [],
"source": [
- "sess_batch.to_excel('output/batch.xlsx')"
+ "sess_batch.to_excel(\"output/batch.xlsx\")"
]
},
{
@@ -170,7 +173,7 @@
"tags": []
},
"source": [
- "However, you may want to customize this export to add more information. In this example, you may want to show more information regarding Analysis of Deviance Table than is generally shown in the summary exports. \n",
+ "However, you may want to customize this export to add more information. In this example, you may want to show more information regarding the Analysis of Deviance Table than is generally shown in the summary exports. \n",
"\n",
"To do this, first, generate the summary dataframe, to which you will add more info:"
]
@@ -230,18 +233,20 @@
" }\n",
" if model.has_results:\n",
" res = model.results\n",
- " data.update({\n",
- " \"A1_ll\": res.deviance.loglikelihoods[0],\n",
- " \"A2_ll\": res.deviance.loglikelihoods[1],\n",
- " \"A3_ll\": res.deviance.loglikelihoods[2],\n",
- " \"fitted_ll\": res.deviance.loglikelihoods[3],\n",
- " \"reduced_ll\": res.deviance.loglikelihoods[4],\n",
- " \"A1_aic\": res.deviance.aics[0],\n",
- " \"A2_aic\": res.deviance.aics[1],\n",
- " \"A3_aic\": res.deviance.aics[2],\n",
- " \"fitted_aic\": res.deviance.aics[3],\n",
- " \"reduced_aic\": res.deviance.aics[4],\n",
- " })\n",
+ " data.update(\n",
+ " {\n",
+ " \"A1_ll\": res.deviance.loglikelihoods[0],\n",
+ " \"A2_ll\": res.deviance.loglikelihoods[1],\n",
+ " \"A3_ll\": res.deviance.loglikelihoods[2],\n",
+ " \"fitted_ll\": res.deviance.loglikelihoods[3],\n",
+ " \"reduced_ll\": res.deviance.loglikelihoods[4],\n",
+ " \"A1_aic\": res.deviance.aics[0],\n",
+ " \"A2_aic\": res.deviance.aics[1],\n",
+ " \"A3_aic\": res.deviance.aics[2],\n",
+ " \"fitted_aic\": res.deviance.aics[3],\n",
+ " \"reduced_aic\": res.deviance.aics[4],\n",
+ " }\n",
+ " )\n",
" rows.append(data)\n",
"\n",
"df2 = pd.DataFrame(rows)\n",
@@ -308,7 +313,7 @@
},
"outputs": [],
"source": [
- "with pd.ExcelWriter('output/report.xlsx') as writer:\n",
+ "with pd.ExcelWriter(\"output/report.xlsx\") as writer:\n",
" data = {\n",
" \"summary\": df_summary2,\n",
" \"datasets\": sess_batch.df_dataset(),\n",
@@ -333,7 +338,7 @@
"\n",
"## Model result introspection\n",
"\n",
- "This section describes how to introspect model results that are available and their data structures and text summaries.\n",
+ "This section describes how to introspect model results that are available, along with their data structures and text summaries.\n",
"\n",
"Let's grab the first model that was executed and look at its results object:"
]
@@ -366,7 +371,7 @@
"tags": []
},
"source": [
- "For example, this is a nested python data structure:"
+ "For example, to show the BMD, BMDL, and AIC:"
]
},
{
@@ -398,7 +403,7 @@
"tags": []
},
"source": [
- "To better understand the structure, we can \"pretty print\" a dictionary representation:"
+ "To better understand the structure, we can \"pretty print\" the Python dictionary:"
]
},
{
@@ -414,15 +419,17 @@
},
"outputs": [],
"source": [
+ "from pprint import pprint\n",
+ "\n",
"data = res.model_dump()\n",
"\n",
"# truncate a few fields so they print better... (you can ignore this code)\n",
- "data['fit']['bmd_dist'][0] = data['fit']['bmd_dist'][0][:5]\n",
- "data['fit']['bmd_dist'][1] = data['fit']['bmd_dist'][1][:5]\n",
- "data['plotting']['dr_x'] = data['plotting']['dr_x'][:5]\n",
- "data['plotting']['dr_y'] = data['plotting']['dr_y'][:5]\n",
+ "data[\"fit\"][\"bmd_dist\"][0] = data[\"fit\"][\"bmd_dist\"][0][:5]\n",
+ "data[\"fit\"][\"bmd_dist\"][1] = data[\"fit\"][\"bmd_dist\"][1][:5]\n",
+ "data[\"plotting\"][\"dr_x\"] = data[\"plotting\"][\"dr_x\"][:5]\n",
+ "data[\"plotting\"][\"dr_y\"] = data[\"plotting\"][\"dr_y\"][:5]\n",
"\n",
- "pprint(data, indent=2, width=140, sort_dicts=True)"
+ "pprint(data, indent=2, width=100, sort_dicts=True)"
]
},
{
@@ -468,7 +475,9 @@
},
"outputs": [],
"source": [
- "for name, df, ll, p_value in zip(res.tests.names, res.tests.dfs, res.tests.ll_ratios, res.tests.p_values, strict=True):\n",
+ "for name, df, ll, p_value in zip(\n",
+ " res.tests.names, res.tests.dfs, res.tests.ll_ratios, res.tests.p_values, strict=True\n",
+ "):\n",
" print(f\"{name:10} {df: <6} {ll: <10.4f} {p_value: <8.6f}\")"
]
},
@@ -477,7 +486,7 @@
"id": "4b235271",
"metadata": {},
"source": [
- "This pattern uses the built-in [zip](https://docs.python.org/3/library/functions.html#zip) function which allows you to iterate across multiple lists of items in Python of the same size at the same time. "
+ "This pattern uses the built-in [zip](https://docs.python.org/3/library/functions.html#zip) function that allows you to iterate across multiple lists of items in Python of the same size at the same time. "
]
}
],
diff --git a/docs/source/recipes/dichotomous.ipynb b/docs/source/recipes/dichotomous.ipynb
index 4b96ec41..36a3b7ef 100644
--- a/docs/source/recipes/dichotomous.ipynb
+++ b/docs/source/recipes/dichotomous.ipynb
@@ -13,7 +13,8 @@
"source": [
"%matplotlib inline\n",
"import warnings\n",
- "warnings.filterwarnings('ignore')\n",
+ "\n",
+ "warnings.filterwarnings(\"ignore\")\n",
"from IPython.display import display\n",
"# tag: remove-cell applied"
]
@@ -79,7 +80,7 @@
"source": [
"## Dichotomous datasets\n",
"\n",
- "Creating a dichotomous dataset requires a list of doses, incidences, and the total number of subjects, one item per dose group.\n",
+ "Creating a dichotomous dataset requires a list of doses, incidences, and the total number of subjects, one item per dose group. Doses must be unique.\n",
"\n",
"You can also add optional attributes, such as `name`, `dose_name`, `dose_units`, `response_name`, `response_units`, etc.\n",
"\n",
@@ -116,7 +117,7 @@
"\n",
"You can fit a specific model to the dataset and plot/print the results. The printed results will include the BMD, BMDL, BMDU, p-value, AIC, etc. \n",
"\n",
- "The individual models available are shown below. Note that the degrees of the Multistage mode can be increased to a maximum of the lesser of N-1 or 8 (as specified in the BMDS User Guide). "
+ "The individual models available are shown below. Note that the degrees of the Multistage model can be increased to a maximum of the lesser of N-1 or 8 (as specified in the BMDS User Guide). "
]
},
{
@@ -133,8 +134,8 @@
"from pybmds.models import dichotomous\n",
"\n",
"dichotomous.QuantalLinear(dataset)\n",
- "dichotomous.Multistage(dataset, settings = {\"degree\": 2})\n",
- "dichotomous.Multistage(dataset, settings = {\"degree\": 3})\n",
+ "dichotomous.Multistage(dataset, settings={\"degree\": 2})\n",
+ "dichotomous.Multistage(dataset, settings={\"degree\": 3})\n",
"dichotomous.Logistic(dataset)\n",
"dichotomous.LogLogistic(dataset)\n",
"dichotomous.Probit(dataset)\n",
@@ -161,7 +162,6 @@
},
"outputs": [],
"source": [
- "\n",
"model = dichotomous.Logistic(dataset)\n",
"model.execute()\n",
"model.plot()"
@@ -187,14 +187,6 @@
"print(model.text())"
]
},
- {
- "cell_type": "markdown",
- "id": "635aa34b-97fb-464b-815b-0501ac31127e",
- "metadata": {},
- "source": [
- "The individual models that you can fit are shown below. Note that the degrees of the Multistage model can be increased to a maximum of the lesser of n-1 or 8 (as specified in the BMDS User Guide)."
- ]
- },
{
"cell_type": "markdown",
"id": "5541698b-e53a-44fb-836a-e3f310ade4d8",
@@ -214,10 +206,9 @@
},
"outputs": [],
"source": [
- "model = dichotomous.Logistic(dataset, settings={\n",
- " \"bmr\": 0.15,\n",
- " \"bmr_type\": pybmds.DichotomousRiskType.AddedRisk\n",
- "})\n",
+ "model = dichotomous.Logistic(\n",
+ " dataset, settings={\"bmr\": 0.15, \"bmr_type\": pybmds.DichotomousRiskType.AddedRisk}\n",
+ ")\n",
"print(model.settings.tbl())"
]
},
@@ -263,8 +254,8 @@
},
"outputs": [],
"source": [
- "model.settings.priors.update('a', min_value=-10, max_value=10)\n",
- "model.settings.priors.update('b', min_value=0, max_value=50)\n",
+ "model.settings.priors.update(\"a\", min_value=-10, max_value=10)\n",
+ "model.settings.priors.update(\"b\", min_value=0, max_value=50)\n",
"print(model.priors_tbl())"
]
},
@@ -307,7 +298,7 @@
"# recommend a best-fitting model\n",
"session.recommend()\n",
"\n",
- "#print recommended model and plot recommended model with dataset\n",
+ "# print recommended model and plot recommended model with dataset\n",
"model_index = session.recommender.results.recommended_model_index\n",
"if model_index:\n",
" model = session.models[model_index]\n",
@@ -387,11 +378,7 @@
"outputs": [],
"source": [
"session.add_default_models(\n",
- " settings = {\n",
- " \"bmr\": 0.15,\n",
- " \"bmr_type\": pybmds.DichotomousRiskType.AddedRisk,\n",
- " \"alpha\": 0.1\n",
- " }\n",
+ " settings={\"bmr\": 0.15, \"bmr_type\": pybmds.DichotomousRiskType.AddedRisk, \"alpha\": 0.1}\n",
")"
]
},
@@ -446,7 +433,7 @@
"source": [
"### Model recommendation and selection\n",
"\n",
- "The `pybmds` package may recommend a best fitting model based on a decision tree, but expert judgment may be required for model selection. To run model recommendation and view a recommended model, if one is recommended:"
+ "The `pybmds` package may recommend a best-fitting model based on a decision tree, but expert judgment may be required for model selection. To run model recommendation and view a recommended model, if one is recommended:"
]
},
{
@@ -468,7 +455,7 @@
"id": "a0b22de3-5956-4cfb-bede-6c113c434401",
"metadata": {},
"source": [
- "You can select a best fitting model and output reports generated will indicate this selection. This is a manual action. The example below selects the recommended model, but any model in the session could be selected."
+ "You can select a best-fitting model and output reports generated will indicate this selection. This is a manual action. The example below selects the recommended model, but any model in the session could be selected."
]
},
{
diff --git a/docs/source/recipes/dichotomous_ma.ipynb b/docs/source/recipes/dichotomous_ma.ipynb
index c2d4b2f4..ca9fcd99 100644
--- a/docs/source/recipes/dichotomous_ma.ipynb
+++ b/docs/source/recipes/dichotomous_ma.ipynb
@@ -58,7 +58,10 @@
" incidences=[0, 1, 7, 15, 19],\n",
")\n",
"\n",
- "model = dichotomous.Logistic(dataset=dataset, settings={\"priors\": pybmds.PriorClass.bayesian})\n",
+ "model = dichotomous.Logistic(\n",
+ " dataset=dataset, \n",
+ " settings={\"priors\": pybmds.PriorClass.bayesian}\n",
+ ")\n",
"result = model.execute()\n",
"print(model.text())"
]
@@ -121,7 +124,9 @@
},
"outputs": [],
"source": [
- "model = dichotomous.Logistic(dataset=dataset, settings={\"priors\": pybmds.PriorClass.bayesian})\n",
+ "model = dichotomous.Logistic(\n",
+ " dataset=dataset, settings={\"priors\": pybmds.PriorClass.bayesian}\n",
+ ")\n",
"\n",
"print(model.settings.tbl())\n",
"print(model.priors_tbl())"
@@ -184,7 +189,9 @@
" \"burnin\": 500\n",
" }\n",
")\n",
- "model.settings.priors.update('g', type=pybmds.PriorDistribution.Uniform, min_value=0, max_value=1)\n",
+ "model.settings.priors.update(\n",
+ " 'g', type=pybmds.PriorDistribution.Uniform, min_value=0, max_value=1\n",
+ ")\n",
"print(model.priors_tbl())"
]
},
@@ -206,7 +213,12 @@
"outputs": [],
"source": [
"model.settings.priors.update(\n",
- " 'g', type=pybmds.PriorDistribution.Lognormal, min_value=0, max_value=1, initial_value=0, stdev=1.5\n",
+ " 'g', \n",
+ " type=pybmds.PriorDistribution.Lognormal, \n",
+ " min_value=0, \n",
+ " max_value=1, \n",
+ " initial_value=0, \n",
+ " stdev=1.5,\n",
")\n",
"print(model.priors_tbl())"
]
diff --git a/docs/source/recipes/multitumor.ipynb b/docs/source/recipes/multitumor.ipynb
index d5b407b6..f02b3dcf 100644
--- a/docs/source/recipes/multitumor.ipynb
+++ b/docs/source/recipes/multitumor.ipynb
@@ -17,7 +17,8 @@
"source": [
"%matplotlib inline\n",
"import warnings\n",
- "warnings.filterwarnings('ignore')\n",
+ "\n",
+ "warnings.filterwarnings(\"ignore\")\n",
"from IPython.display import display\n",
"# tag: remove-cell applied"
]
@@ -31,9 +32,9 @@
"\n",
"Conducting dose-response analysis on dichotomous tumor data differs from analyzing standard dichotomous tumor data in the following ways:\n",
"\n",
- "* The multistage cancer model uses different parameter settings for model fit than the standard multistage model\n",
- "* A cancer slope factor is calculated\n",
- "* In some cases, there may be a need to combine multiple tumor datasets and then calculate a single cancer slope factor\n",
+ "* The Multistage cancer model uses different parameter settings for model fit than the standard Multistage model.\n",
+ "* A cancer slope factor is calculated.\n",
+ "* In some cases, there may be a need to combine multiple tumor datasets and then calculate a single cancer slope factor.\n",
"\n",
"To that end, this guide covers some different approaches that you can use in `pybmds` for handling tumor data.\n",
"\n",
@@ -57,7 +58,7 @@
" ns=[20, 20, 20, 20, 20],\n",
" incidences=[0, 1, 7, 15, 19],\n",
" name=\"Tumor dataset A\",\n",
- " dose_units=\"mg/kg-d\"\n",
+ " dose_units=\"mg/kg-d\",\n",
")\n",
"\n",
"model = MultistageCancer(dataset, settings={\"bmr\": 0.1})\n",
@@ -93,15 +94,15 @@
" ns=[20, 20, 20, 20, 20],\n",
" incidences=[0, 1, 7, 15, 19],\n",
" name=\"Tumor A\",\n",
- " dose_units=\"mg/m³\"\n",
+ " dose_units=\"mg/m³\",\n",
" ),\n",
" pybmds.DichotomousDataset(\n",
" doses=[0, 25, 75, 125, 200],\n",
" ns=[20, 20, 20, 20, 20],\n",
" incidences=[0, 0, 1, 7, 11],\n",
" name=\"Tumor B\",\n",
- " dose_units=\"mg/m³\"\n",
- " )\n",
+ " dose_units=\"mg/m³\",\n",
+ " ),\n",
"]\n",
"\n",
"session = pybmds.Multitumor(datasets, settings={\"bmr\": 0.2}, name=\"Example\")\n",
@@ -184,7 +185,7 @@
"source": [
"## Single dataset fit\n",
"\n",
- "With a single tumor dataset defined above, you can run a single multistage cancer model:"
+ "With a single tumor dataset defined above, you can run a single Multistage cancer model:"
]
},
{
@@ -259,12 +260,13 @@
"outputs": [],
"source": [
"model = MultistageCancer(\n",
- " dataset,\n",
- " settings = {\n",
- " \"bmr_type\": pybmds.DichotomousRiskType.AddedRisk,\n",
- " \"bmr\": 0.15,\n",
- " \"degree\": 3\n",
- "})\n",
+ " dataset, \n",
+ " settings={\n",
+ " \"bmr_type\": pybmds.DichotomousRiskType.AddedRisk, \n",
+ " \"bmr\": 0.15, \n",
+ " \"degree\": 3,\n",
+ " },\n",
+ ")\n",
"print(model.settings.tbl())"
]
},
@@ -301,7 +303,7 @@
"id": "e2bb7bfe-9b5e-4ee4-9357-822400cad69e",
"metadata": {},
"source": [
- "For multistage models, the `b2` parameter setting is reused for all beta parameters greater than or equal to b2.\n",
+ "For Multistage models, the `b2` parameter setting is reused for all beta parameters greater than or equal to b2.\n",
"\n",
"These can be updated:"
]
@@ -313,9 +315,9 @@
"metadata": {},
"outputs": [],
"source": [
- "model.settings.priors.update('g', initial_value=0, min_value=-10, max_value=10)\n",
- "model.settings.priors.update('b1', initial_value=10, min_value=0, max_value=100)\n",
- "model.settings.priors.update('b2', initial_value=20, min_value=0, max_value=1000)\n",
+ "model.settings.priors.update(\"g\", initial_value=0, min_value=-10, max_value=10)\n",
+ "model.settings.priors.update(\"b1\", initial_value=10, min_value=0, max_value=100)\n",
+ "model.settings.priors.update(\"b2\", initial_value=20, min_value=0, max_value=1000)\n",
"\n",
"print(model.priors_tbl())"
]
@@ -327,9 +329,7 @@
"source": [
"### Fit multiple models\n",
"\n",
- "The example above runs a single Multitumor model to a single dataset. You may want to run multiple multitumor models of varying degrees to a single dataset, for example. To do that, follow the \"Multiple dataset fit\" guide below, but just fit one dataset instead of multiple. \n",
- "\n",
- "This method for fitting multiple models to a single dataset is required because the model selection criteria for multiple models given a single dataset is only implemented in the Multitumor model below."
+ "The previous example runs a single Multitumor model to a single dataset. However, you may want, for example, to run multiple multitumor models of varying degrees to a single dataset. "
]
},
{
@@ -339,7 +339,7 @@
"source": [
"## Multiple dataset fit\n",
"\n",
- "To fit multiple models and and one or more datasets, use an instance of the Multitumor class:"
+ "To fit multiple models and one or more datasets, use an instance of the Multitumor class:"
]
},
{
@@ -357,15 +357,15 @@
" ns=[20, 20, 20, 20, 20],\n",
" incidences=[0, 1, 7, 15, 19],\n",
" name=\"Tumor A\",\n",
- " dose_units=\"mg/m³\"\n",
+ " dose_units=\"mg/m³\",\n",
" ),\n",
" pybmds.DichotomousDataset(\n",
" doses=[0, 25, 75, 125, 200],\n",
" ns=[20, 20, 20, 20, 20],\n",
" incidences=[0, 0, 1, 7, 11],\n",
" name=\"Tumor B\",\n",
- " dose_units=\"mg/m³\"\n",
- " )\n",
+ " dose_units=\"mg/m³\",\n",
+ " ),\n",
"]\n",
"\n",
"session = pybmds.Multitumor(datasets)\n",
@@ -416,13 +416,10 @@
"metadata": {},
"outputs": [],
"source": [
- "session = pybmds.Multitumor(\n",
- " datasets,\n",
- " settings = {\n",
- " \"bmr_type\": pybmds.DichotomousRiskType.AddedRisk,\n",
- " \"bmr\": 0.15\n",
- " }\n",
- ")"
+ "session = pybmds.Multitumor(datasets, settings={\n",
+ " \"bmr_type\": pybmds.DichotomousRiskType.AddedRisk, \n",
+ " \"bmr\": 0.15,\n",
+ "})"
]
},
{
@@ -456,22 +453,22 @@
" ns=[20, 20, 20, 20, 20, 20, 20, 20, 20],\n",
" incidences=[0, 1, 4, 8, 11, 12, 13, 14, 15],\n",
" name=\"Tumor A (9 groups)\",\n",
- " dose_units=\"mg/m³\"\n",
+ " dose_units=\"mg/m³\",\n",
" ),\n",
" pybmds.DichotomousDataset(\n",
" doses=[0, 2, 3, 4, 5, 6, 7, 8, 9],\n",
" ns=[20, 20, 20, 20, 20, 20, 20, 20, 20],\n",
" incidences=[0, 1, 7, 15, 19, 19, 19, 19, 19],\n",
" name=\"Tumor B (9 groups)\",\n",
- " dose_units=\"mg/m³\"\n",
+ " dose_units=\"mg/m³\",\n",
" ),\n",
" pybmds.DichotomousDataset(\n",
" doses=[0, 2, 3, 4, 5],\n",
" ns=[20, 20, 20, 20, 20],\n",
" incidences=[0, 0, 1, 7, 11],\n",
" name=\"Tumor C (5 groups)\",\n",
- " dose_units=\"mg/m³\"\n",
- " )\n",
+ " dose_units=\"mg/m³\",\n",
+ " ),\n",
"]"
]
},
@@ -490,7 +487,7 @@
"metadata": {},
"outputs": [],
"source": [
- "degrees=[0, 3, 2]\n",
+ "degrees = [0, 3, 2]\n",
"session = pybmds.Multitumor(datasets, degrees=degrees)\n",
"session.execute()\n",
"session.plot()"
diff --git a/docs/source/recipes/nested_dichotomous.ipynb b/docs/source/recipes/nested_dichotomous.ipynb
index ec029458..665f67e1 100644
--- a/docs/source/recipes/nested_dichotomous.ipynb
+++ b/docs/source/recipes/nested_dichotomous.ipynb
@@ -115,7 +115,7 @@
"source": [
"## Nested dichotomous dataset\n",
"\n",
- "Creating a nested dichotomous dataset requires a list of doses, litter ns, incidence, and litter covariates. All lists must have must have the same number of items, with the total items equal to the total number of litters.\n",
+ "Creating a nested dichotomous dataset requires a list of doses, litter Ns, incidence, and litter covariates. All lists must have the same number of items, with the total items equal to the total number of litters.\n",
"\n",
"You can also add optional attributes, such as `name`, `dose_name`, `dose_units`, `response_name`, `response_units`, etc."
]
@@ -167,7 +167,7 @@
"source": [
"## Single model fit\n",
"\n",
- "If you want to fit only one model to your dataset, you can fit the specific model to the dataset and print the results such as the BMD, BMDL, BMDU, p-value, AIC, etc.\n",
+ "If you want to fit only one model to your dataset, you can fit the specific model to the dataset and print the results, such as the BMD, BMDL, BMDU, p-value, AIC, etc.\n",
"\n",
"For example, to execute the Nested Logistic model:"
]
@@ -395,11 +395,11 @@
"id": "9a04b81f-88e4-4695-a4e5-7f04205364e0",
"metadata": {},
"source": [
- "### Select a best fitting model\n",
+ "### Select a best-fitting model\n",
"\n",
- "You may recommend a best fitting model based on a decision tree, but expert judgment is be required for model selection.\n",
+ "You may recommend a best fitting model based on a decision tree, but expert judgment is required for model selection.\n",
"\n",
- "You can select any model; in this example we can agree agree with the recommended model:"
+ "You can select any model; in this example, we agree with the recommended model:"
]
},
{
diff --git a/pyproject.toml b/pyproject.toml
index 8c79c5e5..a70a964f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -13,6 +13,7 @@ classifiers = [
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
+ "Programming Language :: Python :: 3.13",
"Topic :: Scientific/Engineering",
]
requires-python = ">=3.11"