iteraa.piaa
===========

.. py:module:: iteraa.piaa


Functions
---------

.. autoapisummary::

   iteraa.piaa.subsetSplit
   iteraa.piaa.submitAAjobs
   iteraa.piaa.runAA
   iteraa.piaa.fitPIAA


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

.. py:function:: subsetSplit(X, nSubsets, dataName, subsetsSampleIdxs=[], subsetsPicklesPath=SUBSETS_PICKLES_PATH, postfixStr='', shuffle=True, randomState=RANDOM_STATE, verbose=False)

   Split data into subsets.

   :param X: Whole data set.
   :type X: numpy.ndarray
   :param numSubset: Number of subsets.
   :type numSubset: int
   :param subsetsSampleIdxs: Identifiers for subset samples.
   :type subsetsSampleIdxs: list[int]
   :param dataName: Name of dataset.
   :type dataName: str
   :param subsetsPicklesPath: Path to directory containing data subset pickle files.
   :type subsetsPicklesPath: str
   :param postfixStr: Postfix name.
   :type postfixStr: str
   :param shuffle: Whether to shuffle data.
   :type shuffle: bool
   :param randomState: Random seed.
   :type randomState: int
   :param verbose: Whether information is printed.
   :type verbose: bool

   :returns: **runTime** -- Duration of execution.
   :rtype: float


.. py:function:: submitAAjobs(nArchetypes, dataName, splitKeyword='data', postfixStr='', jobscriptsDirPath=JOBSCRIPTS_DIR_PATH, subsetsPicklesPath=SUBSETS_PICKLES_PATH, outputsPicklesPath=OUTPUTS_PICKLES_PATH, AAscriptPath=AA_SCRIPT_PATH, project='q27', queue='normal', numCPUs=48, wallTime='00:05:00', mem=5, jobFS=1, email='Jonathan.Ting@anu.edu.au', verbose=False)

   Submit jobs of executing individual archetypal analysis to a job scheduler.

   :param X: Whole data set.
   :type X: numpy.ndarray
   :param dataName: Name of dataset.
   :type dataName: str
   :param splitKeyword: Keyword for data subsets.
   :type splitKeyword: str
   :param postfixStr: Postfix name.
   :type postfixStr: str
   :param jobscriptsPicklesPath: Path to directory containing data jobscript files.
   :type jobscriptsPicklesPath: str
   :param subsetsPicklesPath: Path to directory containing data subset pickle files.
   :type subsetsPicklesPath: str
   :param outputsPicklesPath: Path to directory containing data output pickle files.
   :type outputsPicklesPath: str
   :param AAscriptPath: Path to script to run archetypal analysis.
   :type AAscriptPath: str
   :param verbose: Whether information is printed.
   :type verbose: bool

   :rtype: None


.. py:function:: runAA(fName, nArchetypes, outputsPicklesPath=OUTPUTS_PICKLES_PATH, splitKeyword='data', robust=False, tolerance=0.001, computeXtX=False, stepsFISTA=3, stepsAS=50, randominit=False, numThreads=-1, onlyZ=False)

   Executes archetypal analysis.

   :param fName: Path to pickle file containing data.
   :type fName: str
   :param nArchetypes: Number of archetypes.
   :type nArchetypes: int
   :param outputsPicklesPath: Path to directory containing output pickle files.
   :type outputsPicklesPath: str
   :param splitKeyword: Keyword for data subsets.
   :type splitKeyword: str
   :param robust: Whether to use robust archetypal analysis.
   :type robust: bool
   :param tolerance: Tolerance.
   :type tolerance: float
   :param computeXtX: Whether to compute XtX.
   :type computeXtX: bool
   :param stepsFISTA: Number of FISTA steps.
   :type stepsFISTA: int
   :param stepsAS: Number of active subset steps.
   :type stepsAS: int
   :param randominit: Whether to initialise randomly.
   :type randominit: bool
   :param numThreads: Number of threads for algorithm execution.
   :type numThreads: int
   :param onlyZ: Whether to stop early by returning only Z matrix.
   :type onlyZ: bool

   :rtype: None


.. py:function:: fitPIAA(X, nArchetypes, numSubset, dataName, outputsPicklesPath=OUTPUTS_PICKLES_PATH, postfixStr='', shuffle=True, robust=False, onlyZ=False, C=0.0001, tolerance=0.001, computeXtX=False, stepsFISTA=3, stepsAS=50, randominit=False, randomState=RANDOM_STATE, numThreads=-1, splitRunTime=0.0, verbose=True)

   Combining results from individual archetypal analysis runs to obtain final archetypes.

   :param X: Whole data set.
   :type X: numpy.ndarray
   :param nArchetypes: Number of archetypes.
   :type nArchetypes: int
   :param numSubset: Number of subsets.
   :type numSubset: int
   :param dataName: Name of dataset.
   :type dataName: str
   :param outputsPicklesPath: Path to directory containing output pickle files.
   :type outputsPicklesPath: str
   :param postfixStr: Postfix name.
   :type postfixStr: str
   :param shuffle: Whether to shuffle data.
   :type shuffle: bool
   :param robust: Whether to use robust archetypal analysis.
   :type robust: bool
   :param onlyZ: Whether to stop early by returning only Z matrix.
   :type onlyZ: bool
   :param C:
             C.
   :type C: float
   :param tolerance: Tolerance.
   :type tolerance: float
   :param computeXtX: Whether to compute XtX.
   :type computeXtX: bool
   :param stepsFISTA: Number of FISTA steps.
   :type stepsFISTA: int
   :param stepsAS: Number of active subset steps.
   :type stepsAS: int
   :param randominit: Whether to initialise randomly.
   :type randominit: bool
   :param randomState: Random seed.
   :type randomState: int
   :param numThreads: Number of threads for algorithm execution.
   :type numThreads: int
   :param splitRuntime: Execution duration for splitting of data into subsets (seconds)
   :type splitRuntime: float
   :param verbose: Whether information is printed.
   :type verbose: bool

   :returns: **AA** -- Object with fitted results.
   :rtype: ArchetypalAnalysis object