forestplot

To create a forest plot, provide a pandas DataFrame containing your study results. The core workflow involves loading or preparing your data and then calling fp.forestplot() with specific column mappings.

Basic Usage Example

import forestplot as fp
import matplotlib.pyplot as plt

# Load example data
df = fp.load_data("sleep")

# Generate the forest plot
fp.forestplot(
    df, 
    estimate="r",      # Column containing estimated effect size 
    ll="ll",          # Column containing confidence interval lower limits
    hl="hl",          # Column containing confidence interval higher limits
    varlabel="label", # Column containing variable labels
    ylabel="Confidence interval",
    xlabel="Pearson correlation"
)

# Save the plot using matplotlib
plt.savefig("plot.png", bbox_inches="tight")

import forestplot as fp

df = fp.load_data("sleep")  # companion example data
df.head(3)

fp.forestplot(df,  # the dataframe with results data
              estimate="r",  # col containing estimated effect size 
              ll="ll", hl="hl",  # columns containing conf. int. lower and higher limits
              varlabel="label",  # column containing variable label
              ylabel="Confidence interval",  # y-label title
              xlabel="Pearson correlation",  # x-label title
              )

You can transform the forest plot into a table format by setting table=True. This allows you to include detailed annotations on both the left and right sides of the plot.

• annote: List of columns to report on the left of the plot.
• annoteheaders: Corresponding headers for the left annotations.
• rightannote: List of columns to report on the right of the plot.
• right_annoteheaders: Corresponding headers for the right annotations.

fp.forestplot(df,  # the dataframe with results data
              estimate="r",  # col containing estimated effect size 
              ll="ll", hl="hl",  # lower & higher limits of conf. int.
              varlabel="label",  # column containing the varlabels to be printed on far left
              capitalize="capitalize",  # Capitalize labels
              pval="p-val",  # column containing p-values to be formatted
              annote=["n", "power", "est_ci"],  # columns to report on left of plot
              annoteheaders=["N", "Power", "Est. (95% Conf. Int.)"],  # ^corresponding headers
              rightannote=["formatted_pval", "group"],  # columns to report on right of plot 
              right_annoteheaders=["P-value", "Variable group"],  # ^corresponding headers
              xlabel="Pearson correlation coefficient",  # x-label title
              table=True,  # Format as a table
              )

When each variable has multiple estimates (e.g., from different models), use mforestplot. This function allows you to compare models side-by-side.

Key parameters:

• model_col: The column identifying the model.
• modellabels: Labels for the different models.
• mcolor: A list of colors to assign to each model.
• offset: Controls the vertical offset between models (0.0 to 1.0).

Note: This module is currently experimental.

fp.mforestplot(
    dataframe=df_mmodel,
    estimate="coef",
    ll="ll",
    hl="hl",
    varlabel="label",
    capitalize="capitalize",
    model_col="model",
    color_alt_rows=True,
    groupvar="group",
    table=True,
    rightannote=["var", "group"],
    right_annoteheaders=["Source", "Group"],
    xlabel="Coefficient (95% CI)",
    modellabels=["Have young kids", "Full sample"],
    xticks=[-1200, -600, 0, 600],
    mcolor=["#CC6677", "#4477AA"],
    # Additional kwargs for customizations
    **{
        "markersize": 30,
        # override default vertical offset between models (0.0 to 1.0)
        "offset": 0.35,  
        "xlinestyle": (0, (10, 5)),  # long dash for x-reference line
        "xlinecolor": ".8",  # gray color for x-reference line
    },
)

You can organize your forest plot by adding variable groupings and controlling their order. Using groupvar specifies the column containing group labels, and group_order allows you to define the specific sequence of those groups. Additionally, setting sort=True will sort the estimates in ascending order within each group.

fp.forestplot(df,  # the dataframe with results data
              estimate="r",  # col containing estimated effect size 
              ll="ll", hl="hl",  # columns containing conf. int. lower and higher limits              
              varlabel="label",  # column containing variable label
              capitalize="capitalize",  # Capitalize labels
              groupvar="group",  # Add variable groupings 
              # group ordering
              group_order=["labor factors", "occupation", "age", "health factors", 
                           "family factors", "area of residence", "other factors"],
              sort=True  # sort in ascending order (sorts within group if group is specified)               
              )

To enhance readability, you can display p-values on the right side of the plot and apply gray shading to alternate rows. Use pval to specify the column containing p-values and color_alt_rows=True to enable shading. You can also customize the y-axis label using ylabel and control its size via keyword arguments like ylabel1_size.

fp.forestplot(df,  # the dataframe with results data
              estimate="r",  # col containing estimated effect size 
              ll="ll", hl="hl",  # columns containing conf. int. lower and higher limits
              varlabel="label",  # column containing variable label
              capitalize="capitalize",  # Capitalize labels
              groupvar="group",  # Add variable groupings 
              # group ordering
              group_order=["labor factors", "occupation", "age", "health factors", 
                           "family factors", "area of residence", "other factors"],
              sort=True,  # sort in ascending order (sorts within group if group is specified)               
              pval="p-val",  # Column of p-value to be reported on right
              color_alt_rows=True,  # Gray alternate rows
              ylabel="Est.(95% Conf. Int.)",  # ylabel to print
              **{"ylabel1_size": 11}  # control size of printed ylabel
              )