j1-template 2022.5.0.rc1 → 2022.5.0.rc4

data/lib/starter_web/pages/public/_jupyter/docs/nbinteract-widget-manual.adoc

@@ -0,0 +1,928 @@
+---
+title:                                  J1 NBI
+tagline:                                nbinteract widgets
+date:                                   2022-03-28 00:00:00
+description: >
+                                        The package nbinteract aims to enable authors and educators to create and
+                                        share interactive web pages easily. Interactive explanations of concepts are
+                                        useful for communicating and explaining tricky concepts.
+keywords: >
+                                        opensource, free, load, download, start, starter, example,
+                                        high, easy, use, secure, encrypt, standard, popular,
+                                        generate, create, learn, distribute, publish, deploy,
+                                        beginner, advanced, expert, student, learner, educator,
+                                        writer, reader, visitor,
+                                        framework, toolkit, integration, extension, module, api,
+                                        dynamic, static, generator, client, server, internet, local, localhost,
+                                        page, web, website, webdesign, material, design, responsive,
+                                        javascript, nodejs, ruby, windows, linux, osx, mac, os,
+                                        http, https, html, html5, css, scss, style,
+                                        browser, firefox, chrome, edge, opera, safari,
+                                        configuration, generator, navigation, menu, dropdown, fab, action, button,
+                                        application, interface, provider, api, repository,
+                                        cookie, language, translation, gdpr, dsgvo, privacy,
+                                        asciidoc, aciidoctor, bootstrap, jekyll, liquid,
+                                        hyvor, disqus, git, github, netlify, heroku, apple, microsoft,
+                                        provider, service, internet, support,
+                                        google, analytics, advertising, search, console, silverlight, score,
+                                        j1, nbi, j1-nbinteract, nbinteract, template, integration,
+                                        python, jupyter, notebook, textbook, api, app,
+                                        binder, binderhub, jupyterhub
+
+categories:                             [ Software, Python ]
+tags:                                   [ Binder, API ]
+
+scrollbar:                              false
+
+permalink:                              /pages/public/jupyter/docs/nbi-widgets/
+regenerate:                             false
+
+resources:                              [ animate, clipboard, lightbox, rouge ]
+resource_options:
+  - attic:
+      slides:
+        - url:                          /assets/images/modules/attics/yellow-cactus-1920x1280.jpg
+          alt:                          Photo by Yellow Cactus on Unsplash
+          badge:
+            type:                       unsplash
+            author:                     Yellow Cactus
+            href:                       https://unsplash.com/@yellowcactus
+---
+
+// Page Initializer
+// =============================================================================
+// Enable the Liquid Preprocessor
+:page-liquid:
+
+// Set (local) page attributes here
+// -----------------------------------------------------------------------------
+// :page--attr:                         <attr-value>
+:badges-enabled:                        false
+:binder-badges-enabled:                 false
+:binder--home:                          https://mybinder.org/
+:binder--docs:                          https://mybinder.readthedocs.io/en/latest/
+:binder-app-launch--tree:               https://mybinder.org/v2/gh/jekyll-one/j1-binder-repo/main?urlpath=/tree
+:binder-app-launch--lab:                https://mybinder.org/v2/gh/jekyll-one/j1-binder-repo/main
+
+//  Load Liquid procedures
+// -----------------------------------------------------------------------------
+{% capture load_attributes %}themes/{{site.template.name}}/procedures/global/attributes_loader.proc{%endcapture%}
+
+// Load page attributes
+// -----------------------------------------------------------------------------
+{% include {{load_attributes}} scope="all" %}
+
+
+// Page content
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ifeval::[{binder-badges-enabled} == true]
+image:/assets/images/badges/myBinder.png[[Binder, link="{binder--home}", {browser-window--new}]
+image:/assets/images/badges/docsBinder.png[[Binder, link="{binder--docs}", {browser-window--new}]
+endif::[]
+
+
+// Include sub-documents (if any)
+// -----------------------------------------------------------------------------
+
+The package at Github link:{url-j1-repo--j1-nbinteract}[j1-nbinteract, {browser-window--new}]
+aims to enable authors and educators to create and share interactive web pages
+easily. Interactive explanations of concepts are useful for communicating and
+explaining complex concepts better. The package *j1-nbinteract* comes with a
+set of backend functions that produce Javascript-based plots designed for
+interaction. The package combines the _ipywidgets_ library and the _bqplot_
+plotting library to implement function-driven interfaces for interactive
+plotting.
+
+CAUTION: The current version of j1-nbinteract *1.x* is limited to Notebook v6
+(Classic Notebook). The latest version Jupyter Notebook v7 (JupyterLab) are
+supported by upcoming versions of j1-nbinteract *2.x*.
+
+The j1-nbinteract plotting methods use _ipywidgets_ to generate and display
+widgets, inferring the widget type automatically as needed. When a user
+interacts with a widget, a Python callback updates the visualization *without*
+a complete rerender. This noticeably lowers visualization update time compared
+to using ipywidgets for other plotting libraries that render *static images*.
+
+== Histogram
+
+The widget `nbinteract.hist` generates an interactive histogram that allows
+users to change the parameters of the input hist_function.
+
+=== Example
+
+[source, python, role="noclip"]
+----
+def hist_function(mean, sd, size=1000):
+    '''
+    Returns 1000 values picked at random from the normal
+    distribution with the Mean value and SD given.
+    '''
+    return np.random.normal(loc=mean, scale=sd, size=1000)
+
+
+options = {
+    'title': 'Histogram',
+    'xlabel': 'Mean value (mean)',
+    'ylabel': 'Standard Deviation (sd)',
+    'bins': 10
+}
+
+layouts = {
+    'plot_height': '480px',
+    'plot_width': '800px',
+}
+
+hist_chart = nbi.hist(
+    hist_function,
+    mean=(0, 10),
+    sd=(0.2, 2.0, 0.2),
+    options=options,
+    layouts=layouts
+)
+
+hist_chart
+----
+
+=== Rendered Histogram
+
+lightbox::nbi-widget--hist[1280, {image-nbi-widget--hist}, role="mt-3 mb-4"]
+
+TIP: Find an live example on page:
+link:{url-nbinteract-common-widget--histogram}[Common used widgets -- Histogram, {browser-window--new}].
+
+=== Synopsis
+
+[source, python, role="noclip"]
+----
+nbinteract.hist(
+    hist_function,
+    *,  <1>
+    options={},
+    layouts={},
+    **interact_params
+)
+----
+<1> arbitrary variables to control the `hist_function`
+
+=== Options
+
+[source, python, role="noclip"]
+----
+hist_function (Array | (*args -> Array int | Array float)):
+    Function that takes in parameters to interact with and returns an
+    array of numbers. These numbers will be plotted in the resulting
+    histogram.
+----
+
+[source, python, role="noclip"]
+----
+interact_params (dict):
+    Keyword arguments in the same format as `ipywidgets.interact`.
+    One parameter is required for each argument of both `x_fn` and `y_fn`.
+    If `x_fn` and `y_fn` have conflicting parameter names, prefix the
+    corresponding kwargs with `x__` and
+    `y__`.
+----
+
+.Available options (Python dict)
+[cols="^3a,^3a,^6a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
+|===
+|Name |Value |Description
+
+|`title`
+|empty string
+|Title of the plot
+
+|`aspect_ratio`
+|float
+|Aspect ratio of the figure, defaults 16:9 ratio
+
+|`animation_duration`
+|int
+|Duration of transition on change of the data measured in milliseconds
+
+|`xlabel`
+|empty string
+|Label of the x-axis
+
+|`ylabel`
+|empty string
+|Label of the y-axis
+
+|`xlim`
+|Tuple
+|Contains the (lower, upper) values for x-axis
+
+|`ylim`
+|Tuple
+|Contains the (lower, upper) values for y-axis
+
+|`bins`
+|int (positive)
+|Non-negative int for the number of Towers (bars) generated for the
+histogram. Default: 10
+
+|`normalized`
+|Boolean (True\|False)
+|Normalize histogram area to 1 if `True`. If `False`, plots unmodified
+counts. Default: `True`
+
+|===
+
+.Available layout settings (Python dict)
+[cols="^3a,^3a,^6a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
+|===
+|Name |Value |Description
+
+|`plot_height`
+|string
+|Specifies the `height` of the plot measured in pixels (px).
+Default: 400px
+
+|`plot_width`
+|string
+|Specifies the `width` of the plot measured in pixels (px).
+Default: 640px
+
+|===
+
+== Bar chart
+
+The widget `nbinteract.bar` generates an interactive bar chart that allows
+users to change the parameters of the inputs x_fn and y_fn.
+
+=== Example
+
+[source, python, role="noclip"]
+----
+import nbinteract as nbi
+import numpy as np
+
+def x_fn(n):
+    return np.arange(n)
+
+def y_fn(xs, offset):
+    return xs + offset
+
+
+options = {
+    'ylim': (0, 20),
+}
+
+layouts = {
+    'plot_height': '480px',
+    'plot_width': '800px',
+}
+
+bar_chart = nbi.bar(
+    x_fn,
+    y_fn,
+    n=(3, 10),
+    offset=(1, 10),
+    options=options,
+    layouts=layouts
+)
+# print("Barchart Dataset: ", bar_chart)
+
+bar_chart
+----
+
+=== Rendered Bar chart
+
+lightbox::nbi-widget--bar[1280, {image-nbi-widget--bar}, role="mt-3 mb-4"]
+
+TIP: Find an live example on page:
+link:{url-nbinteract-common-widget--barchart}[Common used widgets -- Barchart, {browser-window--new}].
+
+=== Synopsis
+
+[source, python, role="noclip"]
+----
+nbinteract.bar(
+    x_fn,
+    y_fn,
+    *,  <1>
+    options={},
+    layouts={},
+    **interact_params
+)
+----
+<1> arbitrary variables to control the functions `x_fn`  and `y_fn`
+
+=== Options
+
+[source, python, role="noclip"]
+----
+x_fn (Array | (*args -> Array str | Array int | Array float)):
+    If array, uses array values for categories of bar chart.
+
+    If function, must take parameters to interact with and return an
+    array of strings or numbers. These will become the categories on
+    the x-axis of the bar chart.
+
+y_fn (Array | (Array, *args -> Array int | Array float)):
+    If array, uses array values for heights of bars.
+
+    If function, must take in the output of x_fn as its first parameter
+    and optionally other parameters to interact with. Must return an
+    array of numbers. These will become the heights of the bars on the
+    y-axis.
+----
+
+.Available options (Python dict)
+[cols="^3a,^3a,^6a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
+|===
+|Name |Value |Description
+
+|`title`
+|empty string
+|Title of the plot
+
+|`aspect_ratio`
+|float
+|Aspect ratio of the figure, defaults 16:9 ratio
+
+|`animation_duration`
+|int
+|Duration of transition on change of the data measured in milliseconds
+
+|`xlabel`
+|empty string
+|Label of the x-axis
+
+|`ylabel`
+|empty string
+|Label of the y-axis
+
+|`xlim`
+|Tuple
+|Contains the (lower, upper) values for x-axis
+
+|`ylim`
+|Tuple
+|Contains the (lower, upper) values for y-axis
+
+|===
+
+.Available layout settings (Python dict)
+[cols="^3a,^3a,^6a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
+|===
+|Name |Value |Description
+
+|`plot_height`
+|string
+|Specifies the `height` of the plot measured in pixels (px).
+Default: 400px
+
+|`plot_width`
+|string
+|Specifies the `width` of the plot measured in pixels (px).
+Default: 640px
+
+|===
+
+
+== Interactive Scatter Chart
+
+The widget `nbinteract.scatter_drag` generates an interactive scatter plot
+with the best *fit line* plotted over the points. The points can be dragged
+by the user and the line will automatically update.
+
+=== Example
+
+[source, python, role="noclip"]
+----
+import nbinteract as nbi
+import numpy as np
+from numpy import arange
+
+x_points = np.arange(10)
+y_points = np.arange(10) + np.random.rand(10)
+
+
+options = {
+    'title': 'Interactive Scatter Plot',
+    'xlabel': 'x-values',
+    'ylabel': 'y-values',
+    'xlim': (0, 10),
+    'ylim': (0, 10),
+    'animation_duration': 1000
+}
+
+layouts = {
+    'plot_height': '480px',
+    'plot_width': '800px',
+}
+
+scatter_drag = nbi.scatter_drag(
+    x_points,
+    y_points,
+    options=options,
+    layouts=layouts
+)
+
+scatter_drag
+----
+
+=== Rendered Interactive Scatter Chart
+
+lightbox::nbi-widget--scatter-drag[1280, {image-nbi-widget--scatter-drag}, role="mt-3 mb-4"]
+
+
+TIP: Find an live example on page:
+link:{url-nbinteract-common-widget--i_scatter}[Common used widgets -- Interactive Scatter Chart, {browser-window--new}].
+
+
+=== Synopsis
+
+[source, python, role="noclip"]
+----
+nbinteract.scatter_drag(
+    x_points: 'Array',
+    y_points: 'Array',
+    options={},
+    layouts={}
+)
+----
+
+=== Options
+
+[source, python, role="noclip"]
+----
+x_points (Array Number): x-values of points to plot
+y_points (Array Number): y-values of points to plot
+----
+
+.Available options (Python dict)
+[cols="^3a,^3a,^6a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
+|===
+|Name |Value |Description
+
+|`title`
+|empty string
+|Title of the plot
+
+|`aspect_ratio`
+|float
+|Aspect ratio of the figure, defaults 16:9 ratio
+
+|`animation_duration`
+|int
+|Duration of transition on change of the data measured in milliseconds
+
+|`xlabel`
+|empty string
+|Label of the x-axis
+
+|`ylabel`
+|empty string
+|Label of the y-axis
+
+|`xlim`
+|Tuple
+|Contains the (lower, upper) values for x-axis
+
+|`ylim`
+|Tuple
+|Contains the (lower, upper) values for y-axis
+
+|===
+
+.Available layout settings (Python dict)
+[cols="^3a,^3a,^6a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
+|===
+|Name |Value |Description
+
+|`plot_height`
+|string
+|Specifies the `height` of the plot measured in pixels (px).
+Default: 400px
+
+|`plot_width`
+|string
+|Specifies the `width` of the plot measured in pixels (px).
+Default: 640px
+
+|===
+
+
+== Scatter Chart
+
+The widget `nbinteract.scatter` generates an interactive scatter chart that
+allows users to change the parameters of the inputs x_fn and y_fn.
+
+=== Example
+
+[source, python, role="noclip"]
+----
+def x_fn(n):
+    return np.random.choice(100, n)
+
+def y_fn(xs):
+    return np.random.choice(100, len(xs))
+
+
+options = {
+    'title': 'Scatter Plot',
+    'marker': 'circle',
+    'animation_duration': 1000,
+    'xlabel': 'x-values',
+    'ylabel': 'y-values',
+    'xlim': (0, 100),
+    'ylim': (0, 100)
+}
+
+layouts = {
+    'plot_height': '480px',
+    'plot_width': '800px',
+}
+
+scatter_chart = nbi.scatter(
+    x_fn,
+    y_fn,
+    n=(10,200),
+    options=options,
+    layouts=layouts
+)
+
+scatter_chart
+----
+
+=== Rendered Scatter Chart
+
+lightbox::nbi-widget--scatter[1280, {image-nbi-widget--scatter}, role="mt-3 mb-4"]
+
+TIP: Find an live example on page:
+link:{url-nbinteract-common-widget--scatter}[Common used widgets -- Scatter Chart, {browser-window--new}].
+
+
+=== Synopsis
+
+[source, python, role="noclip"]
+----
+nbinteract.scatter(
+    x_fn,
+    y_fn,
+    *,  <1>
+    options={},
+    layouts={},
+    **interact_params
+)
+----
+<1> arbitrary variables to control the functions `x_fn`  and `y_fn`
+
+=== Options
+
+[source, python, role="noclip"]
+----
+x_fn (Array | (*args -> Array str | Array int | Array float)):
+    If array, uses array values for x-coordinates.
+
+    If function, must take parameters to interact with and return an
+    array of strings or numbers. These will become the x-coordinates
+    of the scatter plot.
+
+y_fn (Array | (Array, *args -> Array int | Array float)):
+    If array, uses array values for y-coordinates.
+
+    If function, must take in the output of x_fn as its first parameter
+    and optionally other parameters to interact with. Must return an
+    array of numbers. These will become the y-coordinates of the
+    scatter plot.
+----
+
+.Available options (Python dict)
+[cols="^3a,^3a,^6a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
+|===
+|Name |Value |Description
+
+|`title`
+|empty string
+|Title of the plot
+
+|`aspect_ratio`
+|float
+|Aspect ratio of the figure, defaults 16:9 ratio
+
+|`animation_duration`
+|int
+|Duration of transition on change of the data measured in milliseconds
+
+|`xlabel`
+|empty string
+|Label of the x-axis
+
+|`ylabel`
+|empty string
+|Label of the y-axis
+
+|`xlim`
+|Tuple
+|Contains the (lower, upper) values for x-axis
+
+|`ylim`
+|Tuple
+|Contains the (lower, upper) values for y-axis
+
+|`marker`
+|`circle`\|`cross`\|`diamond`\|`square`\|`triangle-down`\|`triangle-up`\|`arrow`\|`rectangle`\|`ellipse`
+|Shape of marker plots. Default: `circle`
+
+
+|===
+
+.Available layout settings (Python dict)
+[cols="^3a,^3a,^6a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
+|===
+|Name |Value |Description
+
+|`plot_height`
+|string
+|Specifies the `height` of the plot measured in pixels (px).
+Default: 400px
+
+|`plot_width`
+|string
+|Specifies the `width` of the plot measured in pixels (px).
+Default: 640px
+
+|===
+
+
+== Line Chart
+
+Generates an interactive line chart that allows users to change the
+parameters of the inputs `x_fn` and `y_fn`. The first two arguments of
+`line` are *response functions* that return the x and y-axis coordinates.
+
+Either argument can be *arrays* themselves. Arguments for the response
+functions must be passed in as keyword arguments to line in the format
+expected by interact. The response function for the y-coordinates will
+be called with the x-coordinates as its first argument.
+
+=== Example
+
+[source, python, role="noclip"]
+----
+import nbinteract as nbi
+import numpy as np
+from numpy import arange
+
+def x_fn(max):
+    return np.arange(0, max + 1)
+
+def y_fn(xs, sd):
+    return xs + np.random.normal(0, scale=sd, size=len(xs))
+
+
+options = {
+    'title': 'Line chart',
+    'xlabel': 'x-values (max)',
+    'ylabel': 'y-values (sd)',
+    'xlim': (0, 50),
+    'ylim': (-20, 70),
+    'animation_duration': 500
+}
+
+layouts = {
+    'plot_height': '480px',
+    'plot_width': '800px',
+}
+
+line_chart = nbi.line(
+    x_fn,
+    y_fn,
+    max=(10, 50),
+    sd=(0, 10),
+    options=options,
+    layouts=layouts
+)
+
+line_chart
+----
+
+=== Rendered Line Chart
+
+lightbox::nbi-widget--line[1280, {image-nbi-widget--line}, role="mt-3 mb-4"]
+
+TIP: Find an live example on page:
+link:{url-nbinteract-common-widget--line}[Common used widgets -- Line Chart, {browser-window--new}].
+
+
+=== Synopsis
+
+[source, python, role="noclip"]
+----
+nbinteract.line(
+    x_fn,
+    y_fn,
+    *,  <1>
+    options={},
+    layouts={},
+    **interact_params
+)
+----
+<1> arbitrary variables to control the functions `x_fn`  and `y_fn`
+
+=== Options
+
+[source, python, role="noclip"]
+----
+x_fn (Array | (*args -> Array str | Array int | Array float)):
+    If array, uses array values for x-coordinates.
+
+    If function, must take parameters to interact with and return an
+    array of strings or numbers. These will become the x-coordinates
+    of the line plot.
+
+y_fn (Array | (Array, *args -> Array int | Array float)):
+    If array, uses array values for y-coordinates.
+
+    If function, must take in the output of x_fn as its first parameter
+    and optionally other parameters to interact with. Must return an
+    array of numbers. These will become the y-coordinates of the line
+    plot.
+----
+
+[source, python, role="noclip"]
+----
+interact_params (dict):
+    Keyword arguments in the same format as `ipywidgets.interact`.
+    One parameter is required for each argument of both `x_fn` and `y_fn`.
+    If `x_fn` and `y_fn` have conflicting parameter names, prefix the
+    corresponding kwargs with `x__` and `y__`
+----
+
+.Available options (Python dict)
+[cols="^3a,^3a,^6a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
+|===
+|Name |Value |Description
+
+|`title`
+|empty string
+|Title of the plot
+
+|`aspect_ratio`
+|float
+|Aspect ratio of the figure, defaults 16:9 ratio
+
+|`animation_duration`
+|int
+|Duration of transition on change of the data measured in milliseconds
+
+|`xlabel`
+|empty string
+|Label of the x-axis
+
+|`ylabel`
+|empty string
+|Label of the y-axis
+
+|`xlim`
+|Tuple
+|Contains the (lower, upper) values for x-axis
+
+|`ylim`
+|Tuple
+|Contains the (lower, upper) values for y-axis
+
+|===
+
+.Available layout settings (Python dict)
+[cols="^3a,^3a,^6a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
+|===
+|Name |Value |Description
+
+|`plot_height`
+|string
+|Specifies the `height` of the plot measured in pixels (px).
+Default: 400px
+
+|`plot_width`
+|string
+|Specifies the `width` of the plot measured in pixels (px).
+Default: 640px
+
+|===
+
+== Multiple Choice
+
+Generates a multiple choice question that allows the user to select an
+answer choice and shows whether choice was correct.
+
+=== Example
+
+[source, python, role="noclip"]
+----
+import nbinteract as nbi
+
+multiple_choice = nbi.multiple_choice(
+    question="Select all prime numbers.",
+    choices=['12', '3', '31'],
+    answers=[1, 2]
+)
+
+multiple_choice
+----
+
+=== Rendered Multiple Choice
+
+lightbox::nbi-widget--multiple-choice[1280, {image-nbi-widget--multiple-choice}, role="mt-3 mb-4"]
+
+TIP: Find an live example on page:
+link:{url-nbinteract-common-widget--multiple_choice}[Common used widgets -- Multiple Choice, {browser-window--new}].
+
+=== Synopsis
+
+[source, python, role="noclip"]
+----
+nbinteract.multiple_choice(
+    question,
+    choices,
+    answers
+)
+----
+
+=== Options
+
+.Available options (Python dict)
+[cols="^3a,^3a,^6a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
+|===
+|Name |Value |Description
+
+|`question`
+|empty string
+|Question text displayed above choices
+
+|`choices`
+|list (string)
+|Answer choices that user can select
+
+|`answers`
+|int \| iterable int
+|Either an integer or iterable of integers. Each integer in answers
+corresponds to the index of the correct choice in `choices`
+
+|===
+
+
+== Short Answer
+
+Generates a short answer question that allows user to input an answer in
+a textbox and a submit button to check the answer.
+
+=== Example
+
+[source, python, role="noclip"]
+----
+import nbinteract as nbi
+
+short_answer = nbi.short_answer(
+    'What is 1+1?',
+    answers='2',
+    explanation='1+1 is 2'
+)
+
+short_answer
+----
+
+=== Rendered Short Answer
+
+lightbox::nbi-widget--short_answer[1280, {image-nbi-widget--short-answer}, role="mt-3 mb-4"]
+
+TIP: Find an live examples on page:
+link:{url-nbinteract-common-widget--short_answer}[Common used widgets -- Short Answer, {browser-window--new}].
+
+=== Synopsis
+
+[source, python, role="noclip"]
+----
+nbinteract.short_answer(
+    question,
+    answers,
+    explanation
+)
+----
+
+=== Options
+
+.Available options (Python dict)
+[cols="^3a,^3a,^6a", subs=+macros, options="header", width="100%", role="rtable mt-3"]
+|===
+|Name |Value |Description
+
+|`question`
+|empty string
+|The question being asked
+
+|`answers`
+|int \| iterable int
+|Either an integer or iterable of integers. Each integer in answers
+corresponds to the index of the correct choice in `choices`
+
+|`explanation`
+|list (string)
+|The explanation to the question is displayed if the user inputs the
+correct answer. Default: `None`
+
+|===