Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Distinguish between aggregate & device properties #174

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Distinguish between aggregate & device properties #174

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9749684
Distinguish between aggregate & device properties
cjsha Dec 30, 2024
734eb50
Add css classes for badges
cjsha Dec 31, 2024
2e0d5d9
PR 174 feedback
cjsha Jan 2, 2025
e44f8c5
Review of property-categories.md
jonnew Jan 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions api/configure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,13 @@
---
uid: configure
title: Configuration Operators
title: Device Group Configuration Operators
---

Aggregate configuration operators belong in a top-level chain of operators between
[`CreateContext`](xref:OpenEphys.Onix1.CreateContext) and [`StartAcquisition`](xref:OpenEphys.Onix1.StartAcquisition) to
configure ONIX hardware hubs. These are known as aggregate configuration operators because they configure an aggregation
of devices (also referred to as a hub) on a given headstage, miniscope, breakout board, etc..
configure ONIX hardware hubs. These are known as device group configuration operators because they configure an aggregation
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

dont use hub, its a specification term.

of devices (also referred to as a hardware hub) on a given headstage, miniscope, breakout board, etc..

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Device Group

Aggregate configuration operators are simply referred to as "Configuration Operators" in the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TOC -> Table of contents

[Reference](xref:OpenEphys.Onix1) TOC for concision and simplicity as they are recommended starting-point operators for
configuring Open Ephys ONIX hardware. There are also <xref:device-configure>.
7 changes: 4 additions & 3 deletions api/device-configure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@ title: Device Configuration Operators
---

> [!TIP]
> Device configuration operators are not recommended for using off-the-shelf Open Ephys hardware. Use aggregate [configuration operators](xref:configure) instead. Aggregate [configuration operators](xref:configure) confer the following benefits:
> - The `address` and `name` properties of aggregate configuration operators undergo automatic configuration which reduces the risk of erroneous configuration.
> - The workflow is less cluttered with configuration operators as one aggregate configuration operator corresponds to multiple device operators. This improves workflow legibility and expedites the workflow scripting process.
> Device configuration operators are not recommended for using off-the-shelf Open Ephys hardware.
> Use [device group configuration operators](xref:configure) instead. They confer the following benefits:
> - The `address` and `name` properties of device group configuration operators undergo automatic configuration which reduces the risk of erroneous configuration.
> - The workflow is less cluttered with configuration operators as one device group configuration operator corresponds to multiple device operators. This improves workflow legibility and expedites the workflow scripting process.

Device configuration operators belong in a top-level chain of operators between [`CreateContext`](xref:OpenEphys.Onix1.CreateContext) and [`StartAcquisition`](xref:OpenEphys.Onix1.StartAcquisition) to configure devices contained by ONIX hardware hubs.
47 changes: 36 additions & 11 deletions articles/getting-started/property-categories.md
View file
Open in desktop
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

edited directly by @jonnew

Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,42 @@ uid: property-categories
title: Property Categories
---

There are specific categories of properties that define when an operator's properties can be modified.
Operators can be configured through editable properties. These properties fall
into the following categories:

<span class="badge bg-warning-subtle border border-warning-subtle text-warning-emphasis rounded-pill"
id="configuration">configuration</span> properties have an effect on hardware when a workflow is started and are used to
initialize the hardware state. Even if they are changed while a workflow is running, they will not have an effect until
the workflow is restarted.
<span class="badge oe-badge-border oe-badge-orange"
id="configuration">Configuration</span> properties have an effect on hardware
when a workflow is started and are used to initialize the hardware state. If
they are changed while a workflow is running, they will not have an effect until
the workflow is restarted. For example, the `Driver` and `Index` properties of
<xref:OpenEphys.Onix1.CreateContext#properties> are used to specify the hardware
prior to starting a recording.

<span class="badge bg-primary-subtle border border-primary-subtle text-primary-emphasis rounded-pill"
id="acquisition">acquisition</span> properties have an immediate effect on hardware when the workflow is running. For
instance, stimulus waveform properties can be dynamically modified according to parameters in your workflow.
<span class="badge oe-badge-border oe-badge-blue"
id="acquisition">Acquisition</span> properties have an immediate effect on
hardware when the workflow is running. For example, the stimulus properties of
<xref:OpenEphys.Onix1.Headstage64ElectricalStimulatorTrigger#properties> can be dynamically
configured while a workflow is running to shape stimulus patterns in real-time.

<span class="badge oe-badge-border oe-badge-green" id="device-group">Device
Group</span> properties are only available through [Device Group configuration
operators](xref:configure) that are used for globally configuring groups of
devices. For example,
<xref:OpenEphys.Onix1.ConfigureBreakoutBoard.BreakoutBoard#breakoutboard> property can be used
to provide a unique name to different Breakout boards if multiple are used on a
single host computer.

