$schema: https://json-schema.org/draft/2019-09/schema
title: MultiAnalysisConfig
description: MultiAnalysisConfig Model.
type: object
properties:
  version:
    title: Version
    description: Version number of the configuration.
    type: integer
  simulation_campaign:
    title: Simulation Campaign
    description: Path to the simulation campaign configuration file.
    type: string
    format: path
  output:
    title: Output
    description: Deprecated, use ``cache.path`` instead.
    type: string
    format: path
    deprecated: true
  clear_cache:
    title: Clear Cache
    description: Deprecated, use ``cache.clear`` instead.
    type: boolean
    default: "false"
    deprecated: true
  cache:
    $ref: '#/$defs/CacheConfig'
  simulations_filter:
    title: Simulations Filter
    description: |
      Optional dictionary used to filter the simulations loaded from the simulation campaign.      
      The simulations can be filtered by any attribute used in the campaign, or by ``simulation_id``.
      The syntax of the filter is the same supported by the ``etl.q()`` method, with the simulations filtered as a Pandas dataframe.

      |
      | See the Jupyter notebook :doc:`/notebooks/01_core_transformations` for more information and examples.
      |
      | Example:

      .. code-block:: yaml

          simulations_filter:
            ca: 1.0
            depol_stdev_mean_ratio: 0.45
            fr_scale: 0.4
            vpm_pct: 2.0
    default: "{}"
    type: object
  simulations_filter_in_memory:
    title: Simulations Filter In Memory
    description: |
      Optional dictionary similar to ``simulations_filter``, but used only with the method ``apply_filter()`` of ``MultiAnalyzer`` or ``SingleAnalyzer``.
    default: "{}"
    type: object
  analysis:
    title: Analysis
    description: Dictionary of analyses configurations, where the keys are the names of the analyses.
    type: object
    additionalProperties:
      $ref: '#/$defs/SingleAnalysisConfig'
  custom:
    title: Global Custom Parameters
    description: Optional dict of parameters that can be used in user code.
    default: "{}"
    type: object
