:py:mod:`kwcoco.cli.coco_subset`
================================

.. py:module:: kwcoco.cli.coco_subset


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   kwcoco.cli.coco_subset.CocoSubsetCLI



Functions
~~~~~~~~~

.. autoapisummary::

   kwcoco.cli.coco_subset.query_subset



Attributes
~~~~~~~~~~

.. autoapisummary::

   kwcoco.cli.coco_subset._CLI


.. py:class:: CocoSubsetCLI

   Bases: :py:obj:`object`

   .. py:class:: CLIConfig(data=None, default=None, cmdline=False)

      Bases: :py:obj:`scriptconfig.Config`

      Take a subset of this dataset and write it to a new file

      .. py:attribute:: default
         

         

      .. py:attribute:: epilog
         :annotation: = Multiline-String

          .. raw:: html

              <details><summary>Show Value</summary>

          .. code-block:: text
              :linenos:

              
                      Example Usage:
                          kwcoco subset --src special:shapes8 --dst=foo.kwcoco.json

                          # Take only the even image-ids
                          kwcoco subset --src special:shapes8 --dst=foo-even.kwcoco.json --select_images '.id % 2 == 0'

                          # Take only the videos where the name ends with 2
                          kwcoco subset --src special:vidshapes8 --dst=vidsub.kwcoco.json --select_videos '.name | endswith("2")'
                      

          .. raw:: html

              </details>

         


   .. py:attribute:: name
      :annotation: = subset

      

   .. py:method:: main(cls, cmdline=True, **kw)
      :classmethod:

      .. rubric:: Example

      >>> kw = {'src': 'special:shapes8',
      >>>       'dst': 'subset.json', 'include_categories': 'superstar'}
      >>> cmdline = False
      >>> cls = CocoSubsetCLI
      >>> cls.main(cmdline, **kw)



.. py:function:: query_subset(dset, config)

   .. rubric:: Example

   >>> # xdoctest: +REQUIRES(module:jq)
   >>> from kwcoco.cli.coco_subset import *  # NOQA
   >>> import kwcoco
   >>> dset = kwcoco.CocoDataset.demo()
   >>> assert dset.n_images == 3
   >>> #
   >>> config = CocoSubsetCLI.CLIConfig({'select_images': '.id < 3'})
   >>> new_dset = query_subset(dset, config)
   >>> assert new_dset.n_images == 2
   >>> #
   >>> config = CocoSubsetCLI.CLIConfig({'select_images': '.file_name | test(".*.png")'})
   >>> new_dset = query_subset(dset, config)
   >>> assert all(n.endswith('.png') for n in new_dset.images().lookup('file_name'))
   >>> assert new_dset.n_images == 2
   >>> #
   >>> config = CocoSubsetCLI.CLIConfig({'select_images': '.file_name | test(".*.png") | not'})
   >>> new_dset = query_subset(dset, config)
   >>> assert not any(n.endswith('.png') for n in new_dset.images().lookup('file_name'))
   >>> assert new_dset.n_images == 1
   >>> #
   >>> config = CocoSubsetCLI.CLIConfig({'select_images': '.id < 3 and (.file_name | test(".*.png"))'})
   >>> new_dset = query_subset(dset, config)
   >>> assert new_dset.n_images == 1
   >>> #
   >>> config = CocoSubsetCLI.CLIConfig({'select_images': '.id < 3 or (.file_name | test(".*.png"))'})
   >>> new_dset = query_subset(dset, config)
   >>> assert new_dset.n_images == 3

   .. rubric:: Example

   >>> # xdoctest: +REQUIRES(module:jq)
   >>> from kwcoco.cli.coco_subset import *  # NOQA
   >>> import kwcoco
   >>> dset = kwcoco.CocoDataset.demo('vidshapes8')
   >>> assert dset.n_videos == 8
   >>> assert dset.n_images == 16
   >>> config = CocoSubsetCLI.CLIConfig({'select_videos': '.name == "toy_video_3"'})
   >>> new_dset = query_subset(dset, config)
   >>> assert new_dset.n_images == 2
   >>> assert new_dset.n_videos == 1


.. py:data:: _CLI