repic.utils.build_subsets
=========================

.. py:module:: repic.utils.build_subsets

.. autoapi-nested-parse::

   Creates cross-validation subsets for iterative ensemble particle picking



Attributes
----------

.. autoapisummary::

   repic.utils.build_subsets.name
   repic.utils.build_subsets.rng
   repic.utils.build_subsets.parser


Functions
---------

.. autoapisummary::

   repic.utils.build_subsets.add_arguments
   repic.utils.build_subsets.calc_subsets
   repic.utils.build_subsets.create_symlinks
   repic.utils.build_subsets.plot_defocus
   repic.utils.build_subsets.sample_from_bin
   repic.utils.build_subsets.main


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

.. py:data:: name
   :value: 'build_subsets'


   module name (used by argparse subparser)

   :type: str

.. py:data:: rng

   NumPy random generator (set to zero for reproducibility)

.. py:function:: add_arguments(parser)

   Adds argparse command line arguments for build_subsets.py

   :param parser: argparse parse_args() object
   :type parser: object

   :returns: None


.. py:function:: calc_subsets(n, s=3)

   Calculates subsets of examples (micrographs) for desired sampling percentages (1, 25, 50, and 100%)

   :param n: total number of examples to sample from
   :type n: int
   :param s: number of examples to sample each iteration (s = 3 represents the low, medium, and high defocus bins)
   :type s: int

   :returns: Python dictionary containing the number of examples (values) per subset (key)
   :rtype: dict


.. py:function:: create_symlinks(args, files, label)

   Creates symlinks for cross-validation files

   :param args: argparse command line argument object
   :type args: obj
   :param files: list of micrograph filenames to be symlinled
   :type files: list
   :param label: name for created subdirectory that will contain linked files
   :type label: str

   :returns: None


.. py:function:: plot_defocus(data, low, med, out_file)

   Creates Matplotlib line plot of CTFFIND4 defocus values

   :param data: list of paired micrograph filenames and CTFFIND4 defocus values
   :type data: list
   :param low: low defocus bin upper threshold
   :type low: float
   :param med: medium defocus bin upper threshold
   :type med: float
   :param outfile: filepath of the produced line plot
   :type outfile: str

   :returns: None


.. py:function:: sample_from_bin(bins, i)

   Samples example from a random defocus bin (low, medium, and high) if the bin has items else randomly choose another bin to sample from

   :param bins: list of defocus bins
   :type bins: list
   :param i: index of defocus bin to sample from
   :type i: int

   :returns: filename (str) and CTFFIND4 defocus value (float) of sampled example
   :rtype: tuple


.. py:function:: main(args)

   Builds training, validation, and testing subsets (cross-validation files) for machine learning algorithm training

   :param args: argparse command line argument object
   :type args: obj


.. py:data:: parser

   argparse parse_args() object

   :type: obj