%YAML 1.1
---
$schema: "http://stsci.edu/schemas/yaml-schema/draft-01"
id: "http://stsci.edu/schemas/asdf/transform/remap_axes-1.2.0"
title: >
  Reorder, add and drop axes.

description: |
  This transform allows the order of the input axes to be shuffled and
  returned as the output axes.

  It is a list made up of integers, each corresponding to an index of
  the input axis to send to the output axis.

  If only a list is provided, the number of input axes is
  automatically determined from the maximum index in the list.  If an
  object with `mapping` and `n_inputs` properties is provided, the
  number of input axes is explicitly set by the `n_inputs` value.

  Invertibility: TBD
examples:
  -
    - For 2 input axes, swap the axes
    - |
        !transform/remap_axes-1.2.0
          mapping: [1, 0]
  -
    - For 2 input axes, return the second axis and drop the first
    - |
        !transform/remap_axes-1.2.0
          mapping: [1]

  -
    - For 2 input axes, return the first axis twice, followed by the second
    - |
        !transform/remap_axes-1.2.0
          mapping: [0, 0, 1]

  -
    - For 2 input axes, add a third axis which is a constant
    - |
        !transform/concatenate-1.2.0
          forward:
            - !transform/remap_axes-1.2.0
              mapping: [0]
            - !transform/remap_axes-1.2.0
              mapping: [1]
            - !transform/constant-1.2.0
              value: 42

  -
    - Here we have 3 input axes, but we are explicitly dropping the last one
    - |
        !transform/remap_axes-1.2.0
          mapping: [0, 1]
          n_inputs: 3

definitions:
  mapping:
    type: array
    items:
      anyOf:
        - type: integer
        - $ref: "../core/constant-1.0.0"

allOf:
  - $ref: "transform-1.2.0"
  - properties:
      n_inputs:
        description: |
          Explicitly set the number of input axes.  If not provided,
          it is determined from the maximum index value in the
          mapping list.
        type: integer
      mapping:
        $ref: "#/definitions/mapping"
    required: [mapping]
...
