How-to: Modeling Dichotomous Data in BMDS Online

For users new to BMDS Online, the following sections walk through the basics of creating and sharing an online analysis using dichotomous data. The steps also include tips on how to use BMDS Online effectively.

On this page:

Creating a New Analysis
- Analyses and URLs
Configuring and Executing an Analysis
Analysis Downloading and Sharing

Creating a New Analysis

Navigate to the BMDS Online website.
Select the Create a new BMDS analysis button (Figure 1).

BMDS Online landing page, with create analysis button highlighted — Figure 1: BMDS Online landing page, with **Create a new BMDS analysis** button

BMDS Online displays a new, empty analysis page with the Settings tab selected (Figure 2). From here, you can configure an analysis, load a dataset, execute the analysis, and select results. Each BMDS Online analysis is self-contained; it includes all of the inputs and outputs for the executed analysis.

New BMDS Online analysis on Settings tab — Figure 2: A new BMDS Online analysis on the Settings tab

Analyses and URLs

When a new analysis is created, a unique URL is created for the analysis that can be shared with others (Figure 3).

BMDS Online analysis URL highlighted — Figure 3: A new BMDS Online analysis has a unique URL.

You can create as many analyses as you want, but only the most recent execution is saved with an analysis. If you edit the data or add new data or new options, then the resulting analysis will overwrite the previous analysis.

Therefore, if you want to analyze multiple sets of data, create a new analysis instead of overwriting an existing analysis.

Configuring and Executing an Analysis

Steps Required to Run the Analysis

BMDS Online tracks the steps required to run an analysis (Figure 4). For a new analysis, the green checkmarks show that the default set of models and options have been selected for the analysis. Red x’s show that, currently, no dataset has been selected and the analysis has not been saved.

BMDS Online analysis steps marked with red and green checkmarks — Figure 4: When all checkmarks are green, BMDS Online can run an analysis

Specifying an Analysis

On the Settings tab, specify a name and description for the analysis (Figure 5).

Figure 5: Enter a descriptive name and summary of the analysis; they will be included in the report.
Select the model type for your analysis (i.e., are you modeling dichotomous or continuous data?) (Figure 6). For this example, the dichotomous model type has been selected.
Note: An analysis can only be composed of a single model type; you cannot mix continuous and dichotomous data in single analysis. Instead, create two analyses.

Figure 6: Endpoint types available for analysis in BMDS Online
Select which models will be used for the analysis. For this example, the default selection of dichotomous maximum-likelihood estimation (MLE) models will be used, plus all of the Bayesian dichotomous model averaging models. To use all the models in a column, check the Select All box (Figure 7).

Figure 7: Tick the Select All box to select all the models in a column.
Select which option sets will be used for the analysis (up to 3-6, depending on endpoint type). For this example, we will create a single option set with the default benchmark response (BMR) of 10% extra risk.

You can add/delete option sets by clicking the blue plus or red trash can icons, respectively, to the right of the option set window (Figure 8).

Figure 8: Select the blue plus icon to add a row for a new option set. Select the red trash can icon to delete the row.

Maximum Number of Option Sets

BMDS Online: A maximum of six option sets (for continuous, dichotomous, and nested dichotomous) and up to three option sets (for multitumor).
BMDS Desktop: No limit essentially; but it is recommended to create multiple analyses.
pybmds: No limit.

Specifying Datasets

A BMDS Online analysis can have up to a maximum of six datasets (for continuous, dichotomous, and nested dichotomous) or 10 datasets (for multitumor). For BMDS Desktop/pybmds, there is essentially no limit, but it is recommended to create multiple analyses instead of putting large numbers of datasets into a single analysis.

To add a dataset, click the Data tab to the top right of the screen (Figure 9).

Figure 9: Select the Data tab to start specifying datasets.
On the data tab, click the New button to add an individual dataset (Figure 10). BMDS Online can model dichotomous data (e.g., lesion incidence), summarized continuous data (e.g., data measured on a continuous scale and presented as means and standard deviations), and individual continuous data (data measured on a continuous scale presented as dose and response data for each test subject).

For this analysis, only the dichotomous option is shown for New dataset because dichotomous was chosen as the model type on the Settings tab.

Figure 10: The New button creates a new empty dataset.
After a new empty dataset has been added, you can specify the dataset name, dose name and units, and response name and units. BMDS Online will use this information to identify the dataset in results and reports.

For this example, the incidence of hepatocellular hyperplasia will be modeled with dose units of mg/kg-day, as noted in Figure 11.

Figure 11: Data tab with empty dataset, empty graph, and details about the dataset to be analyzed.
You can add datasets to BMDS Online in two ways:
1. Manually enter dose, N, and Incidence data by typing the data into the table. BMDS Online automatically adds five rows of data when adding new datasets. New rows can be added by clicking the blue plus icon; unneeded rows can be deleted by clicking the red trash can icon (Figure 12).
  
  Figure 12: Select the blue plus icon to add five rows at a time; select the red trash can icon to delete that row.
2. Paste data directly from Excel into the table.
  1. Enter the data in Excel.
  2. Select and copy the Excel cells (numbers only; do not include column titles or header text) (Figure 13).
    
    Figure 13: Select and copy the data from Excel.
  3. In BMDS Online, select the teal Excel icon in the dataset table header (Figure 14a). A Paste from Excel window displays.
    
    Figure 14a: Select the Paste from Excel button (right).
    
    Click the mouse inside the Paste from Excel window's text box, paste the data, and select the Load icon (Figure 14b). The dataset is then fully entered in BMDS Online.
    
    Figure 14b: After pasting in the data from Excel, select Load to enter the data into BMDS Online.

Note that the plot to the right of the dataset table updates as data is entered (Figure 15).

