# Spatial Structures
A Spatial Structure is a hierarchical arrangement of containers (compartments) that can represent an organism consisting of organs, cells, and other substructures. Alternatively, it can be a laboratory setup, like a test tube or a flow chamber with interconnected compartments. Typically, each structure is described by physical parameters, in particular by volume.
Two types of containers are available - **logical** and **physical** containers. Logical containers do not represent a real container with molecules, but serve to group multiple sub-containers. An example is an **organ**, that groups physical containers like blood, interstitial space, and cells. A logical container may also be used to group multiple organs into a system, like the gastrointestinal tract or the whole organism. Logical containers may contain other logical containers or physical containers.
Physical containers represent a real physical space that can contain molecules. Examples are blood, interstitial space, or cells within an organ, or a test tube in a laboratory setup.
Physical containers must be connected by neighborhoods to allow exchange processes like active or passive transports between them. A neighborhood is a logical connection between two physical containers that allows the definition of transport processes between them. Neighborhoods are always bidirectional, meaning that transport processes can be defined in both directions. Neighborhoods may also carry parameters, for example to describe the physical properties like surface area or permeabilities across the barrier between the two connected compartments.
The following section describes the functionalities of the Spatial Structure building block based on a PBPK model exported from PK-Sim. Later on, a simple [example](#example---creating-a-spatial-structure) is given to create a spatial structure from scratch.
The complex structure of a complete organism can be inspected, used, and modified after loading a simulation that was generated in PK-Sim® (see [Load a Simulation](/working-with-mobi/mobi-documentation/setting-up-simulation.md#load-a-simulation)). Alternatively, a spatial structure can be loaded on its own by using the 
**Load Spatial Structure** command in the Building Block Explorer and selecting the pkml file generated in PK-Sim® or MoBi®.
## Spatial Structures - Functionality Overview
After loading a PBPK model from PK-Sim®, the spatial structure representing the whole organism is located in the imported PK-Sim® module. Double-clicking on the spatial structure (
) or using the **Edit** command of the context menu that appears after right-clicking on it opens an edit window.
The right side of the window shows the structure either in a **Tree** or the **Diagram** view. The tree view shows the hierarchical arrangement of containers and neighborhoods in a tree structure. The diagram view shows the spatial structure in a graphical way. The diagram view is particularly useful for visualizing the physical and logical arrangement of containers and their neighborhoods.
The tab **Formulas** shows all formulas used in the parameters of the spatial structure.
### Parent Path of Top Level Containers
The spatial structures of the models are organized in a hierarchy of containers, where each container can be a child of a parent container. `Container A` can be a child of maximal one parent container `Container B`, and the parent of multiple containers. Each container has a property `Parent path` which specifies the full path to its parent container.
In a module, the user can change the parent container property for the top level containers. When combining modules, the containers (and all their children) of the module will be placed under the container specified in the `Parent path` property. If the parent path of `Container A` is empty OR the container with the specified parent path is not found in the simulation, `Container A` will be created as the top-level container in the simulation.
Be cautious, as changing the parent path of a container will result in different absolute path to the respective container and might break the formulas that use absolute paths for variables definition. You might have to adjust the absolute paths accordingly, by manually appending the parent path to the aliases.
### Neighborhoods
New neighborhoods can be created by dragging a line from one physical container to another in the **Diagram** view, or by right-clicking on the **Neighborhoods** node in the tree view and selecting **Create Neighborhood** from the context menu. The user must specify the neighbor containers and a name for the neighborhood.
If a neighborhood is defined with a neighbor that is not present in the final model structure, the neighborhood is ignored.
When renaming a container, the software suggests changing the neighbor of all neighborhoods associated with the container to the new name.
### Exporting containers as pkml files
As described in ["Modularization concept"](/working-with-mobi/mobi-documentation/modularization-concept.md), individual-specific parameters in PK-Sim modules are not stored directly in the spatial structure but in the Individual BB. When saving a container from a PK-Sim module to pkml, the user must select an Individual and, if applicable, the proteins for which the expression in this container should be allocated. This ensures that the exported container can be used without an individual.
When loading a container from \*.pkml, the exported Expression Profiles are added as PV and IC.
Exporting a container to PKML also exports all of its sub-containers and all neighborhoods that have this container or its sub-containers as a neighbor.
## Example - Creating a Spatial Structure
{% hint style="info" %}
In the process of this and the next sections of this chapter, you will create an example project. An already completed project file named "ManualModel\_Sim.mbp3" is automatically installed together with MoBi® in the default program data directory. The entry "Examples" in the program start menu in the "MoBi" group will lead you to the proper path.
{% endhint %}
Start by creating a new project by executing the **New Project** command in the File menu. Create a new module by selecting the **Module** button in the **Create** group of the **Modeling** tab in the ribbon. Name the new module "ExampleModule" and select a "Spatial Structure" building block to be created within the new module. Click **OK** to create the new module.
The screen should now look as shown in the following figure:
In this example, you will construct a simple spatial structure which consists of a top level logical container having two interconnected physical containers. A common tag will be added to both physical containers which will be used later for restricting some computations (e.g., observers) to be only done for the two sub-containers. Tags are also used for restricting events or selecting source and target for transport processes. Check the corresponding sections for their use.
### Creating Containers and Parameters
1. Create a **top level container** by selecting **New** in the **Add** group of the **Edit Spatial Structure** tab in the ribbon, or by right-clicking on the free area of the tree view and selecting 
**Create Top Container** from the context menu. Enter "BigVial" as the name. Make sure that the type of the container is set to **Logical** and **OK**.
2. Now create two sub-containers. Right-click on the `BigVial` container and select **Create Container** from the context menu. A new window named "New Container" opens. Enter "Vial1" as name, and leave the Container Type on Organ. Select Physical Container in the right combobox below the name input box.
3. Click the **Add Tag** button below the Container Type. You are asked for a tag name. Enter "Obs" as a tag name. Click **OK**.
4. Repeat steps 2 and 3 to create a second sub-container named "Vial2" with the same tag "Obs". Make sure to create the second sub-container as a child of "BigVial" by right-clicking on "BigVial" and not on "Vial1"!
Any container or sub-container may have parameters associated with it. They can describe physical or biological properties of the container that are required for processes like transports or reactions. What is needed in our model is the volume parameter which is used to calculate concentrations required for kinetic equations or for plotting concentrations after a simulation has been performed.
To create the required parameters:
1. Expand the `BigVial` container and select the `Vial1` entry (we will refer to this container by the path `BigVial|Vial1`)
2. Click the "Parameters" tab.
3. Click the button 
**Add Parameter**, upon which a window named "New Parameter" opens.
4. Enter **Volume** into the Name input box, select **Volume** in the Dimension input box, then enter "0.1" into the Value input box. The Formula Type remains "Constant".
5. Finally, click **OK**, and the new parameter "Volume" will appear in the parameter list.
6. Repeat this procedure for the container `BigVial|Vial2` and set the value of the volume to 0.2 liters.
### Creating Neighborhoods
Within a spatial structure, transport processes may occur (see [Active Transporter Molecules](/working-with-mobi/mobi-documentation/molecules-bb.md#active-transports) or [Passive Transports](/working-with-mobi/mobi-documentation/passive-transports-bb.md)) only between physical containers that are connected by a neighborhood.
To create a neighborhood between the two containers `BigVial|Vial1` and `BigVial|Vial2`, proceed as follows:
1. Right-click on the **Neighborhoods** node in the tree view and select **Create Neighborhood** from the context menu. Alternatively, you can also use the **Neighborhood** button in the **Add** group of the **Edit Spatial Structure** tab in the ribbon.
2. Enter "V1V2Connection" as the name of the new neighborhood. Select `BigVial|Vial1` as the first neighbor and `BigVial|Vial2` as the second neighbor from the corresponding tree views. Click **OK** to create the neighborhood.
{% hint style="info" %}
It is possible to type in the paths to the containers instead of selecting them from the tree view. This is especially useful when the final structure with the full paths to the neighbors is a result of combining multiple modules. In this case, the containers may not yet be present in the the modules, but they will be available in the final model.
{% endhint %}
The created spatial structure should now look like this:
By switching to the diagram view, you can see the graphical representation of the spatial structure.
Like the containers, the neighborhood may contain parameters and may carry tags. If you look at simulations imported from PK-Sim®, you will see examples for such parameters. The spatial structure of such a PBPK model is much more complex, but editing it works in the same way as described for our simple example.
We will continue building our example model in the next sections by adding molecules and processes to it.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.open-systems-pharmacology.org/working-with-mobi/mobi-documentation/spatial-structures-bb.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.