> For the complete documentation index, see [llms.txt](https://evomimic.gitbook.io/map-book/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://evomimic.gitbook.io/map-book/dahn-human-experience-of-the-map/dahn-visualizers/collection-visualizers.md).
# Collection Visualizers
Copyright (c) 2022, this book is offered to the world under Creative Commons license CC BY-NC-SA 4.0
DAHN's *collection* *visualizers* present sets of holons that all share the same type (e.g., a set of *agents* or a set of *memes*). Any one-to-many relationship will map to a collection. By default, DAHN includes a set of ***Holon Collection Visualizers**.* Additional *collection visualizers* (for the various sub-types of Holon) can be contributed to the DAHN V-Space by HI developers.
Possible *Holon Collection Visualizers* include the following:
* ***collection-node*** -- (collapsed) this visualizer requires minimal screen real-estate (see the *Meme* and *Resource:Review* *collection-nodes* in the example diagram above). It represents the collection as a rounded rectangle with a double-border (typically as part of a graph). It does not show any of the members of the collection, but can show relationships to other nodes (either holon nodes or collection nodes) and can be expanded into any of the *expanded collection* layouts.
* ***expanded-collection*** -- shows the members of the collection in any one of several layouts:
* ***collection-table*** -- this layout presents the collection as a table with a rows listing members of the collection and columns showing their properties.
* ***collection-grid*** -- this layout represents the collection as a grid of holon nodes. Each member of the collection is presented as a node using the expanded state of a *node visualizer*. The number of nodes in each row of the grid is determined dynamically based on responsive design principles. Grid layouts generally work better than table layouts on presentation devices with relatively small screens (e.g., smart phones).
* ***collection-graph*** -- this layout is similar to the collection grid layout. Like the collection-grid, each member of the collection is rendered using a *node visualizer*. In the *collection-graph*, nodes are presented in their *collapsed state,* whereas in the collection-grid they are presented in their *expanded state*.
* ***collection-map*** -- this layout shows a geographical map with members of the collection as geo-located *pins* the map.
Each of these is further elaborated below.
#### Holon Collection-Node Visualizer
*Collection-nodes* represent a collection of holons in a collapsed state -- i.e., it does not show any of the members of the collection. Their double-border distinguishes them from *holon-nodes*.
*Collection-nodes* support the following actions:
* ***Expand To*** -- allows the *collection-node* to be expanded into any of the expanded collection layouts: *table*, *grid*, *map* or *graph,* or *metrics*. When doing so, the *collection-node's* double border is enlarged to encompass the selected layout of that collection.
* ***Show Related*** -- allows the human agent to select any or all of the relationship types originating from the *collection-node's* holon type to be displayed. For each selected relationship type, if at least one member of the (filtered) collection has that relationship type populated, then a (single) line is shown from the collection node to a *destination node*. If the relationship is populated with multiple values, the destination node will be a *collection-node*. Otherwise, the destination will be a *holon-node*.
* ***Personalization Control*** () -- *clicking* on the personalization control allows alternate visualizations of the collection-node (without expanding it). This controls, for example, whether the holon type icon and/or holon type name is displayed within the collection-node. *Dragging* the personalization control allows the human agent to re-position the collection-node within its containing graph.
* ***Filter*** () -- allows the human agent to view and/or edit one or more *filtering rules.* Since the *collection-node* does not show the members of the collection in its collapsed state, the effect of applying a filter in this state is somewhat subtle. These rules are *remembered* within the current view regardless of the presentation state of the collection. Thus, expanding a collection-node will reveal the full effects of the filter rules by only showing members that meet the filter criteria.
Continuing with our above example, the following figure shows the human agent requesting that the *Agent:We-Space* collection be expanded to show a *Table View* of the collection.
As a result of this action, the graph view is replaced with the default *expanded-collection* view. The following figure shows the *Agent:We-Space* collection using the ***table-layout*** of the ***expanded collection visualizer***.
The *expanded-collection visualizer* is surrounded by a double-border. Its layout consists of a *title block*, a *collection action bar*, a *filter bar*, and the *collection viewing area.* The contents of the collection viewing area vary depending on the selected *collection layout*. The size of the *collection viewing area* is *responsive* to the dimensions of its container. For the *table layout* shown in the figure, the *collection viewing area* contains the table itself. The number and width of each column is dynamically determined based on the size of the collection-table.
The ***title block*** shows the type of the collection.
The ***collection action bar*** offers the following operations:
* ***Type Icon*** -- shows the holon type for this collection. Clicking on the *Type Icon* allows the human agent to select a different collection visualizer or view information about the holon type of the collection.
* ***Level*** -- allows the human agent to navigate up and down the holarchy. This is explained further in the section on [#holon-graph-visualizers](#holon-graph-visualizers "mention")(is this necessary / meaningful here?)
* ***Layout*** -- allows the human agent to select alternate layouts for this collection. Layout choices include:
* ***table*** -- displays members of the collection as rows with holon properties in the columns.
* ***grid*** -- display each member of the collection using a *node visualizer* in an *expanded state*. The nodes are displayed in rows and columns in a way that is responsive to the container size.
* ***graph*** -- display each member of the collection using a *node visualizer* in an *collapsed state*.
* ***map*** -- (only for geo-located collection members) -- displays a geographic map, with geo-located markers for each member of the collection
* ***metrics*** -- displays metrics about the collection, rather than the actual members of the collection.
* ***Find in Collection*** -- supports text search of the properties within the collection.
* ***Add*** (
) -- allows nodes to be added to the collection.
* ***Remove*** (
) -- removes selected nodes from the collection
* ***More Actions*** -- allows the human agent to invoke type-specific collection actions
The ***filter block*** shows a textual representation of the filters (if any) that are currently being applied to the collection. In the example, the filter text states "*this* We-Space *collection has* member Roger P. Briggs". Thus, the collection viewing area will only contain We-Spaces that contain Roger P. Briggs as a member.
There are several ways that filters can be defined.
* ***by navigating a relationship*** -- in our example, we arrived at this collection by navigating the *member of* relationship from the *Roger P. Briggs* holon to arrive at the collection of *We-Spaces* that *Roger P. Briggs* is a *member of*. Thus, the collection table only shows We-Spaces that have Roger P. Briggs as a *member*. There is a subtle shift in perspective that is worth noting. Recall that one of the MAP principles is that[Core Principles of the MAP](/map-book/core-principles-of-the-map.md#every-relationship-is-reciprocal). The *member of* relationship from agent to We-Space, has the reciprocal relationship *member.* The collection-table shows a list of We-Spaces. Its filter rule needs to reflect the perspective of the We-Spaces. This is why the filter shown in the example references the relationship. When we arrived at the We-Space collection, our perspective shifted to the collection of We-Spaces. Thus the filter shown fo
* **by clicking on a *****personalization control*** () within a property column header of the *table-layout*. This offers a simplified way of defining filters that is explained a bit further down in the discussion of the *collections viewing area*.
* **by clicking on the filter-icon** () on a *collection-node* or in the filter block of a *collection-table*. This allows the filters to be modified via the *Filter Dialog Box*:
The *Filter Dialog* allows *filter rules* to be added, edited or removed. Each filter rule is marked as either an ***and-rule*** or an ***or-rule***. A member of a collection will be included only if **all** of its *and-rules* are TRUE and **at least one** its *or-rules* is TRUE.
*Filter rules* come in two flavors:
* ***Relationship Rules*** -- evalute to TRUE if the collection member has the *specified relationship* to the *specified target holon*. The type-specific list of *relationship types* is shown in a drop-list consisting of all of the outbound facing relationships defined for the holon type of the collection as determined from its *L0 holon type descriptor*. The *target holon* for the filter rule can be specified via text search (or, eventually, a nested *Filter Dialog* that allows additional filter rules to be defined in order to select the desired *target holon*).
* ***Property Rules*** -- evalute to TRUE if the value of the specified property of the collection member meets the filter condition. The drop-list of available property names is pulled from the holon's *L0 holon type descriptor*. The range of possible conditions for that property is displayed in a drop-list based on the *L0 property type descriptor*. As an example, for ***Date*** property types, the *Date Comparators* are available under the condition drop-list. For unary comparators (is *before* or *contains*), a single value may be entered. For binary comparators (e.g., *is between*), two values may be entered.
For the table layout, the ***collection viewing area*** contains the table itself. Some collection actions (e.g., *remove from collection*) can operate on multiple rows. The leftmost table column contains selection checkboxes that signify row selection. Clicking on a selection checkbox toggles between selected and not selected. The ***All** or **None** Selection buttons*. in the leftmost column header provides a quick way to *select all rows* or *de-select all rows*, respectively, in one click.
Each table row presents a member of the collection. Each table column (other than the first and last) displays values for the properties of the members of the collection.
#### Personalization Controls
The table layout of the *expanded-collection visualizer* offers various ways for the human agent to control what is displayed in the collection table.
* ***Column Width*** -- is controlled by dragging a columns right-hand border to the left (to shrink) or right (to expand) the column's width.
* ***Column Order (salience)*** -- is controlled by dragging the *personalization icon* (
) left or right.
* ***Column Visibility*** -- If there are more columns than fit in the display space of the table, the right-most column header will simply contain an ellipsis (
). Dragging a column icon onto the ellipsis will cause that column to be hidden. Clicking on the ellipsis will show a list of the hidden columns. Dragging a column from that list to the left will cause that column to be displayed.
Clicking on the ***personalization icon*** ()within a property's header causes the *property personalization dialog* to be displayed.
This dialog offers various ways for the human agent to control the order in which rows are displayed (sort) and what rows are displayed (filter) in the table.
* ***Row Order (sort)*** -- selecting A->Z will sort the table rows in ascending order based on the values of this property. Selecting Z->A will sort the table rows in descending order. To sort on multiple columns, the human agent may click on the *Advanced Sorting* button.
* ***Row Visibility (filter)*** -- row visibility can controlled by selecting specific property values or entering a filter condition. Clicking on 
will show a list of type-specific comparators. Behavior is very similar to that described in the *Filter Dialog Box* described above. In fact, both dialog boxes share the same underlying collection ruleset. Defining a property filter using the *Property Personalization Dialog* is equivalent to defining a property *and-rule* within the *Filter Dialog Box*. If filters are defined for more than one column, only those members that satisfy ALL rules are displayed (i.e., the results of evaluating each property rule is ANDed together).
For more complex filters (e.g., those that require relationship rules), clicking on the *Advanced Filtering* button will cause the *Filter Dialog Box* to be displayed.
**Copyright (c) 2022, this book is offered to the world under Creative Commons license** [**CC BY-NC-SA 4.0**](https://creativecommons.org/licenses/by-nc-sa/4.0/)
Open Questions:
1. Graphql vs. Cypher