# The study's entry recipe: `tvbo run EI_Tuning_tvboptim.yaml`. Its directory is the study root.
tvbo_class: tvbo:SimulationStudy

citekey: EI_Tuning_tvboptim
title: "Three ways to tune excitation-inhibition balance against the same empirical FC"
label: "E-I balance tuning: feedback inhibition control, combined FIC+EIB, and a gradient fit"
description: >-
  Runs the FIC+EIB tuning workflow of Schirner et al. (2023) on a two-population Reduced Wong-Wang
  network: a feedback-inhibition loop that holds excitatory activity at its target, a combined loop
  that additionally tunes the long-range and feed-forward-inhibition weights against empirical FC,
  and a gradient fit of the same weights. All three are declared in one curated experiment and read
  from one container, so the three are compared on the numbers they actually produced.

experiments:
    - tvbo:experiment/EI_Tuning_FIC_EIB_Optimization

figures:
    - name: ei_tuning
      label: "Excitation-inhibition balance tuning"
      description: >-
        What each of the three tuning routes converges to, the functional connectivity each one
        ends up producing, and the connectivity weights the fits arrive at.
      layout: |
          abc
          def
          ghi
      width: 170.0
      height: 165.0
      font_size: 7.0
      panel_numbers: true
      panel_number_loc: upper left
      panels:
          a:
              kind: cartesian
              label: "FIC convergence"
              description: >-
                Mean excitatory gating over the feedback-inhibition loop, against the 0.25 it is
                asked to hold (rule). This is the loop's own tracked observation, recorded once per
                iteration.
              layers:
                  - used: {experiment: 3, output: algorithm__fic__history__mean_S_e}
                    mark: line
                    style: {color: "#0a5170", opts: {linewidth: 1.2}}
              title: ""
              xlabel: "FIC iteration"
              ylabel: "Mean S_e"
              rules:
                  - {orientation: horizontal, at: [0.25]}
          b:
              kind: cartesian
              label: "FIC+EIB convergence (in-loop)"
              description: >-
                The combined loop tunes the connectivity weights as well and is scored on the
                empirical FC: its correlation rises as its error falls. Both are the in-loop
                quantities the recipe declares, computed on the loop's own sliding window.
              layers:
                  - used: {experiment: 3, output: algorithm__fic_eib__history__fc_corr}
                    mark: line
                    label: "FC correlation"
                    style: {color: "#0a5170", opts: {linewidth: 1.2}}
                  - used: {experiment: 3, output: algorithm__fic_eib__history__fc_rmse}
                    mark: line
                    label: "FC RMSE"
                    style: {color: "#d98a00", opts: {linewidth: 1.2}}
              title: ""
              xlabel: "FIC+EIB iteration"
              ylabel: ""
              legend: "lower right"

          c:
              kind: cartesian
              label: "Gradient fit"
              description: "The combined loss of the gradient fit over its optimization steps."
              layers:
                  - used: {experiment: 3, output: optimization__gradient_eib__loss_trajectory}
                    mark: line
                    style: {color: "#3E8E68", opts: {linewidth: 1.2}}
              title: ""
              xlabel: "Optimization step"
              ylabel: "Combined loss"

          d:
              kind: heatmap
              label: "Empirical FC"
              description: >-
                The target every route is scored against, read from the connectome's own BOLD
                correlation. Panels (d) to (g) share one colour scale, so the four are comparable
                by eye and the bar on (g) keys all of them.
              layers:
                  - used: {experiment: 3, output: algorithm__fic_eib__fc_target}
                    encoding: {x: node_j, y: node_i}
                    style: &fc_scale {colormap: cividis, opts: {vmin: -0.3, vmax: 0.9}}
              <<: &fc_axes
                  title: ""
                  xlabel: ""
                  ylabel: "Region"
                  aspect: equal
                  invert_y: true
                  hide_xticklabels: true
                  hide_yticklabels: true
                  colorbar: {show: false}

          e:
              kind: heatmap
              label: "FIC only"
              description: >-
                Simulated FC after feedback inhibition control alone. FIC constrains activity and
                never sees the target, and the matrix shows it.
              layers:
                  - used: {experiment: 3, output: algorithm__fic__fc}
                    encoding: {x: node_j, y: node_i}
                    style: *fc_scale
              <<: *fc_axes

          f:
              kind: heatmap
              label: "FIC+EIB"
              description: "Simulated FC after the combined loop, re-evaluated on a fresh simulation rather than in-loop."
              layers:
                  - used: {experiment: 3, output: algorithm__fic_eib__fc}
                    encoding: {x: node_j, y: node_i}
                    style: *fc_scale
              <<: *fc_axes

          g:
              kind: heatmap
              label: "Gradient fit"
              description: "Simulated FC after the gradient fit, on the same scale as the three beside it."
              layers:
                  - used: {experiment: 3, output: optimization__gradient_eib__observation__fc}
                    encoding: {x: node_j, y: node_i}
                    style: *fc_scale
              <<: *fc_axes
              colorbar:
                  show: true
                  label: "FC"
                  ticks: [-0.3, 0.3, 0.9]

          h:
              kind: heatmap
              label: "Long-range excitation"
              description: "The fitted per-edge long-range weight the combined loop arrives at."
              layers:
                  - used: {experiment: 3, output: estimate__wLRE}
                    encoding: {x: node_j, y: node_i}
                    style: {colormap: cividis}
              <<: *fc_axes
              colorbar:
                  show: true
                  label: "w_LRE"
                  ticks: [0.9, 1.4, 1.9]

          i:
              kind: heatmap
              label: "Feed-forward inhibition"
              description: "The matching feed-forward inhibition weight, on its own scale."
              layers:
                  - used: {experiment: 3, output: estimate__wFFI}
                    encoding: {x: node_j, y: node_i}
                    style: {colormap: cividis}
              <<: *fc_axes
              colorbar:
                  show: true
                  label: "w_FFI"
                  ticks: [0.1, 0.6, 1.1]