required:
- version
- simulation_campaign
- analysis
additionalProperties: false
$defs:
  CacheConfig:
    title: CacheConfig
    description: CacheConfig Model.
    type: object
    properties:
      path:
        title: Cache Path
        description: |
          Path to the cache folder, used to store the generated files.
          If the directory is not empty, its content is loaded in the cache if valid, or it's automatically deleted.
        type: string
        format: path
      clear:
        title: Cache Clear
        description: |
          If True, remove any existing cache.
          If False, reuse the existing cache if possible.
        type: boolean
        default: "false"
      readonly:
        title: Cache Read-Only
        description: |
          If True, use the existing cache if possible, or raise an error.
          If False, use the existing cache if possible, or update it.
          It can be used to prevent accidental updates, or to read the same cache from
          multiple processes, since the lock is shared and not exclusive in this case.
        type: boolean
        default: "false"
      skip_features:
        title: Skip features
        description: |
          Do not write the features files in the cache folder.
          It can be useful to shorten the execution time when experimenting with different parameters, since writing big DataFrames can take some time.
        type: boolean
        default: "false"
      store_type:
        title: Store Type
        description: Name of the format used to store the files in the cache folder (experimental).
        enum:
        - parquet
        - feather
        default: parquet
    additionalProperties: false
  SingleAnalysisConfig:
    title: SingleAnalysisConfig
    description: SingleAnalysisConfig Model.
    type: object
    properties:
      simulations_filter:
        title: Simulations Filter
        description: Reserved field, it should be set only at the top level.
        default: "{}"
        type: object
      simulations_filter_in_memory:
        title: Simulations Filter In Memory
        description: Reserved field, it should be set only at the top level.
        default: "{}"
        type: object
      extraction:
        $ref: '#/$defs/ExtractionConfig'
      features:
        title: Features
        description: |
          List of features configuration dictionaries.
        default: "[]"
        type: array
        items:
          $ref: '#/$defs/FeaturesConfig'
      custom:
        title: Single Analysis Custom Parameters
        description: Optional dict of parameters that can be used in user code.
        default: "{}"
        type: object
    required:
    - extraction
    additionalProperties: false
  ExtractionConfig:
    title: ExtractionConfig
    description: ExtractionConfig Model.
    type: object
    properties:
      report:
        $ref: '#/$defs/ReportConfig'
      neuron_classes:
        title: Neuron Classes
        description: |
          Used to filter the neurons, it must be a dictionary with neuron class labels as keys.
        default: "{}"
        type: object
        additionalProperties:
          $ref: '#/$defs/NeuronClassConfig'
      limit:
        title: Limit
        description: |
          Optional limit to the number of extracted neurons for each neuron class.
          If specified and not `null`, the neuron are chosen randomly up to the given limit.
          For reproducible results, remember to init the Random Number Generator seed in numpy.
        type:
        - integer
        - "null"
      population:
        title: Population
        description: |
          Node population used to filter the neurons, overridable in each neuron class.
        type:
        - string
        - "null"
      node_set:
        title: NodeSet
        description: Optional node_set used to filter the neurons.
        type:
        - string
        - "null"
      node_sets_file:
        title: NodeSetsFile
        description: Optional node_sets file used to filter the neurons.
        type:
        - string
        - "null"
      windows:
        title: Windows
        description: |
          Dictionary of windows, used to decide which bounded data of the report to consider.
          
          Alternatively, some values of the windows dict can be strings referencing other windows, using the format ``<report_name>.extraction.windows.<window_name>``.
        default: "{}"
        type: object
        additionalProperties:
          anyOf:
          - type: string
          - $ref: '#/$defs/WindowConfig'
      trial_steps:
        title: Trial Steps
        description: |
          Dictionary of trial steps referenced by the windows.
        default: "{}"
        type: object
        additionalProperties:
          $ref: '#/$defs/TrialStepsConfig'
    required:
    - report
    additionalProperties: false
  ReportConfig:
    title: ReportConfig
    description: ReportConfig Model.
    type: object
    properties:
      type:
        title: Type
        description: Type of report.
        enum:
        - spikes
        - soma
        - compartment
      name:
        title: Name
        description: Name of the report, needed only for soma or compartment reports.
        default: "''"
        type: string
    required:
    - type
    additionalProperties: false
  NeuronClassConfig:
    title: NeuronClassConfig
    description: NeuronClassConfig Model.
    type: object
    properties:
      query:
        title: Query
        description: |
          Query dict, or list of query dicts, to be used to filter the neurons using ``etl.q``.
          If this property is not specified, any additional properties will be considered as keys of the query dict.
        anyOf:
        - type: object
        - type: array
          items:
            type: object
      population:
        title: Population
        description: |
          Optional node population used to filter the neurons, specific to the current neuron class.
        type:
        - string
        - "null"
      node_set:
        title: NodeSet
        description: Optional node_set, specific to the current neuron class.
        type:
        - string
        - "null"
      node_sets_file:
        title: NodeSetsFile
        description: Optional node_sets file, specific to the current neuron class.
        type:
        - string
        - "null"
      limit:
        title: Limit
        description: Optional limit to the number of neurons, specific to the current neuron class.
        type:
        - integer
        - "null"
      node_id:
        title: NodeId
        description: |
          Optional list of numeric node ids that will be used to filter the neurons.
          It should be avoided if possible, since the ids aren't granted to remain the same in different versions of the libraries.
        type: array
        items:
          type: integer
    additionalProperties: false
  WindowConfig:
    title: WindowConfig
    description: WindowConfig Model.
    type: object
    properties:
      initial_offset:
        title: Initial Offset
        description: Initial offset of the window.
        default: 0.0
        type: number
      bounds:
        title: Bounds
        description: Lower and upper limits of the window, relative to the initial offset.
        type: array
        minItems: 2
        maxItems: 2
        items:
        - type: number
        - type: number
      t_step:
        title: T Step
        description: Time step to consider, used only for soma and compartment reports.
        default: 0.0
        type: number
      n_trials:
        title: N Trials
        description: |
          Number of trials. If more than 1, multiple windows with the same length are generated, each one spaced:

          - by a constant amount, if ``trial_steps_value`` is specified, or
          - by a calculated amount, if ``trial_steps_label`` is specified together with a section with the same name in ``TrialStepsConfig``.
          
          Only one of ``trial_steps_value`` and ``trial_steps_label`` should be specified.
        default: 1
        type: integer
      trial_steps_value:
        title: Trial Steps Value
        description: Constant amount of time used to space windows, considered when ``n_trials`` is greater than 1.
        default: 0.0
        type: number
      trial_steps_list:
        title: Trial Steps List
        description: List of trial steps values, to be used as an alternative to ``trial_steps_value`` and ``n_trials```.
        default: "[]"
        type: array
        items:
          type: number
      trial_steps_label:
        title: Trial Steps Label
        description: Label that should match a section in ``TrialStepsConfig``, considered when ``n_trials`` is greater than 1.
        default: "''"
        type: string
      window_type:
        title: Window Type
        description: Optional window description that will be added to the windows DataFrame.
        default: "''"
        type: string
    required:
    - bounds
    additionalProperties: false
  TrialStepsConfig:
    title: TrialStepsConfig
    description: TrialStepsConfig Model.
    type: object
    properties:
      function:
        title: Function
        description: |
          Name of the function that should be imported and executed to calculate the trial steps.
          
          The function should accept the positional parameters:
          
          * ``spikes``: numpy array of spikes, automatically filtered by ``initial_offset``, ``bounds``, and the attributes ``population``, ``node_set``, and ``limit``.
          * ``params``: dictionary of parameters defined in this section.

          and it should return a float representing the dynamic offset to be added to the initial offest of the window.
        type: string
      bounds:
        title: Bounds
        description: Lower and upper limits relative to the initial offset of window, used to filter the spikes passed to the function.
        type: array
        minItems: 2
        maxItems: 2
        items:
        - type: number
        - type: number
      population:
        title: Population
        description: |
          Optional node population used to filter the spikes, overriding the global value.
        type:
        - string
        - "null"
      node_set:
        title: NodeSet
        description: Optional node_set used to filter the spikes, overriding the global value.
        type:
        - string
        - "null"
      node_sets_file:
        title: NodeSetsFile
        description: Optional node_sets file used to filter the spikes, overriding the global value.
        type:
        - string
        - "null"
      limit:
        title: Limit
        description: Optional limit to the number of neurons, overriding the global value.
        type:
        - integer
        - "null"
    required:
    - function
    - bounds
  FeaturesConfig:
    title: FeaturesConfig
    description: FeaturesConfig Model.
    type: object
    properties:
      type:
        title: Type
        description: |
          Type of computation. Valid values are:

          * ``multi``: if the configured function produces multiple dataframes of features; features are calculated in parallel in subprocesses.
          * ``single``: if the configured function produces a single dataframe of features; features are calculated in a single process (to be deprecated).
          
          Using ``type=multi`` is preferred and it may speed up the performance of the calculation.
        enum:
        - single
        - multi
      name:
        title: Name
        description: |
          Name of the features DataFrame to be created, used only in case of ``type=single``.
        type: string
      groupby:
        title: Groupby
        description: |
          List of columns of the ``report`` dataframe to group by. Valid item values are:

          * ``simulation_id``
          * ``circuit_id``
          * ``window``
          * ``trial``
          * ``neuron_class``
          * ``gid``
        type: array
        items:
          type: string
      function:
        title: Function
        description: |
          Name of the function to calculate the features, imported and executed for each group of data.

          The function should accept the parameters ``repo, key, df, params``, and it should return:

          * if ``type=multi``, a dictionary of ``dataframe_name -> dataframe``, that will be used to produce multiple final DataFrames.
          * if ``type=single``, a dictionary of ``feature_name -> number``, where each key will be a column in the final features DataFrame.
        type: string
      neuron_classes:
        title: Neuron Classes
        description: |
          List of neuron classes to consider, or empty to consider them all.
        default: "[]"
        type: array
        items:
          type: string
      windows:
        title: Windows
        description: |
          List of windows to consider, or empty to consider them all.
        default: "[]"
        type: array
        items:
          type: string
      params:
        title: Params
        description: |
          Optional configuration parameters that will be passed to the specified function.
        default: "{}"
        type: object
      params_product:
        title: Params Product
        description: |
          Optional dict of parameters that will be used to expand the parameters passed to the function, as ``itertools.product`` from the python standard library.
        default: "{}"
        type: object
      params_zip:
        title: Params Zip
        description: |
          Optional dict of parameters that will be used to expand the parameters passed to the function, as ``zip`` from the python standard library.
        default: "{}"
        type: object
      suffix:
        title: Suffix
        description: |
          Suffix to be added to the features DataFrames, used only if ``type=multi``.
          
          A numeric suffix is automatically added when any of ``params_product`` or ``params_zip`` is specified.
        default: "''"
        type: string
      multi_index:
        title: MultiIndex
        description: |
          - If True, do not reset the index of the resulting DataFrames of features, and add the values specified in ``groupby`` to the MultiIndex.
          - If False, reset the index, returning columnar DataFrames.

          The DataFrames with MultiIndex should use less memory then the columnar DataFrames, but they take more time to load and dump to disk.
        type: boolean
        default: "true"
    required:
    - type
    - groupby
    - function
    additionalProperties: false
