# instructions.py
from dash import html, dcc
def build_instructions_layout() -> html.Div:
"""
~1-page Quick Start Guide layout for the Extraction Condition Comparison Tool.
Intended audience: analytical chemists & toxicologists.
"""
page_style = {
"fontFamily": "Arial, Helvetica, sans-serif",
"padding": "20px",
}
card_style = {
"maxWidth": "950px",
"margin": "0 auto",
"padding": "18px 22px",
"border": "1px solid #e5e5e5",
"borderRadius": "8px",
"boxShadow": "0 1px 4px rgba(0,0,0,0.06)",
"backgroundColor": "white",
"lineHeight": "1.45",
}
h1_style = {"margin": "0 0 10px 0", "fontSize": "28px"}
h2_style = {"margin": "18px 0 8px 0", "fontSize": "18px"}
p_style = {"margin": "8px 0", "color": "#333"}
small_style = {"margin": "6px 0", "color": "#555", "fontSize": "13px"}
ul_style = {"margin": "8px 0 8px 22px"}
li_style = {"marginBottom": "6px"}
callout_style = {
"marginTop": "10px",
"padding": "10px 12px",
"borderLeft": "4px solid #999",
"backgroundColor": "#fafafa",
"color": "#333",
"fontSize": "13.5px",
}
return html.Div(
style=page_style,
children=[
html.Div(
style=card_style,
children=[
html.H1("Quick Start Guide", style=h1_style),
html.P(
"Use this tool to compare predicted fractional release of boundary chemicals from a polymer "
"under two scenarios (Condition #1 vs Condition #2).",
style=p_style,
),
html.P(
["Return to the tool: ", dcc.Link("Main page", href="/")],
style=small_style,
),
html.H2("1) Choose polymer properties", style=h2_style),
html.P(
"Start in the “Polymer component” section. These inputs define the material and geometry used "
"in the transport calculations.",
style=p_style,
),
html.Ul(
style=ul_style,
children=[
html.Li([html.B("Matrix: "), "Select the polymer type (e.g., PP)."], style=li_style),
html.Li(
[
html.B("Tg (°C), Crystallinity (%), Density (g/cm³): "),
"Enter polymer properties (use best-available values; defaults are acceptable for screening).",
],
style=li_style,
),
html.Li(
[
html.B("Volume (cm³) and Surface area (cm²): "),
"Define the polymer amount and exposed area for the scenario being evaluated.",
],
style=li_style,
),
],
),
html.H2("2) Define Condition #1 and Condition #2", style=h2_style),
html.P(
"Each condition can represent either an extraction experiment (in vitro) or an in vivo exposure case.",
style=p_style,
),
html.Ul(
style=ul_style,
children=[
html.Li(
[
html.B("In vitro: "),
"Enables solvent and extraction settings (solvent, solvent volume, swelling ratio = final mass divided by initial mass, "
"extraction temperature, iterations). Use this to mimic or design extraction conditions.",
],
style=li_style,
),
html.Li(
[
html.B("In vivo (conservative): "),
"Screening-level release assumption (often higher predicted release).",
],
style=li_style,
),
html.Li(
[
html.B("In vivo (tissue): "),
"Accounts for tissue-limited behavior for a more constrained release estimate.",
],
style=li_style,
),
],
),
html.P(
"For all modes, set “Extraction time (h)” to match the scenario duration of interest.",
style=small_style,
),
html.H2("3) Monte Carlo samples", style=h2_style),
html.P(
"Set the number of samples under “Monte Carlo → Samples” (the default is typically fine).",
style=p_style,
),
html.Ul(
style=ul_style,
children=[
html.Li([html.B("500–2000"), " for routine comparisons"], style=li_style),
html.Li([html.B(">5000"), " for more stable uncertainty bounds (slower)"], style=li_style),
],
),
html.H2("4) Run and interpret results", style=h2_style),
html.P(
["Click ", html.B("Calculate"), ". The chart compares predicted fractional release by chemical (CASRN)."],
style=p_style,
),
html.Ul(
style=ul_style,
children=[
html.Li([html.B("Red bars: "), "Condition 1"], style=li_style),
html.Li([html.B("Blue bars: "), "Condition 2"], style=li_style),
html.Li(
[
html.B("Error bars: "),
"uncertainty bounds (interquartile range). Larger error bars indicate greater uncertainty.",
],
style=li_style,
),
html.Li(
[
html.B("Log-scale y-axis: "),
"equal vertical steps represent orders of magnitude differences.",
],
style=li_style,
),
],
),
# --- Revised section (replaces any convex-hull language) ---
html.Div(
style=callout_style,
children=[
html.B("How to interpret the chemical list"),
html.Br(),
"The CASRNs shown are a representative boundary set selected to span the range of molecular "
"weight and hydrophobicity (logP) expected in a chemical characterization study. "
"Because this set covers the anticipated chemical space, tool-supported conclusions "
"(e.g., which condition is more/less conservative) are intended to be applicable broadly to "
"chemicals expected in that study context.",
],
),
html.H2("Common tips & troubleshooting", style=h2_style),
html.Ul(
style=ul_style,
children=[
html.Li(
"For test articles with multiple components comprised of different polymers, the "
"tool should be run separately for each component.",
style=li_style,
),
html.Li(
"If in vitro fields appear disabled, ensure the condition mode is set to “In vitro”.",
style=li_style,
),
html.Li(
"If results look unexpected, double-check units (cm³, cm², °C, hours) and polymer geometry inputs.",
style=li_style,
),
html.Li(
"For screening, focus on relative differences between Condition 1 and 2 rather than absolute values.",
style=li_style,
),
html.Li(
"If you need a defensible justification, document the polymer geometry, exposure duration, and "
"the rationale for choosing in vitro vs in vivo modes.",
style=li_style,
),
],
),
html.Hr(style={"margin": "16px 0"}),
html.P(
"Note: Outputs are model-based predictions intended to support comparisons and study design. "
"Interpret results alongside analytical data, scenario context, and uncertainty considerations.",
style=small_style,
),
],
)
],
)