RubyGems - j1-template - Versions diffs - 2022.5.0 → 2022.5.1.rc0 - Mend

j1-template 2022.5.0 → 2022.5.1.rc0

Files changed (386) hide show

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

@@ -1,928 +0,0 @@
----
-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`
-|===