# JSAT Documentation

## Outline:

- JSON file format, creating nodes, edges
- The script file and highlighting strategies through the network
- Viewing the network and analysis

# Part 1: The data folder, Where the nodes and edge relationships of the network are created
- To start creating your network with nodes and eges, first navigate to the data folder in jsat. Here you will can ad your own json files following the example we provide. Here we will be working with the provided "robot_example.json" with the example of our disaster robot network.  
 
- The data folder contains json files, which will contain our edge and node relationships that define the graph that will be generated by running the script. 
- In “GraphData” we have two sections, one for creating nodes and one for creating edges, which are the relationships/connections between the nodes. We need to define both to create the network. 
- Nodes are given a name that will be displayed on the network (usually abbreviated), assigned a node type, and then a note can be given for the entire name

 ``` JSON
"Nodes": {
    "OST": {
        "Type": "BaseEnvironmentResource",
        "UserData": "ObservedSubsystemTemperatures"
    },
    "RS": {
        "Type": "BaseEnvironmentResource",
        "UserData": "RobotState"
    },
    "GL": {
        "Type": "BaseEnvironmentResource",
        "UserData": "GoalLocation"
    }
}
```


## Node example
- “OST” will the displayed abbreviated name, the “Type” is a Base EnvironmentResource, and “UserData” is the full name ObservedSubsystemTemperatures
- After defining all the nodes in the network, then we can define the edges that connect them. The edges in our network are directed, meaning that they point from one node to another (in one direction)

 ``` JSON
 "Edges": [
    {
        "Source": "BLM",
        "Target": "OBL",
        "UserData": {
            "QOS": ""
        }
    },
    {
        "Source": "OBL",
        "Target": "RPP",
        "UserData": {
            "QOS": ""
        }
    }
]
```

- Each edge has a “Source” node and a “Target” node that is the node to which the arrow is pointing. It is possible for a source node to be pointing at several target nodes. However, one must make sure to only connect functions to resources, as connections cannot be made between nodes of the same type (this violates the logic of the network)
- “UserData” is present if you wish to give a name to the label, but we have decided to omit this for our example
- “QOS” defines the Quality of Service of an edge relationship, which defines how often a resource needs to be updated by performing its associated function 
o	Example: If the QOS = 45 seconds, then if a resource hasn’t been updated in 50 seconds, then the resource in that relationship is out-of-date. If the resource was updated 30 seconds ago, then the quality of that resource is still up-to-date 

## Part 2: The script file and generating the network

``` Python
''' The folder containing the JSON data.
'''
directory: str = "data/"

''' The JSON files in the given folder
'''
data_sets: list[str] = [
    "robot_example",
]
```
 
- First make sure that the directory is set to the folder where your data is located, in this case it is the previously discussed “data” folder where are json files are located
- In “data_sets” you can list multiple json data files if you want to be able to run different configurations easily, just ensure that one json folder is uncommented, in our case “robot_example”

``` Python
# Main network
main_net = data_dict["robot_example"]
```

- Ensure that the main network is set to the correct network you created in the json file, in this case we are using the provided "robot example"
- Critical to our modeling is how giving authority to machine/robotic agents gives rise to the need to coordinate, which takes the form of synchrony functions in order to maintain common ground with responsible agents (humans) 

``` Python
# Define roles for both human and operator
operator: nd.Agent = nd.Agent("Operator")
rover: nd.Agent = nd.Agent("Robot")
```
Below we assign roles to the operator and robot agents that we defined above

``` Python
operator.add_action(main_net.get_node("LAA"), operator.allocation_types.Authority)
operator.add_action(main_net.get_node("OLL"), operator.allocation_types.Authority)
```
In this case, the operator is given the "LAA" and "OLL" functions to perform

``` Python
rover.add_action(main_net.get_node("BLM"), rover.allocation_types.Authority)
rover.add_action(main_net.get_node("TMP"), rover.allocation_types.Authority)
```
In this example, we have given the robot the functions "BLM" and "TMP" to perform, these functions are assumed to now be automated in the system

- For this example model, we have not included the possiblity of more than one agent sharing a function to perform, we assume that the opeator and robot perform their respective functions
- We now need to define who has responsibility over the functions in a network, as a mismatch in authority-responsibility will create the need for agents to coordinate, so that common ground is maintained with the responsible agent for that function. Here, we assume the human operator is responsible for all functions performed by the automated robotic agent

``` Python
operator.add_action(main_net.get_node("BLM"), operator.allocation_types.Responsibility)
operator.add_action(main_net.get_node("TMP"), operator.allocation_types.Responsibility)
```
Above is an example of the human operator being given responsibility over the two example functions that the robot has been assigned authority to perform. All functions must be given authority to some agent to perform, and all functions must be assigned to an agent responsible for them. When there is a mismatch in authority-responsibility, then a synchrony function must be created to maintain common ground. This mismatch will automatically generate a synchrony function with the code. 

The list of functions with mismatches is stored in:

``` Python
# Identify the functions with authority-responsibility mismatches
functions_w_auth_resp_mismatch = []
```

The last part of the script file generates the visualization of the network. For some of our work, we want to see a strategy, or the path through the directed gaph from one node to another (goal) noed. Let's say we want to see the paths that one may take to reach our goal: Goal Location (GL). We have included code to highlight edges of the graph to show a strategy. 

``` Python
Strategy without updating PP for NWS
app = CytoscapeApp(data_dict, RoverDataHandler, [("GL", "RM"),("GL", "NWS"),("TM", "NWS"), ("Confirmation-NWS", "NWS"), ("NWS", "NWP"), ("NWP", "Confirming-NWS"), ("Confirming-NWS", "Confirmation-NWS"), ("NWP", "RM"), ("PP", "NWS"), ("PP", "RM")])
```

In the above code, we are highlighting a subsection of the graph to reflect a strategy forr moving towards Goal Location (GL) without needing to update the Planned Path (PP) for Next Waypoint Selection (NWS). We can assume that there will be instances when the Planned Path does not need to be updated if it was recently created and still relevant. Therefore, a strategy would be to not have to update PP and the other functions associated with bringing it about. So, this code shows the subsection of the graph that needs to be performed when this information (QOS) is still relevant. To highlight an edge, simply type in the starting and ending node in the form ("node1", "node2") as seen above. 

``` Python
This will generate the graph without a highlighted strategy, comment this out if you use on the highlighted strategies below
app = CytoscapeApp(data_dict, RoverDataHandler)
```

With this code uncommented, the grpah will generate without a highglighted strategy. 

Run the script file to generate the network and view the dashboard of what you created!


## Part 3: Running the app and viewing the network