Sufficient-component cause (SCC) models consist of component causes, which are grouped to sufficient causes. Sufficient causes are minimally sufficient for the outcome of interest to occur, i.e., if only one of the component causes included is missing, the outcome does not occur (at least not via this sufficient cause).
The main modeling task when creating SCC models is therefore to specify, which component causes belong into the same sufficient cause. Since SCC models are causal models, these specifications need to be based on knowledge regarding the mechanisms of outcome occurrence and not statistical knowledge, i.e., based on the mechanisms of outcome occurrence it needs to be specified how component causes are connected with each other and with the outcome.
Because sufficient causes are minimally sufficient, it is necessary
to also describe minimally sufficient mechanisms that connect them. For
this reason, the complex net of mechanisms leading to outcome occurrence
needs to be split into small parts. These small parts are called
steps in epicmodel. Component causes are
linked with each other and the outcome of interest by
chaining these steps together.
Steps have a pre-defined structure to facilitate
chaining. The developed structure tries to strike the balance between
flexible and user-friendly step specification and automated SCC model
creation. The structure used in epicmodel is basically an
IF-THEN structure. Steps consists of 3 parts:
THEN statements are the core building block of steps. They describe what happens, e.g., Cell A releases cytokine B, Exposure to C, D moves to E, etc. In order to facilitate chaining of steps, THEN statements also follow a pre-defined structure. This makes it possible to automatically create ID and description for THEN statements. IDs are then used for chaining. As steps are built from THEN statements, this structure also enables automated creation of step IDs and descriptions.
THEN statements contain up to 4 segments:
THEN statements follow a WHAT DOES WHAT WHERE structure
and therefore generally consist of WHAT, DOES, and WHERE
segments. WHAT segments can appear twice: the first is called
“subject”, the second is called
“object”. Here you can see how the examples above fit
into the WHAT DOES WHAT WHERE structure:
Cell A releases cytokine B
Exposure to C
D moves to E
Some DOES segments require the object to be a THEN
statement instead of a WHAT segment. Imagine, e.g., the DOES
segment “inhibition”. In general, inhibition can be modeled by
specifying IFNOT conditions (see below). However, if inhibition only
occurs under certain condition, it might need to be specified as its own
step. Since only a certain process, i.e., a specific step is inhibited,
the object in these cases needs to be this exact step. There might be
other DOES segments, for which THEN objects are necessary. The option to
use THEN objects offers more flexibility to model the mechanisms found
in Nature within the WHAT DOES WHAT WHERE structure. Note
that a certain DOES segment either has WHAT or THEN objects in all its
steps. Please also note that THEN objects can be “stacked” by including
as object a THEN statement that already has a THEN object. In general,
WHAT object should be far more prevalent though. (That’s why we
generally refer to the structure as WHAT DOES WHAT WHERE
structure.)
A THEN statement can contain up to 4 segments, but it does
not have to. In general, all combinations of segments are
possible and you, the modeler, need to decide how to model the process
of interest. The WHAT DOES WHAT WHERE structure is supposed
to facilitate automation of naming and SCC creation, but also grant as
much flexibility as needed to model all necessary processes. Remember
that the goal is to connect component causes with each other and the
outcome of interest in order to enable grouping of component causes to
sufficient causes. The structure is designed with this goal in mind. So
far, in our projects, we were able to model all processes within this
structure, but if you encounter something you cannot model, let us know
on GitHub and we adjust the structure accordingly. Please also note
that, although all segment combinations are possible in theory, only
DOES, only WHERE, and WHAT-WHAT, in our experience, do not make much
sense.
IF and IFNOT describe the conditions for the THEN statement to occur. The IF condition must be fulfilled in order for the THEN statement to occur. The IFNOT condition must not be fulfilled in order for the THEN statement to occur. IF and IFNOT themselves are a combination of THEN statements combined with AND/OR logic. By using THEN statements in IF and IFNOT conditions, the individual step can be chained together.
When creating a step, specification of the THEN statement is
mandatory while IF and IFNOT conditions are optional. If the IF
condition is missing, there is no pre-condition and the THEN statement
“just happens”. Therefore, this type of steps are “starting
steps” and their description begins with Start:.
They form the start of the chains that connect the component causes and
the outcome of interest. In our context, “starting steps” usually
represent component causes. In reality, component causes are, of course,
caused by other factors not otherwise involved in causing the outcome,
e.g., an occupational exposure that causes occupational asthma is caused
by socio-economic factors that influence job choice. But in the context
of SCC model creation when our task is to group the component causes to
sufficient causes, component causes are the starting point and therefore
represented by steps without IF condition. However, please note that
component causes can have IFNOT conditions.
Here are the step descriptions from the built-in steplist
steplist_rain as an example:
There are, as mentioned, different types of steps that play different roles during SCC model creation:
Based on the presence of an IF condition, we define:
Starting steps can also be separated into two types:
Therefore, component causes, interventions, and non-starting steps are mutually exclusive and together form the complete list of steps.
In addition, we define:
The steplist is the structure that contains all specified steps. It
is the only input for function create_scc(), which creates
the SCC model. See ?new_steplist for a detailed description
of the structure of steplists from a R perspective.
Steps contain additional attributes:
In R, steplists are defined as S3 class and contain 8 data.frames.
Here’s a short overview, but also see ?new_steplist for
details.
incompatible component causes and
records combinations of component causes, which cannot appear in
practice. Sets of component causes which contain ICCs are not considered
during SCC model creation.outcome definition, which is a list of
conditions under which the outcome is assumed to have occurred. In
practice, the outcome definition consists of end steps combined by
AND/OR logic.Steplists are created with the built-in Steplist Creator
Shiny App. It can be launched with:
We made a little tutorial that shows how to use the
shiny app, see
vignette("articles/steplist_creator_tutorial"). It contains
screenshots and an example for you to click along. Please note that the
tutorial is not shipped with the package and can only be accessed on the
homepage.
The steplist created in the shiny app can be downloaded
as .rds file and loaded into R using
readRDS(). Additionally, there are some options to process
the steplist in R, as it might be easier for some standard tasks instead
of clicking through the app. These functions accompany
check_steplist(), so let’s talk about this function
first.
A steplist needs to fulfill additional structural requirements in
order to be used in create_scc(). These requirements are
checked with check_steplist(). The function documentation
contains a detailed description of conducted checks. Some violation will
result in errors, which means that checking was not successful and you
need to make changes. Other violations will only result in warnings,
which suggest some non-mandatory changes. If
check_steplist() only results in warnings, you will still
get a checked steplist. Let’s look at the built-in
steplist_party as an example.
Now, let’s run check_steplist().
steplist_checked <- check_steplist(steplist)
#> ── Checking epicmodel_steplist steplist ──────────────────────────────────────────────────────────────────────────────────────────────────────────
#> ✔ Checking WHAT IDs was successful.
#> ✔ Checking DOES IDs was successful.
#> ✔ Checking WHERE IDs was successful.
#> ✔ Checking Module IDs was successful.
#> ✔ Checking ICC IDs was successful.
#> ✔ Checking WHAT keywords was successful.
#> ✔ Checking DOES keywords was successful.
#> ✔ Checking WHERE keywords was successful.
#> ✔ Checking Module keywords was successful.
#> ✔ Checking Modules was successful.
#> ✖ Checking ICC entries failed!
#> Caused by error in `check_steps_in_icc()`:
#> ! All IDs in data.frame `icc`, i.e. in variables `id1` and `id2`, must be in `id_step` of data.frame `step`!
#> ℹ Data.frame `icc` contains 4 elements with two step IDs each.
#> ✖ In total, 1 ID is not in data.frame `step`: NA
#> ℹ If only `NA` is not in data.frame `step`, use `steplist <- remove_na(steplist)`.
#> ✔ Checking WHAT segments was successful.
#> ! Checking DOES segments resulted in warnings!
#> Caused by warning:
#> ! Not all DOES segments have been used in data.frame `step`!
#> ℹ Data.frame `does` contains 6 elements.
#> ℹ In total, 1 DOES segment is not being used in data.frame `step`: d4
#> ✔ Checking WHERE segments was successful.
#> ! Checking references resulted in warnings!
#> Caused by warning:
#> ! For some steps no references have been provided!
#> ℹ In total, 16 steps have no references.
#> ✔ Checking start/end steps was successful.
#> ✔ Checking THEN statements was successful.
#> ✔ Checking THEN/IF/IFNOT equality was successful.
#> ✔ Checking outcome definitions was successful.
#> ── Summary ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> ✖ Checking failed! Please correct errors and repeat.You can see that many checks have been successful but also that some
of them resulted in errors or warnings. The first error tells you that
“Checking ICC entries failed!”. As a reminder, ICC is short for
incompatible component causes and it tells you that in the
ICC data.frame of the steplist, you used step IDs that have
not been defined, i.e., cannot be found in data.frame step
of the steplist. It gives more details: “In total, 1 ID is not in
data.frame step: NA”. This clarifies a lot: There is still
an entry in the table that contains NA, which is counted as an empty
element. Luckily, in this case, it offers a solution: using
remove_na(). Next, we have the warning “Not all DOES
segments have been used in data.frame step!” As it tells us
two lines below, we specified d4 in data.frame
does but did not use it when creating steps. Even though
this won’t break SCC model creation, let’s also address it. Finally,
check_steplist() warns us that “For some steps no
references have been provided!”. Because steps are usually based on the
literature, epicmodel will not get tired of telling you to
specify references in the steplist! In summary, checking failed, which
we can verify by printing steplist_checked.
print(steplist_checked)
#> ✖ unchecked (please run `check_steplist()` before continuing)
#> WHAT: 9 WHAT segments
#> DOES: 6 DOES segments
#> WHERE: 6 WHERE segments
#> MODULE: 3 modules
#> STEP: 16 STEPs
#> ICC: 4 incompatible component-cause pairs
#> OUTCOME: 1 outcome definitionThe first line shows us that steplist_checked is still
“unchecked”. So, let’s work on those errors and warnings. First, to
remove the NAs from data.frame icc, let’s run
remove_na(). It removes rows that only consist of NAs from
data.frames icc as well as outc, which
contains the outcome definition. Next, we can delete DOES segment
d4 with function remove_segment(), which
allows you to delete a single entry from data.frames what,
does, where, module, and
icc by specifying its ID.
This time, check_steplist() is successful. Since our
example is about a party, we ignore the warning about references.
steplist_checked <- check_steplist(steplist)
# ── Checking epicmodel_steplist steplist ───────────────────────────────────────────────────────────────────────────────────────────────────────────
# ✔ Checking WHAT IDs was successful.
# ✔ Checking DOES IDs was successful.
# ✔ Checking WHERE IDs was successful.
# ✔ Checking Module IDs was successful.
# ✔ Checking ICC IDs was successful.
# ✔ Checking WHAT keywords was successful.
# ✔ Checking DOES keywords was successful.
# ✔ Checking WHERE keywords was successful.
# ✔ Checking Module keywords was successful.
# ✔ Checking Modules was successful.
# ✔ Checking ICC entries was successful.
# ✔ Checking WHAT segments was successful.
# ✔ Checking DOES segments was successful.
# ✔ Checking WHERE segments was successful.
# ! Checking references resulted in warnings!
# Caused by warning:
# ! For some steps no references have been provided!
# ℹ In total, 16 steps have no references.
# ✔ Checking start/end steps was successful.
# ✔ Checking THEN statements was successful.
# ✔ Checking THEN/IF/IFNOT equality was successful.
# ✔ Checking outcome definitions was successful.
# ── Summary ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
# ✔ Checking successful!Printing steplist_checked confirms that checking was
successful.
print(steplist_checked)
#> ✔ checked successfully
#> WHAT: 9 WHAT segments
#> DOES: 5 DOES segments
#> WHERE: 6 WHERE segments
#> MODULE: 3 modules
#> STEP: 16 STEPs
#> ICC: 3 incompatible component-cause pairs
#> OUTCOME: 1 outcome definitionThere is another function available for processing steplists in R.
It’s called remove_all_modules() and, as the name implies,
it removes all modules from data.frame module and deletes
assigned modules in data.frame step. epicmodel
expects that either all steps or none of them have a module specified.
With remove_all_modules(), you have an easy tool for
choosing the second option.
steplist_checked <- remove_all_modules(steplist_checked)
#> ! Changing the steplist makes it necessary to repeat `check_steplist()`!We already get a warning that we need to repeat
check_steplist(). Let’s print steplist_checked
to investigate.
print(steplist_checked)
#> ✖ unchecked (please run `check_steplist()` before continuing)
#> WHAT: 9 WHAT segments
#> DOES: 5 DOES segments
#> WHERE: 6 WHERE segments
#> MODULE: 0 modules
#> STEP: 16 STEPs
#> ICC: 3 incompatible component-cause pairs
#> OUTCOME: 1 outcome definitionIndeed, we see that steplist_checked has 0 modules now
but is “unchecked” again. In fact, remove_na() and
remove_segment() also “uncheck” a previously checked
steplist. Additionally, all steplists you download from the
shiny app are “unchecked” as well, even if you uploaded a
“checked” steplist.