<span class="badge oe-badge-border oe-badge-red" id="device">Device</span>
properties are available through [Device configuration
operators](xref:device-configure) and device group configuration operators that
combine multiple individual devices. For example, the
<xref:OpenEphys.Onix1.ConfigureBreakoutBoard.AnalogIO#analogio> property can be used to
configure the Analog IO device on a breakout board.

<!-- TODO: Move this to the user guide -->
<!-- Writing <span class="badge oe-badge-border oe-badge-blue" id="acquisition">Acquisition</span> <span
class="badge oe-badge-border oe-badge-red" id="device">Device</span> properties to hardware
dynamically (e.g. while the the workflow is running) requires using device configuration operators
because externalizing device properties from a device group configuration operator in Bonsai is
currently not possible. -->

`Devices` properties refer to the individual devices available within a particular aggregate operator. Aggregate
operators include <xref:OpenEphys.Onix1.ConfigureHeadstage64>, <xref:OpenEphys.Onix1.ConfigureBreakoutBoard>, and more.
Explore other available options under the [aggregate configuration operators](xref:configure) page.
2 changes: 1 addition & 1 deletion template/ManagedReference.extension.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ exports.preTransform = function (model) {
if (operator.hub) {
properties = extractConstituentOperatorsData(model);
properties.unshift({
'object': 'Configuration',
'object': model.name[0].value.replace('Configure', ''),
'constituentOperator': false,
'hasProperties': true,
'properties': sortPropertiesData([
Expand Down
36 changes: 14 additions & 22 deletions template/partials/class.tmpl.partial
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<div class="Important alert alert-info">
<h5>TIP</h5>
<p>
This is a device configuration operator. <a class="xref" href="configure.html">Aggregate configuration operators</a> are recommended in lieu of <a class="xref" href="device-configure.html">device configuration operators</a> for interfacing with Open Ephys Onix hardware.
This is a device configuration operator. <a class="xref" href="configure.html">Aggregate configuration operators</a> are recommended instead of <a class="xref" href="device-configure.html">device configuration operators</a> for interfacing with Open Ephys Onix hardware.
</p>
</div>
{{/oe.operator.configureDevice}}
Expand Down Expand Up @@ -31,41 +31,33 @@

{{#oe.operator.hub}}

<h3>Configuration</h3>

{{#oe.properties}}
{{^constituentOperator}}

<p>These are properties of the aggregate operator:</p>
<h3 class="text-break" style="display: inline-block;">{{{object}}}</h3>

{{#hasProperties}}
{{>partials/propertyTable}}
{{/hasProperties}}
{{^hasProperties}}
<p>This operator does not have any configuration options.</p>
{{/hasProperties}}
{{^constituentOperator}}
<a class="xref" href="~/articles/getting-started/property-categories.html#device-group">
<button class="badge oe-badge-border oe-badge-green">Device Group</button>
</a>
<p>These are properties of the {{{oe.name}}} <a class="xref" href="~/api/configure.html">device group configuration operator</a>:</p>
{{/constituentOperator}}
{{/oe.properties}}

<h3>Devices</h3>

{{#oe.properties}}
{{#constituentOperator}}

<h4>{{{object}}}</h4>

<p>{{{object}}} is a {{{type}}} operator encapsulated by the {{oe.name}} operator with the following properties:</p>
<a class="xref" href="~/articles/getting-started/property-categories.html#device">
<button class="badge oe-badge-border oe-badge-red">Device</button>
</a>
<p>{{{object}}} is a {{{type}}} device operator contained by the {{{oe.name}}} operator with the following properties:</p>
{{/constituentOperator}}

{{#hasProperties}}
{{>partials/propertyTable}}
{{/hasProperties}}

{{^hasProperties}}
<p>This operator does not have any configuration options.</p>
<p>This operator does not have any properties to set.</p>
{{/hasProperties}}

{{/constituentOperator}}
{{/oe.properties}}

{{/oe.operator.hub}}

{{#oe}}
Expand Down
8 changes: 4 additions & 4 deletions template/partials/propertyTable.tmpl.partial
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,17 +13,17 @@
{{#acquisition}}
<div>
<a class="xref" href="~/articles/getting-started/property-categories.html#acquisition">
<button class="badge bg-primary-subtle border border-primary-subtle text-primary-emphasis rounded-pill">
acquisition
<button class="badge oe-badge-border oe-badge-blue">
Acquisition
</button>
</a>
</div>
{{/acquisition}}
{{#configuration}}
<div>
<a class="xref" href="~/articles/getting-started/property-categories.html#configuration">
<button class="badge bg-warning-subtle border border-warning-subtle text-warning-emphasis rounded-pill">
configuration
<button class="badge oe-badge-border oe-badge-orange">
Configuration
</button>
</a>
</div>
Expand Down
122 changes: 90 additions & 32 deletions template/public/main.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,43 +54,12 @@
} */

figcaption {
/* font-size: calc(var(--bs-body-font-size) * 0.9); */
font-style: italic;
border: solid 1px var(--bs-border-color);
padding: 0.25rem;
}

/* h1 {
font-weight: 500;
font-size: calc(2.2rem + 0.8vw);
}

h2 {
font-weight: 480;
font-size: calc(2.0rem + 0.6vw);
}

h3 {
font-weight: 460;
font-size: calc(1.8rem + 0.4vw);
}

h4 {
font-weight: 440;
font-size: calc(1.6rem + 0.2vw);
}

h5 {
font-weight: 420;
font-size: 1.4rem;
}

h6 {
font-weight: 400;
font-size: 1.2rem;
} */

/* This is for formatting markdown files specifically */
/* Format markdown files */

ol ol, ol ul {
margin-bottom: 1rem
Expand All @@ -106,4 +75,93 @@ ol li div {

[data-bs-theme=light] #logo {
content:url("../logo-light-mode.svg");
}

/* Create color palette for badges */

:root, [data-bs-theme=light] {
--oe-red-text: color-mix(in srgb, var(--bs-red), black 60%);
--oe-red-background: color-mix(in srgb, var(--bs-red), white 80%);
--oe-red-border: color-mix(in srgb, var(--bs-red), white 60%);
--oe-orange-text: color-mix(in srgb, var(--bs-orange), black 60%);
--oe-orange-background: color-mix(in srgb, var(--bs-orange), white 80%);
--oe-orange-border: color-mix(in srgb, var(--bs-orange), white 60%);
--oe-yellow-text: color-mix(in srgb, var(--bs-yellow), black 60%);
--oe-yellow-background: color-mix(in srgb, var(--bs-yellow), white 80%);
--oe-yellow-border: color-mix(in srgb, var(--bs-yellow), white 60%);
--oe-green-text: color-mix(in srgb, var(--bs-green), black 60%);
--oe-green-background: color-mix(in srgb, var(--bs-green), white 80%);
--oe-green-border: color-mix(in srgb, var(--bs-green), white 60%);
--oe-blue-text: color-mix(in srgb, var(--bs-blue), black 60%);
--oe-blue-background: color-mix(in srgb, var(--bs-blue), white 80%);
--oe-blue-border: color-mix(in srgb, var(--bs-blue), white 60%);
--oe-purple-text: color-mix(in srgb, var(--bs-purple), black 60%);
--oe-purple-background: color-mix(in srgb, var(--bs-purple), white 80%);
--oe-purple-border: color-mix(in srgb, var(--bs-purple), white 60%);
}

[data-bs-theme=dark] {
color-scheme: dark;
--oe-red-text: color-mix(in srgb, var(--bs-red), white 40%);
--oe-red-background: color-mix(in srgb, var(--bs-red), black 80%);
--oe-red-border: color-mix(in srgb, var(--bs-red), black 40%);
--oe-orange-text: color-mix(in srgb, var(--bs-orange), white 40%);
--oe-orange-background: color-mix(in srgb, var(--bs-orange), black 80%);
--oe-orange-border: color-mix(in srgb, var(--bs-orange), black 40%);
--oe-yellow-text: color-mix(in srgb, var(--bs-yellow), white 40%);
--oe-yellow-background: color-mix(in srgb, var(--bs-yellow), black 80%);
--oe-yellow-border: color-mix(in srgb, var(--bs-yellow), black 40%);
--oe-green-text: color-mix(in srgb, var(--bs-green), white 40%);
--oe-green-background: color-mix(in srgb, var(--bs-green), black 80%);
--oe-green-border: color-mix(in srgb, var(--bs-green), black 40%);
--oe-blue-text: color-mix(in srgb, var(--bs-blue), white 40%);
--oe-blue-background: color-mix(in srgb, var(--bs-blue), black 80%);
--oe-blue-border: color-mix(in srgb, var(--bs-blue), black 40%);
--oe-purple-text: color-mix(in srgb, var(--bs-purple), white 40%);
--oe-purple-background: color-mix(in srgb, var(--bs-purple), black 80%);
--oe-purple-border: color-mix(in srgb, var(--bs-purple), black 40%);
}

/* Create classes for badges */

.oe-badge-border {
border-radius: var(--bs-border-radius-pill);
border-width: var(--bs-border-width);
border-style: var(--bs-border-style);
}

.oe-badge-red {
color: var(--oe-red-text);
background-color: var(--oe-red-background);
border-color: var(--oe-red-border);
}

.oe-badge-orange {
color: var(--oe-orange-text);
background-color: var(--oe-orange-background);
border-color: var(--oe-orange-border);
}

.oe-badge-yellow {
color: var(--oe-yellow-text);
background-color: var(--oe-yellow-background);
border-color: var(--oe-yellow-border);
}

.oe-badge-green {
color: var(--oe-green-text);
background-color: var(--oe-green-background);
border-color: var(--oe-green-border);
}

.oe-badge-blue {
color: var(--oe-blue-text);
background-color: var(--oe-blue-background);
border-color: var(--oe-blue-border);
}

.oe-badge-purple {
color: var(--oe-purple-text);
background-color: var(--oe-purple-background);
border-color: var(--oe-purple-border);
}
Loading