Dataset table with loaded data and updated plot to the right — Figure 15: The plots to the right update as data is entered into the dataset.

Executing an Analysis and Viewing Results

After all datasets are loaded, return to the Settings tab to run the analysis (Figure 16).

Figure 16: Select Settings after specifying the dataset.
On the Settings tab, a green checkmark now appears next to At least one dataset is selected (Figure 17).

Figure 17: With at least one dataset selected, another analysis requirement is satisfied.
For dichotomous data, BMDS Online automatically selects the Maximum multistage degree to be 3. However, you may manually select a range of options from the drop-down menu (Figure 18). For this analysis, the default setting is used.

Figure 18: You can select the maximum multistage degree, or accept the default of 3. Hover the mouse over the question mark icon for help text on this setting.
Select the Save Analysis button to complete all the steps required to run analysis button. Notice that all steps now have a green checkmark next to them (Figure 19).

Figure 19: Selecting Save Analysis ensures all specifications are in place for an analysis.
Select the Run Analysis button to execute the analysis. A running analysis can be stopped by selecting the Cancel execution button (Figure 20).

Figure 20: Select Cancel execution to stop a running analysis.
After successful execution, the modeling results are displayed on the Output tab (Figure 21).

Figure 21: The Output tab is a large scrolling page showing results based on the analysis specifications.
1. Numerical results are displayed in a summary table for all models. Select the Show icon in the Recommendation and Notes column header to display a full set of model notes and warnings (Figure 22). Select the Hide icon to hide the model notes (Figure 23).
  
  Figure 22: Click the Show button to display any model warnings and messages.
  
  Figure 23: Select Hide to stop showing model notes and warnings.
2. As users hover the cursor over rows within the Model Results table, individual model curves will display in the plot to the right (Figure 24).
  
  Figure 24: Hovering the cursor over a model row displays that model's plot.
3. To investigate an individual model's results, select that model's name in the Model column. Doing so will display a window showing all of the numerical and graphical model outputs for that model (Figure 25).
  
  Figure 25: Results window displayed for the selected model.
For the maximum likelihood estimate (MLE) models, BMDS Online applies a set of model selection logic criteria to recommend a best fitting model (the blue row in Figure 24). The logic criteria used to make the recommendations are located on the Logic tab (Figure 26).

Figure 26: The Logic tab contains the rules BMDS Online uses to make model recommendations. It is highly recommended to leave the settings as-is.
1. On the Logic tab, you can investigate the criteria BMDS Online used to recommend the best fitting model. Users can change any of the criteria for model selection based on the needs of their analysis or to comport with the modeling guidance of their organizations. However, it is highly recommended that new users leave the logic settings as-is; logic settings should only be changed under the guidance of experienced modelers. For more information, refer to the BMDS User Guide chapter on "Model Recommendations and Decision Logic."
2. If any logic setting changes, the default logic settings can be reapplied by selecting the Reset to Default Logic button
3. If any logic setting changes, that change and the reasons for it should be documented in the Selection notes textbox.
After you have confirmed the recommended model, or selected an alternative one, you can choose that model from the Selected best-fitting model picklist (Figure 27).

Figure 27: The Selected best-fitting model picklist, with the Multistage 3 model selected.
1. Enter notes on model selection in the Selection notes window (Figure 28).
  
  Figure 28: Use the Selection notes box to record the reasons why a specific model was selected.
2. Use the Save model selection button to finalize model selection. BMDS Online displays the selected model row in green, and any selection notes will be displayed in a footnote at the bottom of the table (Figure 29).
  
  Figure 29: The final output table, with the recommended row in blue, the user-selected row in green, and footnotes following.
Individual model and model averaging results can also be investigated by clicking on the desired row in the results table. In Figure 30, the Model Average link was selected to display the Model Average results graph. Hover the mouse across the curves to investigate results in more detail.

Figure 30: Selecting the Model Average link from the Bayesian Model Results table displays the Model Average results window. Hover the cursor over the results curves to display more details.

Analysis Downloading and Sharing

After an analysis has been configured and successfully executed, it can be downloaded or shared with others. The Share and Actions menus in the top-right corner of the analysis page include options for other ways to interact with the analysis.

Actions Menu

Load analysis: Load a previously downloaded analysis (using the Download analysis option described below).
Extend deletion date: BMDS Online will store analyses for three years after the date of creation. Select Extend deletion date to extend deletion to three years from the time this button was clicked.
Delete analysis: Delete the current analysis. If an analysis is deleted, it cannot be restored.
Download data: Download the analysis as an Excel file. By default, the user-specified Analysis Name is the Excel filename; the user can change the filename before saving. The Excel file contains all the datasets, their option settings, and their analysis results.
Download report: Download the analysis results as a Word file. Options for the Word report can include only the user-selected model, all models, and all models with the BMD Cumulative Data Function (CDF) table. Note that the Word report contains the analysis URL, and users can access their analyses via the generated report. The name given to the Word file is the user-specified Analysis Name. (The BMDS Desktop/pybmds report does not include URLs because the analysis resides on the user’s local system rather than the internet.)
Download analysis: Download the analysis as a JSON file. This is a machine-readable file format that can be saved or shared, and then uploaded into BMDS Online via Load analysis. The name given to the JSON file is the user-specified Analysis Name.

Share Menu

Read-only links: users can share read-only links so collaborators can view the current analysis and download reports but cannot edit or execute the analysis.
Edit link: users can share links to collaborators so collaborators can edit the analysis settings, change input data, and re-execute the analysis.
.

Only the Most Recent Analysis is Available

Note: When a link is shared, only the most recent execution of an analysis is preserved and would be available to others. Therefore, we recommend creating a new analysis whenever you want to perform a different analysis after sharing an analysis link.