    Compute the probability of detecting an CBC with given SNR and
    threshold, averaging over all orientations and sky positions.
    Based of Finn & Chernoff 1993 (https://arxiv.org/abs/gr-qc/9301003).
    Parameters
    ----------
    snr_value : float or array of floats
        SNR value of the event under ideal conditions. Must be positive.
    snr_threshold : float
        SNR threshold for detection. Must be positive.
    n_thetas : unsigned int
        Number of random realizations of inclination and sky position
        used to calculate the average probability of detecting the
        event. Default: 1e6.
    Returns
    -------
    out : float or array of floats (same as 'snr_value')
        Probability of the received signal to be above the threshold.


returns black hole spins with a random spin value uniformly sampled between 'low' and 'high'


returns black hole spins with a fixed spin value 'spin_value'


        calculates the f() function in Bavera et al (2021) based on given coefficients
        m_WR with units using astropy


calculate Period from separation
        separation is separation (needs to be given in astropy units)
        M1 and M2 are masses of the binary


returns alpha and beta for the Bavera et al. (2021) spin calculation


        Returns spinM1 and spinM2, the spins of the compact objects formed from
        the initial most massive star (M1) and initial least massive star (M2), respectively.

        In this approximation only a BH that is formed second can be tidally spun up, if its
        pre-SN separation is tight enough.

        based on Eq 1 and 2 from https://arxiv.org/pdf/2105.09077.pdf


        Returns spinM1 and spinM2, the spins of the compact objects formed from
        the initial most massive star (M1) and initial least massive star (M2), respectively.

        In this approximation only a BH that is formed second can be tidally spun up, if its
        pre-SN separation is tight enough.

        see Qin+18, approximation originally given in https://ui.adsabs.harvard.edu/abs/2021MNRAS.504.3682C
        (and Equation 5 in https://arxiv.org/pdf/2103.02608.pdf)


        returns metallicity dependent spin parameter coefficients of fitting formula for the Geneva or MESA prescription
        by Belczynski et al. (2020); https://www.aanda.org/10.1051/0004-6361/201936528. Prescription_name should be in ['Geneva', 'MESA']
        it either returns (Geneva:) b, m_1, m_2, a_low,  or (MESA:) a_1, b_1, m_1, a_2 and b_2


        returns spins of the primary (spinM1) and secondary (spinM2)
        based on the MESA BH natal spin model as described in Belczsynski et al. (2020)
        See Equation 4 and Fig 2 in https://www.aanda.org/10.1051/0004-6361/201936528
        this model assumes moderate BH birth spins, with a spin magnitude dependent on metallicity and CO core mass
        Warning: this function currently assumes the two stars have identical metallicity (add a Z mask to change this)


Determine the indices for fixed parameters.


Plot the PDF of each parameter of the model.


    Make a surface brightness map of the lensed image for a given set of model
    parameters.


    Make simulated visibilities given a model image and observed visibilities.
    Writes the visibilities to uvfits files.


    Make an image of the model and the residual from simulated model
    visibilities.  Requires CASA or miriad.


    Make a surface brightness map of a given model image.  Overlay with red
    contours a surface brightness map of the data image to which the model was
    fit.


Remove files created along the way by visualutil routines.


Plot a particular model fit.


    Cycle through each region and run plotFit, selecting parameters
    appropriately.


Function that computes the ln prior probabilities of the model parameters.


Function that computes the Ln likelihood of the data


get model fits within Nbuffer of the best-fit model.


get model fits with mu < 100.


Replace the weights in 'visfile' with weights computed via getStatWgt.


Make a c-shell script to do imaging.


    Plot the convergence profile.  I.e., Max(lnprob) - lnprob as a function of
    iteration number.


Plot the posterior PDF of each parameter of the model.


Plot the evolution of the PDF of each parameter of the model.


Plot the covariance matrix for the parameters of the model.


 Print parameters for this model
    mag: bool
        if True, print magnification factors as well


    Read posterior PDF and identify best-fit parameters.  Plot the best-fit
    model and compare to the data.  Also plot the residuals obtained after
    subtracting the best-fit model from the data and compare to the data.
    Optionally plot the best available optical image and compare to the data.


    Read posterior PDF and draw Nfits realizations from the final Ngood models
    at random.  Plot the model from each realization and compare to the data.
    Also plot the residuals obtained after subtracting the model from the data
    and compare to the data.  By default: Nfits = 12, Ngood=5000.


Plot simulated visibilities, weights, and uvw values vs. entry number.


Use miriad to make a simulated visibility dataset given a model and data.


    NAME: xy_rotate

    PURPOSE: Transform input (x, y) coordiantes into the frame of a new
             (x, y) coordinate system that has its origin at the point
             (xcen, ycen) in the old system, and whose x-axis is rotated
             c.c.w. by phi degrees with respect to the original x axis.

    USAGE: (xnew,ynew) = xy_rotate(x, y, xcen, ycen, phi)

    ARGUMENTS:
      x, y: numpy ndarrays with (hopefully) matching sizes
            giving coordinates in the old system
      xcen: old-system x coordinate of the new origin
      ycen: old-system y coordinate of the new origin
      phi: angle c.c.w. in degrees from old x to new x axis

    RETURNS: 2-item tuple containing new x and y coordinate arrays

    WRITTEN: Adam S. Bolton, U. of Utah, 2009


    NAME: delta_2d

    PURPOSE: Implement 2D Delta function

    USAGE: z = delta_2d(x, y, par)

    ARGUMENTS:
      x, y: vecors or images of coordinates;
            should be matching numpy ndarrays
      par: vector of parameters, defined as follows:
        par[0]: x-center
        par[1]: y-center
        par[2]: radius of a single pixel
        par[3-5]: unused

    RETURNS: 2D Delta function evaluated at x-y coords

    WRITTEN: R. S. Bussmann, 2013 November, Cornell University


    NAME: ellipse_2d

    PURPOSE: Implement 2D Elliptical function

    USAGE: z = ellipse_2d(x, y, par)

    ARGUMENTS:
      x, y: vecors or images of coordinates;
            should be matching numpy ndarrays
      par: vector of parameters, defined as follows:
        par[0]: amplitude
        par[1]: intermediate-axis sigma
        par[2]: x-center
        par[3]: y-center
        par[4]: axis ratio
        par[5]: c.c.w. major-axis rotation w.r.t. x-axis

    RETURNS: 2D Gaussian evaluated at x-y coords

    NOTE: amplitude = 1 is peak flux, not normalized total flux

    WRITTEN: Adam S. Bolton, U. of Utah, 2009


    NAME: gauss_2d

    PURPOSE: Implement 2D Gaussian function

    USAGE: z = gauss_2d(x, y, par)

    ARGUMENTS:
      x, y: vecors or images of coordinates;
            should be matching numpy ndarrays
      par: vector of parameters, defined as follows:
        par[0]: total flux # in ASB original code, this was amplitude
        par[1]: intermediate-axis sigma
        par[2]: x-center
        par[3]: y-center
        par[4]: axis ratio
        par[5]: c.c.w. major-axis rotation w.r.t. y-axis

    RETURNS: 2D Gaussian evaluated at x-y coords

    NOTE: amplitude = 1 is peak flux, not normalized total flux

    WRITTEN: Adam S. Bolton, U. of Utah, 2009


    NAME: sie_grad

    PURPOSE: compute the deflection of an SIE potential

    USAGE: (xg, yg) = sie_grad(x, y, par)

    ARGUMENTS:
      x, y: vectors or images of coordinates;
            should be matching numpy ndarrays
      par: vector of parameters with 1 to 5 elements, defined as follows:
        par[0]: lens strength, or 'Einstein radius'
        par[1]: (optional) x-center (default = 0.0)
        par[2]: (optional) y-center (default = 0.0)
        par[3]: (optional) axis ratio (default=1.0)
        par[4]: (optional) major axis Position Angle
                in degrees c.c.w. of y axis. (default = 0.0)

    RETURNS: tuple (xg, yg) of gradients at the positions (x, y)

    NOTES: This routine implements an 'intermediate-axis' convention.
      Analytic forms for the SIE potential can be found in:
        Kassiola & Kovner 1993, ApJ, 417, 450
        Kormann et al. 1994, A&A, 284, 285
        Keeton & Kochanek 1998, ApJ, 495, 157
      The parameter-order convention in this routine differs from that
      of a previous IDL routine of the same name by ASB.

    WRITTEN: Adam S. Bolton, U of Utah, 2009


    Function to create ERSEM module index everytime the docs are built

    :param file_name: file name of the api
    :type file_name: str


    Run GOTM-ERSEM tutorial

    :param model_path: Full path to netCDF model output
    :type model_path: str

    :return: Dictionary containing output model variables for systests
    :rtype: dict


    Run FABM0D-ERSEM tutorial

    :param model_path: Full path to netCDF model output
    :type model_path: str

    :return: Dictionary containing output model variables for systests
    :rtype: dict


    Run pyfabm-ERSEM tutorial

    :param model_path: Full path to netCDF model output
    :type model_path: str

    :return: list of oxygen saturation concentrations
    :rtype: list


    Reads lines from a list file
    :param listfile: a file having strings, one per line
    :param skip_blank:
    :param skip_comments:
    :return:


    reads json lines
    :param filename: path to dump file
    :return: stream of dictionary objects


    Stores objects into file in JSON line format.
    :param objects: stream of objects to be dumped
    :param filename: path of output file
    :return: number of objects dumped, which is same as number of lines stored


This function adds entity markers into the tokenizer's vocabulary, such as <ner_start=Target> and <ner_end=Target>


Move a tensor to a specific gpu depending on self.gpu_id


            This function inserts type markers such as <Target> around the entity in the sentence
            use_std_text: whether to substitute the entity's text with its canonical name in the sentence. for example,
            if use_std_text is true, then the sentence 'A contains K' would be turned into 'A contains <T>Potassium<\\T>'


    Gets canonical target name: title case, replace spaces and dashes
    with underscore.  Aliases are expanded using tagettab.
    :param name - name whose canonical name is to be looked up
    :return canonical name


Load pretrained Container and Containee model


        Args:
            text:
                text of the document
            batch_size:
                batch size at prediction time.
            entity_linking_method:
                strategy to form Contains relations from Targets and Components.

                Options:
                    closest_containee:
                        for each Container instance, link it to its closest Containee instance with a Contains relation
                    closest_container:
                        for each Containee instance, link it to its closest Container instance with a Contains relation
                    closest_component:
                        for each Container instance, link it to its closest Component instance with a Contains relation,
                    closest_target:
                        for each Containee instance, link it to its closest Target instance with a Contains relation
                    closest_container_closest_containee:
                        union the relation instances found by closest_containee and closest_container


        inserts all the records in the iterator to table
        @param table_name : name of the table to insert
        @param records : iterator of documents


    Gets canonical name: title case
    :param name - name whose canonical name is to be looked up
    :return canonical name

    >>> canonical_name('Fe')
    'Iron'

    >>> canonical_name('I')
    'Iodine'

    >>> canonical_name('FeOT')
    'FeOT'

    >>> canonical_name('m')
    'M'

    >>> canonical_name('CARBONATE')
    'Carbonate'


    Gets standardized target name: title case, replace spaces and dashes
    with underscore.
    :param name - name whose canonical name is to be looked up
    :return canonical name


    Gets canonical name for a property: lower-case.
    :param name - name whose canonical name is to be looked up
    :return canonical name


This function gets canonical name for a component (either element/mineral):


 Named entity recognition (NER) using stanford CoreNLP package

        Args:
            text (str): A string (can be a long string) in which Named Entity
                Recognition will run.
        Return:
            this function returns a dictionary contains the NERs identified,
            sentences extracted, and name of the source parser


 Parse one PDF file using Apache TIKA parser

        Args:
            file_path (str): Path to a PDF file
        Return:
            parsed content stored in a dictionary


    Parses a file at given path
    :param path: path to file
    :return: parsed content


    Extract references from text
    :param content: text
    :return: dictionary of references with reference id ([N]) as key


    >>> eval_brat('test_eval_brat/lpsc16-C-pre-annotate', 'test_eval_brat/lpsc16-C-pre-annotate') # doctest: +NORMALIZE_WHITESPACE
    Read 26 annotations from 1 files in test_eval_brat/lpsc16-C-pre-annotate.
    Read 26 ground-truth annotations from 1 files in test_eval_brat/lpsc16-C-pre-annotate.
                Recall  Prec.   F1
    Element     100.00  100.00  100.00
    Mineral     100.00  100.00  100.00
    Target      100.00  100.00  100.00
    Total:      100.00  100.00  100.00

    >>> eval_brat('test_eval_brat/lpsc16-C-pre-annotate-notarget', 'test_eval_brat/lpsc16-C-pre-annotate') # doctest: +NORMALIZE_WHITESPACE
    Read 25 annotations from 1 files in test_eval_brat/lpsc16-C-pre-annotate-notarget.
    Read 26 ground-truth annotations from 1 files in test_eval_brat/lpsc16-C-pre-annotate.
                Recall  Prec.   F1
    Element     100.00  100.00  100.00
    Mineral     100.00  100.00  100.00
    Target      0.00    0.00    0.00
    Total:      96.15   100.00  98.04

    >>> eval_brat('test_eval_brat/lpsc16-C-pre-annotate', 'test_eval_brat/lpsc16-C-pre-annotate-notarget') # doctest: +NORMALIZE_WHITESPACE
    Read 26 annotations from 1 files in test_eval_brat/lpsc16-C-pre-annotate.
    Read 25 ground-truth annotations from 1 files in test_eval_brat/lpsc16-C-pre-annotate-notarget.
                Recall  Prec.   F1
    Element     100.00  100.00  100.00
    Mineral     100.00  100.00  100.00
    Total:      100.00  100.00  100.00

    >>> eval_brat('test_eval_brat/lpsc16-C-pre-annotate', 'test_eval_brat/lpsc16-C-raymond') # doctest: +NORMALIZE_WHITESPACE
    Read 26 annotations from 1 files in test_eval_brat/lpsc16-C-pre-annotate.
    Read 38 ground-truth annotations from 1 files in test_eval_brat/lpsc16-C-raymond.
                Recall  Prec.   F1
    Element     63.64   70.00   66.67
    Material    0.00    0.00    0.00
    Mineral     83.33   100.00  90.91
    Total:      57.89   88.00   69.84

    >>> eval_brat('test_eval_brat/lpsc16-C-pre-annotate', 'test_eval_brat/lpsc16-C-raymond-v2') # doctest: +NORMALIZE_WHITESPACE
    Read 26 annotations from 1 files in test_eval_brat/lpsc16-C-pre-annotate.
    Read 59 ground-truth annotations from 1 files in test_eval_brat/lpsc16-C-raymond-v2.
                Recall  Prec.   F1
    Element     60.00   60.00   60.00
    Material    0.00    0.00    0.00
    Mineral     68.18   100.00  81.08
    Total:      35.59   84.00   50.00


    Tokenize reference into words by:
        (a) Replacing all special characters with space.
        (b) Splitting the reference by space.
    :param line: one reference
    :return: a set of words


    Compare the intersection of words between two references
    :param ground_truth: original reference
    :param extracted: extracted reference
    :return: Number of common words, Number of actual words, Number of extracted words


    Read references from a file and convert it into a map with key as reference id and value as reference
    :param filepath: path to the file containing references
    :return: reference map


    Evaluate references extracted from a set of documents
    :param ground_truth: directory path where actual references are placed
    :param extracted: directory path where extracted references are placed


            This function inserts type markers such as <Target> around the entity in the sentence

            use_std_text: whether to substitute the entity's text with its canonical name in the sentence. for example,
            if use_std_text is true, then the sentence 'A contains K' would be turned into 'A contains <T>Potassium<\\T>'


extract system ners


map character offset to label to entities


    this function extracts entities from text file
    Argument:
        text_file: text_file that contains the journal/abstract

        ann_file: file that contains annotations from brat.

        doc:  a dictionary that stores corenlp's parsing for text_file. either doc or corenlp_file must not be none.

        corenlp_file: a file that stores corenlp's parsing for text_file. If use_sys_ners is True, then corenlp_file must point to the parse results (in json file) which store the system ner predictons

        use_component: whether to map element and mineral to component

        be_quiet: whether to print out warnings during extraction

        use_sys_ners: whether extract system entities


 This function extract relations from ann files

    Args:
        ann_file: .ann file
        use_component: whether to map element and mineral to component


 This function extracts gold relations with entities in the same sentence

    Args:
        ann_file: .ann file

        corenlp_file: file that stores corenlp's parsing in json file

        doc: dictionary that stores corenlp's parsing

        use_component: whether to map element and mineral to component


    This function extract all pairs of entities from the same sentence as relation candidates. note that here we would get duplicated entity pairs with reverse order, such as (t1, t2) and (t2, t1)

    Args:
        text_file: text_file that contains the journal/abstract

        ann_file: file that contains annotations from brat. used to extract ners

        doc:  a dictionary that stores corenlp's parsing for text_file

        corenlp_file: is a file that stores corenlp's parsing for text_file


    This function extract all pairs of entities in a document as relation candidates. note that here we would get duplicated entity pairs with reverse order, such as (t1, t2) and (t2, t1)

    Args:
        text_file: text_file that contains the journal/abstract

        ann_file: file that contains annotations from brat. used to extract ners

        doc:  a dictionary that stores corenlp's parsing for text_file

        corenlp_file: is a file that stores corenlp's parsing for text_file

        use_component: convert element and mineral to component if True

        use_sys_ners: extract system entities in corenlp_file constructed from the predictions NER model if True. Otherwise use gold entities

        sent_window: maximum number of sentences a pair of entities could be separated by. For example, if 0, then a pair of entities must lie in the same sentence. If 1, then a pair of entities could lie in both the same sentence and adjacent sentences. sent_window >= abs(sent index of entity1 - sent index of entity2). If sent_window is negative, all possible pairs of entities are extracted from a document.


        Args:
            text:
                text of the document

            batch_size:
                batch size at prediction time.

            entity_linking_method:
                strategy to form Contains relations from Targets and Components.

                Options:
                    closest_containee:
                        for each Container instance, link it to its closest Containee instance with a Contains relation
                    closest_container:
                        for each Containee instance, link it to its closest Container instance with a Contains relation
                    closest_component:
                        for each Container instance, link it to its closest Component instance with a Contains relation,
                    closest_target:
                        for each Containee instance, link it to its closest Target instance with a Contains relation
                    union_closest_containee_closest_container:
                        union the relation instances found by closest_containee and closest_container


    Gets canonical name: title case
    :param name - name whose canonical name is to be looked up
    :return canonical name


Move a tensor to a specific gpu depending on self.gpu_id


check how many gold instances could be matched in predicted instances


this function calculates the performance of Containee/Container over the corresponding test set (e.g. to eval Containee, the test set would be a set of Components with label assigned by Containee model)


      This function pads seqeunces of variable lengths to a fixed length

      Args:
        seqs: list of list of numbers

        tensor_type:
          the tensor type of the sequence


    This function extract training, dev and testing component instances from files

    Args:
        tokenizer:
            a bert tokenizer
        ann_files:
            a list of ann files ( used to assign gold labels (binary label for whether the instance is a Containee instance) to component instances)
        text_files:
            a list of text files where component instances would be extracted
        corenlp_files:
            a list of files that store the parsing results of text files from CoreNLP.
        outdir:
            output directory to save the extracted instances
        max_len:
            an integer to indicate the maximum number of tokens to keep for a sentence after bert tokenization (bert allows a list of input tokens with <= 512 tokens )


    Evaluate a trained model over validation set and save if achieves better performance

    Args:
        model:
            a trained model
        val_dataloader:
            a dataloder that contains extracted instances from validation files to predict
        val_gold_ins:
            a list of gold instances from validation files
        best_f1:
            previous best F1 score
        args:
            argument instance
        label_to_eval:
            type of relation to extract (e.g. Contains)
        tupe_level:
            a boolean to indicate whether the evaluation is tuple-level or instance-level
        save_prediction:
            a boolean to indicate whether to save predictions
        use_all_yes:
            a boolean to indicate whether to assign Contains to all extracted instances. This is the all-yes baseline.


    This function uses a trained Containee model to predict whether a component is a Containee instance.

    Args:
        model:
            a trained model
        dataloader:
            a dataloader that contains component instances to predict labels for


Evaluate a trained model over validation set and save if achieves better performance


    This function trains a Containee model

    Args:
        model:
            model to train
        train_dataloder:
            a dataloader that contains training Containee instances
        val_dataloder:
            a dataloader that cotnains extracted component instances from development data
        val_gold_ins:
            a list of gold containee instances from DEV data. This is used to evaluate the model over the  development data (val_dataloader doesn't have gold labels. It only provides component instances for the model to make predictions for).
        args:
            argument parser instance


    This function trains a Container model

    Args:
        model:
            model to train
        train_dataloder:
            a dataloader that contains training Container instances
        val_dataloder:
            a dataloader that cotnains extracted target instances from development data
        val_gold_ins:
            a list of gold container instances from DEV data. This is used to evaluate the model over the  development data (val_dataloader doesn't have gold labels. It only provides target instances for the model to make predictions for).
        args:
            argument parser instance


    This function uses a trained Container model to predict whether a target is a Container instance.

    Args:
        model:
            a trained model
        dataloader:
            a dataloader that contains target instances to predict labels for


    This function extract training, dev and testing target instances from files

    Args:
        tokenizer:
            a bert tokenizer
        ann_files:
            a list of ann files ( used to assign gold labels (binary label for whether the instance is a Container instance) to target instances)
        text_files:
            a list of text files where target instances would be extracted
        corenlp_files:
            a list of files that store the parsing results of text files from CoreNLP.
        outdir:
            output directory to save the extracted instances
        max_len:
            an integer to indicate the maximum number of tokens to keep for a sentence after bert tokenization (bert allows a list of input tokens with <= 512 tokens )
        is_training:
            boolean to indicate whether the extracted instances are used for training or not.
        use_sys_ners:
            boolean to indicate whether system ners instead of gold ners should be used to extract the target instances.


    This function extracts gold relation instances from gold annotation.

    Args:
        ann_files:
            a list of ann files
        text_files:
            a list of text files
        corenlp_files:
            a list of .json files that contains parsing output dictionary from CoreNLP for each text files in text_files.
        outdir:
            output directory


    Loads a data file into a list of `InputBatch`s.
    unused_tokens: whether use [unused1] [unused2] as special tokens


    Prepare data for the relation model
    If training: set use_gold = True


        Search through erence clusters and return the one containing the query entity, if it's
        part of a cluster. If we don't find a match, return None.


        Reparameterization trick to sample from N(mu, var) from
        N(0,1).
        :param mu: (Tensor) Mean of the latent Gaussian [B x D]
        :param logvar: (Tensor) Standard deviation of the latent Gaussian [B x D]
        :return: (Tensor) [B x D]


azimuth between 2 points (interval 0 - 180)


distance between points


	plt.imshow(M,cmap = "jet", origin = "l")
	plt.plot(XK,YK,"kx",markersize = 15)
	plt.plot(xc,yc,"rx",markersize = 15)
	plt.show()


    Converts hex to rgb colours
    value: string of 6 characters representing a hex colour.
    Returns: list length 3 of RGB values


    Converts rgb to decimal colours (i.e. divides each value by 256)
    value: list (length 3) of RGB values
    Returns: list (length 3) of decimal values


Analysis of the inner radius


Analysis of r > r0


		Prior transformation for Dynesty.
		Transforms the uniform random variable `u ~ Unif[0., 1.)`
		to the parameter of interest.


The prior only depends on the parameters


			For emcee and zeus:
			Up to a normalization constant, the log of the posterior pdf is just
			the sum of the log likelihood plus the log prior.


The model evaluation depends only on the parameters


creates gaussian kernel with side length l and a sigma of sig


 INPUT
	2D image
	psf resolution in arcsec
	kernel size in arcsec


\
	creates gaussian kernel with side length l and a sigma of sig


	plt.imshow(vel, origin = "lower")
	plt.plot(pix_x,pix_y,"ko")
	plt.show()


 Return array with completely isolated single cells removed
    :param array: Array with completely isolated single cells
    :param struct: Structure array for generating unique regions
    :return: Array with minimum region size > 1


Does the entire regression calculation for 4 slopes:
OLS(Y|X), OLS(X|Y), bisector, orthogonal.
Fitting form: Y=AX+B.

Usage:

>>> a,b,aerr,berr,covab=bces(x,xerr,y,yerr,cov)

Output:

- a,b : best-fit parameters a,b of the linear regression
- aerr,berr : the standard deviations in a,b
- covab : the covariance between a and b (e.g. for plotting confidence bands)

Arguments:

- x,y : data
- xerr,yerr: measurement errors affecting x and y
- cov : covariance between the measurement errors
(all are arrays)


Constructs Monte Carlo simulated data set using the
Bootstrap algorithm.

Usage:

>>> bootstrap(x)

where x is either an array or a list of arrays. If it is a
list, the code returns the corresponding list of bootstrapped
arrays assuming that the same position in these arrays map the
same "physical" object.


Does the BCES with bootstrapping.

Usage:

>>> a,b,aerr,berr,covab=bcesboot(x,xerr,y,yerr,cov,nsim)

:param x,y: data
:param xerr,yerr: measurement errors affecting x and y
:param cov: covariance between the measurement errors (all are arrays)
:param nsim: number of Monte Carlo simulations (bootstraps)

:returns: a,b -- best-fit parameters a,b of the linear regression
:returns: aerr,berr -- the standard deviations in a,b
:returns: covab -- the covariance between a and b (e.g. for plotting confidence bands)

.. note:: this method is definitely not nearly as fast as bces_regress.f. Needs to be optimized. Maybe adapt the fortran routine using f2python?


	Sometimes, if the dataset is very small, the regression parameters in
	some instances of the bootstrapped sample may have NaNs i.e. failed
	regression (I need to investigate this in more details).

	This method checks to see if there are NaNs in the bootstrapped
	fits and remove them from the final sample.


Check if all elements in an array are equal.
Returns True if they are all the same.


This method is the big bottleneck of the parallel BCES code. That's the
reason why I put these calculations in a separate method, in order to
distribute this among the cores. In the original BCES method, this is
inside the main routine.

Argument:
[y1,y1err,y2,y2err,cerr,nsim]
where nsim is the number of bootstrapping trials sent to each core.

:returns: am,bm : the matrixes with slope and intercept where each line corresponds to a bootrap trial and each column maps a different BCES method (ort, y|x etc).

Be very careful and do not use lambda functions when calling this
method and passing it to multiprocessing or ipython.parallel!
I spent >2 hours figuring out why the code was not working until I
realized the reason was the use of lambda functions.


Parallel implementation of the BCES with bootstrapping.
Divide the bootstraps equally among the threads (cores) of
the machine. It will automatically detect the number of
cores available.

Usage:

>>> a,b,aerr,berr,covab=bcesp(x,xerr,y,yerr,cov,nsim)

:param x,y: data
:param xerr,yerr: measurement errors affecting x and y
:param cov: covariance between the measurement errors (all are arrays)
:param nsim: number of Monte Carlo simulations (bootstraps)

:returns: a,b - best-fit parameters a,b of the linear regression
:returns: aerr,berr - the standard deviations in a,b
:returns: covab - the covariance between a and b (e.g. for plotting confidence bands)

.. seealso:: Check out ~/work/projects/playground/parallel python/bcesp.py for the original, testing, code. I deleted some line from there to make the "production" version.

* v1 Mar 2012: serial version ported from bces_regress.f. Added covariance output.
* v2 May 3rd 2012: parallel version ported from nemmen.bcesboot.

.. codeauthor: Rodrigo Nemmen


Plot the Gaia sources in TPFs, including their space motion.


Calculate the contamination for a target
    Parameters
    ----------
    period : float
        Period of transiting object in days
    t0 : float
        Transit midpoint of transiting object in days
    duration : float
        Duration of transit in days
    sigma : float
        The significance level at which to create an aperture for the contaminanting source.
        If the apertures are large, try increasing sigma. If the apertures are small,
        or contaminante fails, you could try (slightly) lowering sigma.
    plot: bool
        If True, will generate a figure
    cbvs : bool
        If True, will use Kepler/TESS CBVs to detrend. Default is True
    sff : bool
        If True, will use the SFF method to correct variability. Default is False.
    spline_period : float
        The period of a spline to fit. For short period variability,
        set this value to a smaller number. Default is 0.75 days.

    Returns
    -------
    result : list of dict
        List of dictionaries containing the contamination properties
        If plot is True, will show a figure, and will put the
        matplotlib.pyplot.figure object into the result dictionary.


Helper function for packaging up results


Build a design matrix to model pixel in target pixel files

    Parameters
    ----------
    tpf : lightkurve.TargetPixelFile
        Input target pixel file to make the design matrix for
    flux : np.ndarray
        The SAP flux to use for creating the design matrix
    t_model: None or np.ndarray
        The transit model, if None no transit model will be used in the design matrix
    cbvs: None or np.ndarray
        Cotrending Basis vectors. If None will not be used in design matrix
    spline: bool
        Whether to use a B-Spline in time
    spline_period: float
        If using a spline, what time period the knots should be spaced at

    Returns
    -------
    SA : scipy.sparse.csr_matrix
        The design matrix to use to detrend the input TPF


Helper function for making a plot of contamination results


Lifted from lightkurve.

    Creates a contiguous region where a "thumnbnail" is greater than some threshold
    ----------
    thumb : np.ndarray
        2D image, in this case the transit depth in every pixel divided by the
        error.
    threshold : float
        A value for the number of sigma by which a pixel needs to be
        brighter than the median flux to be included in the aperture mask.
    reference_pixel: (int, int) tuple, 'center', 'max', or None
        (col, row) pixel coordinate closest to the desired region.
        In this case we use the maximum of the thumbnail.
    Returns
    -------
    aperture_mask : ndarray
        2D boolean numpy array containing `True` for pixels above the
        threshold.


 Generates params along a 1d line for aligned-spin params.
        The given x_param is varied but all other params are kept const at
        some randomly chosen values.
        For each of the aligned-spin params:
            if x_param is this particular param, returns a uniform list of
                values in the range of this param. Also saves this list as
                x_list.
            else, returns a list, each element of which is the same, a
                randomly chosen value in the range of this param.
        Also returns a label with all the fixed params.


 Generates params along a 1d line for 7d params.
        The given x_param is varied but all other params are kept const at
        some randomly chosen values.
        For each of the 7d params:
            if x_param is this particular param, returns a uniform list of
                values in the range of this param. Also saves this list as
                x_list.
            else, returns a list, each element of which is the same, a
                randomly chosen value in the range of this param.
        Also returns a label with all the fixed params.


Get frequency and spherical-spheroidal mixing from qnm package

    Parameters
    ----------
    tup : tuple
        Index (ell,m,n,sign) of QNM

    chi : float
        The dimensionless spin of the black hole, 0. <= chi < 1.

    M : float
        The mass of the remnant black hole, M > 0.

    s : int, optional [Default: -2]

    Returns
    -------
    omega: complex
        Frequency of QNM, in units of inverse initial total mass M

    C: complex ndarray
        Spherical-spheroidal decomposition coefficient array

    ells: ndarray
        List of ell values for the spherical-spheroidal mixing array


q1, q2 must be [scalar, x, y, z] but those may be arrays or scalars


Returns a unit quaternion that will align vec with the z-axis


Given (for example) a minimal rotation frame quat, transforms
    vec from the minimal rotation frame to the inertial frame.
    With inverse=1, transforms from the inertial frame to the minimal
    rotation frame.


For transforming spins between the coprecessing and coorbital frames


Given a vector (of size 3) in coorbital frame, orbital phase in
    coprecessing frame and a minimal rotation frame quat, transforms
    the vector from the coorbital to the LAL inertial frame.


 Transform error in a vector from the coorbital frame to the inertial
    frame. Generates distributions in the coorbital frame, transforms them
    to inertial frame and returns 1-simga widths in the inertial frame.


    Inputs:
        approximant:    'SpinTaylorT1/T2/T4'
        q:              Mass ratio (q>=1)
        omega0:         Initial orbital frequency in dimless units.
        chiA0:          Dimless spin of BhA at initial freq.
        chiB0:          Dimless spin of BhB at initial freq.
        dt:             Dimless step time for evolution.
        spinO:          Twice PN order of spin effects.
        phaseO:         Twice PN order in phase.

    Outputs (all are time series):
        Omega:    Dimensionless orbital frequency.
        Phi:            Orbital phase (radians)
        ChiA:           Dimensionless spin of BhA
        ChiB:           Dimensionless spin of BhB
        LNhat:          Orbital angular momentum direction
        E1:             Orbital plane basis vector

    The frame is defined at the initial frequency, as follows:
        z-axis is set by the orbital angular momentum direction.
        x-axis is the separation vector from BhB to BhA.
        y-axis completes the triad by right-hand rule.
        All quantities are defined in this fixed frame, including initial spins,
        returned spins, other vectors like LNhat, etc.


 Evolves PN spins from a starting orbital frequency and spins to a final
    frequency.

    Inputs:
        q:                  Mass ratio (q>=1)
        chiA0:              Dimless spin of BhA at initial freq.
        chiB0:              Dimless spin of BhB at initial freq.
        omega0:       Initial orbital frequency in dimless units.
        omegaTimesM_final:  Final orbital frequency in dimless units.
        approximant:        'SpinTaylorT1/T2/T4'. Default: 'SpinTaylorT4'.
        dt:        Dimless step time for evolution. Default: 0.1 .
        spinO:              Twice PN order of spin effects. Default: 5 .
        phaseO:             Twice PN order in phase. Default: 8 .

    Outputs (all are time series):
        chiA_end_copr:      Spin of BhA at final frequency, in coprecessing
                                frame.
        chiB_end_copr:      Spin of BhB at final frequency, in coprecessing
                                frame.
        q_copr_end:         Coprecessing frame quaternion at final frequency.
        phi_end:            Orbital phase in the coprecessing frame at final
                                frequency.
        omegaTimesM_end     Dimensionless final frequency. Should agree with
                                omegaTimesM_final.

    The inertial frame is assumed to be aligned
    to the coorbital frame at orbital frequency = omega0. chiA0 and chiB0
    are the inertial/coorbital frame spins at omega0.


 Loads data for a fit.
    If data is not available, downloads it before loading.


 Downloads fit data to DataPath() diretory.
        If name='all', gets all fit data.


Converts h5 groups to dictionaries


Loads a single fit


Loads a vector of fits


 Evaluates a particular fit by passing fit_key to self.fits.
            Assumes self._get_fit_params() has been overriden.


 Call this at the end of call module to check if all the kwargs have
        been used. Assumes kwargs were extracted using pop.


 Checks that params are within allowed range of paramters.
        Raises a warning if outside self.soft_param_lims limits and
        raises an error if outside self.hard_param_lims.
        If allow_extrap=True, skips these checks.


 Add additional kwargs for regression tests. If not overriden,
            this will be empty. See _fit_evaluators.fit_7dq2.py for an example.


 Maps from input params x to the fit_params used to evaluate the
            fit.


 Evaluates a particular fit. This varies for each surrogate.
            Allowed values for fit_key are 'mf', 'chif' and 'vf' and 'all'.
            chiA and chiB should have size 3.

            Each derived class should have its own _eval_wrapper function but
            call self._check_param_limits() first to do some sanity checks.
            See _fit_evaluators.fit_7dq2.py for an example.


 Evaluates fit and 1-sigma error estimate for remnant mass.
        Returns:
            mf, mf_err_est


 Evaluates fit and 1-sigma error estimate for remnant spin.
        Returns:
            chif, chif_err_est

        chif and chif_err_est are arrays of size 3.


 Evaluates fit and 1-sigma error estimate for remnant kick velocity.
        Returns:
            vf, vf_err_est

        vf and vf_err_est are arrays of size 3.


 Evaluates fit and 1-sigma error estimate for remnant mass, spin
        and kick velocity.
        Returns:
            mf, chif, vf, mf_err_est, chif_err_est, vf_err_est

        chif, vf, chif_err_est and vf_err_est are arrays of size 3.

        In the case of NRsur3dq8BMSRemnant evaluates fit and 1-sigma error estimate for the
        supertranslation parameter's modes and boost velocity of the BMS transformation from the PN
        BMS frame to the remnant BMS frame.
        Returns:
            alpha, boost_vel, alpha_err, boost_vel_err

            alpha, alpha_err complex arrays of spherical harmonics modes from ell = 0 to ell = 8 with spherical_function package mode ordering.
            [(0,0),(1,-1),(1,0),(1,1),(2,-2),...,(8,8)]

            boost_vel, boost_vel_err are arrays of size 3.


Utility function to convert (l,m,n,p)
        into the pair e.g. ("A_l,m,n,p_r", "A_l,m,n,p_i")


Loads fits from h5file and returns a dictionary of fits.


 Transforms the input parameter to fit parameters for the 3dq8 model.
    That is, maps from [q, chiAz, chiBz] to [np.log(q), chiHat, chi_a]
    chiHat is defined in Eq.(3) of 1508.07253.
    chi_a = (chiAz - chiBz)/2.


 Evaluates fit and 1-sigma error estimate for remnant mass, spin,
        and QNM amplitudes.
        Returns:
            mf, chif, QNM_dict, mf_err_est, chif_err_est, QNM_err_est_dict

        chif and chif_err_est are only the spin magnitude.


Evaluates the NRSur3dq8_RD model.


List of additional kwargs to use in regression tests.


 Transforms the input parameter to fit parameters for the 7dq2 model.
    That is, maps from
    x = [q, chiAx, chiAy, chiAz, chiBx, chiBy, chiBz]
    fit_params = [np.log(q), chiAx, chiAy, chiHat, chiBx, chiBy, chi_a]

    chiHat is defined in Eq.(3) of 1508.07253, but with chiAz and chiBz instead
    of chiA and chiB.
    chi_a = (chiAz - chiBz)/2.


 Evolves spins of the component BHs from an initial orbital
        frequency = omega0 until t=-100 M from the peak of the waveform.
        If omega0 < omega0_nrsur, use PN to evolve the spins until
        orbital frequency = omega0. Then evolves further with the NRSur7dq2
        waveform model until t=-100M from the peak.

        Assumes chiA0 and chiB0 are defined in the inertial frame defined
        at orbital frequency = omega0 as:
            The z-axis is along the Newtonian orbital angular momentum when the
                PN orbital frequency = omega0.
            The x-axis is along the line of separation from the smaller BH to
                the larger BH at this frequency.
            The y-axis completes the triad.

        Returns spins in the coorbital frame at t=-100M, as well as the
        coprecessing frame quaternion and orbital phase in the coprecessing
        frame at this time.


Evaluates the surfinBH7dq2 model.


Evaluates the NRSur3dq8Remnant model.


 Transforms the input parameter to fit parameters for the 7dq4 model.
    That is, maps from
    x = [q, chiAx, chiAy, chiAz, chiBx, chiBy, chiBz]
    fit_params = [np.log(q), chiAx, chiAy, chiHat, chiBx, chiBy, chi_a]

    chiHat is defined in Eq.(3) of 1508.07253, but with chiAz and chiBz instead
    of chiA and chiB.
    chi_a = (chiAz - chiBz)/2.


 Computes PN spins and dynamics at a given idx.

        Inputs:
            chiA:       Dimless spin evolution of BhA in inertial frame.
            chiB:       Dimless spin evolution of BhB in inertial frame.
            omega:      Orbital frequency evolution in dimless units.
            lNhat:      Orbital angular momentum direction evolution.
            phi:        Orbital phase evolution.
            idx:        Index for output.

        Outputs (all are time series):
            chiA_at_idx_coorb:   Spin of BhA at idx, in coorbital frame.
            chiB_at_idx_coorb:   Spin of BhB at idx, in coorbital frame.
            quat_copr_at_idx:   Coprecessing frame quaternion at idx.
            phi_at_idx:         Orbital phase in the coprecessing frame at idx.
            omega_at_idx        Dimensionless orbital frequency at idx.

        The inertial frame is assumed to be aligned to the coorbital frame at
        the first index.


 Computes PN spins and frame dynamics at a time close to the start
            of the surrogate waveform model.

            Generates PN spins and frame quantities using spins at omega0.
            Then uses the PN spins at omega_switch_IG to generate the surrogate
            dynamics.
            Then gets the surrogate orbital frequency at t_sur_switch, let's
            call this omega_init_sur.
            Then use the PN spins at omega_init_sur to regenerate the surrogate
            dynamics.


 Evolves spins of the component BHs from an initial orbital
        frequency = omega0 until t=-100 M from the peak of the waveform.  If
        omega0 < omega_switch_IG, use PN to evolve the spins until
        t=t_sur_switch. Then evolves further with the NRSur7dq4 waveform model
        until t=-100M from the peak.

        Returns spins in the coorbital frame at t=-100M, as well as the
        coprecessing frame quaternion and orbital phase in the coprecessing
        frame at this time.

        If return_spin_evolution is given, also returns the PN and surrogate
        spin times series.


Evaluates the NRSur7dq4Remnant model.


 Transforms the input parameter to fit parameters for the 7dq4Emri
    model.
    That is, maps from
    x = [q, chiAx, chiAy, chiAz, chiBx, chiBy, chiBz]
    fit_params = [np.log(q), chiAx, chiAy, chiHat, chiBx, chiBy, chi_a]

    chiHat is defined in Eq.(3) of 1508.07253, but with chiAz and chiBz instead
    of chiA and chiB.
    chi_a = (chiAz - chiBz)/2.


Evaluates the NRSur7dq4EmriRemnant model.


            Estimate ISCO radius following Eq. (2.21) by Bardeen et al.
            (https://doi.org/10.1086/151796)


            Compute remnant spin for EMRI binary following Eq. (7)
            presented in THE PAPER.


            The model evaluates remnant spin using GPR fit up to the upper bound
            of the EMRI training region (q = 1000). At q > 1000, it returns the
            expected EMRI limit (Eq. (7) in THE PAPER). There is a transition
            function (Eq. (9) in THE PAPER) connecting smoothly these
            two regions. The transition takes place from q=1000 to q=2000.


 Transforms the input parameter to fit parameters for the 3dq8BMS model.
    That is, maps from [q, chiAz, chiBz] to [np.log(q), chiHat, chi_a]
    chiHat is defined in Eq.(3) of 1508.07253.
    chi_a = (chiAz - chiBz)/2.


 Evaluates fit and 1-sigma error estimate for supertranslation parameter
        alpha, and boost velocity of the BMS transformation from the inspiral BMS
        frame to the remnant BMS frame.
        Returns:
            alpha, boost,  alpha_err, boost_err


Evaluates the NRSur3dq8BMSRemnant model.


    Parameters
    ----------
    geom : a Geometry object from megaman.geometry.geometry
    n_components : integer, optional
        The dimension of the projection subspace.
    eigen_solver : {'auto', 'dense', 'arpack', 'lobpcg', or 'amg'}
        'auto' :
            algorithm will attempt to choose the best method for input data
        'dense' :
            use standard dense matrix operations for the eigenvalue decomposition.
            For this method, M must be an array or matrix type.  This method should be avoided for large problems.
        'arpack' :
            use arnoldi iteration in shift-invert mode. For this method,
            M may be a dense matrix, sparse matrix, or general linear operator.
            Warning: ARPACK can be unstable for some problems.  It is best to
            try several random seeds in order to check results.
        'lobpcg' :
            Locally Optimal Block Preconditioned Conjugate Gradient Method.
            A preconditioned eigensolver for large symmetric positive definite
            (SPD) generalized eigenproblems.
        'amg' :
            AMG requires pyamg to be installed. It can be faster on very large,
            sparse problems, but may also lead to instabilities.
    random_state : int seed, RandomState instance, or None (default)
        A pseudo random number generator used for the initialization of the
        lobpcg eigen vectors decomposition when eigen_solver == 'amg'.
        By default, arpack is used.
    path_method : string, method for computing graph shortest path. One of :
        'auto', 'D', 'FW', 'BF', 'J'. See scipy.sparse.csgraph.shortest_path
        for more information.
    distance_matrix : sparse Ndarray (n_obs, n_obs), optional. Pairwise distance matrix
        sparse zeros considered 'infinite'.
    graph_distance_matrix : Ndarray (n_obs, n_obs), optional. Pairwise graph distance
        matrix. Output of graph_shortest_path.
    centered_matrix : Ndarray (n_obs, n_obs), optional. Centered version of
        graph_distance_matrix
    solver_kwds : any additional keyword arguments to pass to the selected eigen_solver

    Returns
    -------
    embedding : array, shape=(n_samples, n_components)
        The reduced samples.

    Notes
    -----


Fit the model from data in X.

        Parameters
        ----------
        input_type : string, one of: 'data', 'distance'.
            The values of input data X. (default = 'data')

        X : array-like, shape (n_samples, n_features)
            Training vector, where n_samples in the number of samples
            and n_features is the number of features.

        If self.input_type is 'distance':

        X : array-like, shape (n_samples, n_samples),
            Interpret X as precomputed distance or adjacency graph
            computed from samples.

        eigen_solver : {None, 'arpack', 'lobpcg', or 'amg'}
            The eigenvalue decomposition strategy to use. AMG requires pyamg
            to be installed. It can be faster on very large, sparse problems,
            but may also lead to instabilities.

        Returns
        -------
        self : object
            Returns the instance itself.


Inputs self.geom, and produces the fitted geometry self.geom_


Fit the model from data in X and transform X.

        Parameters
        ----------
        input_type : string, one of: 'data', 'distance' or 'affinity'.
            The values of input data X. (default = 'data')
        X: array-like, shape (n_samples, n_features)
            Training vector, where n_samples in the number of samples
            and n_features is the number of features.

        If self.input_type is 'distance':

        X : array-like, shape (n_samples, n_samples),
            Interpret X as precomputed distance or adjacency graph
            computed from samples.

        Returns
        -------
        X_new: array-like, shape (n_samples, n_components)


    Computes the barycenter weighted graph for points in X

    Parameters
    ----------
    distance_matrix: sparse Ndarray, (N_obs, N_obs) pairwise distance matrix.
    X : Ndarray (N_obs, N_dim) observed data matrix.
    reg : float, optional
        Amount of regularization when solving the least-squares
        problem. Only relevant if mode='barycenter'. If None, use the
        default.

    Returns
    -------
    W : sparse matrix in CSR format, shape = [n_samples, n_samples]
        W[i, j] is assigned the weight of edge that connects i to j.


    Perform a Locally Linear Embedding analysis on the data.

    Parameters
    ----------
    geom : a Geometry object from megaman.geometry.geometry
    n_components : integer
        number of coordinates for the manifold.
    reg : float
        regularization constant, multiplies the trace of the local covariance
        matrix of the distances.
    eigen_solver : {'auto', 'dense', 'arpack', 'lobpcg', or 'amg'}
        'auto' :
            algorithm will attempt to choose the best method for input data
        'dense' :
            use standard dense matrix operations for the eigenvalue decomposition.
            For this method, M must be an array or matrix type.  This method should be avoided for large problems.
        'arpack' :
            use arnoldi iteration in shift-invert mode. For this method,
            M may be a dense matrix, sparse matrix, or general linear operator.
            Warning: ARPACK can be unstable for some problems.  It is best to
            try several random seeds in order to check results.
        'lobpcg' :
            Locally Optimal Block Preconditioned Conjugate Gradient Method.
            A preconditioned eigensolver for large symmetric positive definite
            (SPD) generalized eigenproblems.
        'amg' :
            AMG requires pyamg to be installed. It can be faster on very large,
            sparse problems, but may also lead to instabilities.
    random_state : numpy.RandomState or int, optional
        The generator or seed used to determine the starting vector for arpack
        iterations.  Defaults to numpy.random.
    solver_kwds : any additional keyword arguments to pass to the selected eigen_solver

    Returns
    -------
    Y : array-like, shape [n_samples, n_components]
        Embedding vectors.
    squared_error : float
        Reconstruction error for the embedding vectors. Equivalent to
        ``norm(Y - W Y, 'fro')**2``, where W are the reconstruction weights.

    References
    ----------

    .. [1] Roweis, S. & Saul, L. Nonlinear dimensionality reduction
        by locally linear embedding.  Science 290:2323 (2000).


Fit the model from data in X.

        Parameters
        ----------
        input_type : string, one of: 'data', 'distance'.
            The values of input data X. (default = 'data')
        X : array-like, shape (n_samples, n_features)
            Training vector, where n_samples in the number of samples
            and n_features is the number of features.

        If self.input_type is 'distance':

        X : array-like, shape (n_samples, n_samples),
            Interpret X as precomputed distance or adjacency graph
            computed from samples.

        Returns
        -------
        self : object
            Returns the instance itself.


    Perform a Local Tangent Space Alignment analysis on the data.

    Parameters
    ----------
    geom : a Geometry object from megaman.geometry.geometry
    n_components : integer
        number of coordinates for the manifold.
    eigen_solver : {'auto', 'dense', 'arpack', 'lobpcg', or 'amg'}
        'auto' :
            algorithm will attempt to choose the best method for input data
        'dense' :
            use standard dense matrix operations for the eigenvalue decomposition.
            For this method, M must be an array or matrix type.  This method should be avoided for large problems.
        'arpack' :
            use arnoldi iteration in shift-invert mode. For this method,
            M may be a dense matrix, sparse matrix, or general linear operator.
            Warning: ARPACK can be unstable for some problems.  It is best to
            try several random seeds in order to check results.
        'lobpcg' :
            Locally Optimal Block Preconditioned Conjugate Gradient Method.
            A preconditioned eigensolver for large symmetric positive definite
            (SPD) generalized eigenproblems.
        'amg' :
            AMG requires pyamg to be installed. It can be faster on very large,
            sparse problems, but may also lead to instabilities.
    random_state : numpy.RandomState or int, optional
        The generator or seed used to determine the starting vector for arpack
        iterations.  Defaults to numpy.random.
    solver_kwds : any additional keyword arguments to pass to the selected eigen_solver

    Returns
    -------
    embedding : array-like, shape [n_samples, n_components]
        Embedding vectors.
    squared_error : float
        Reconstruction error for the embedding vectors. Equivalent to
        ``norm(Y - W Y, 'fro')**2``, where W are the reconstruction weights.

    References
    ----------
    * Zhang, Z. & Zha, H. Principal manifolds and nonlinear
      dimensionality reduction via tangent space alignment.
      Journal of Shanghai Univ.  8:406 (2004)


Fit the model from data in X.

        Parameters
        ----------
        input_type : string, one of: 'data', 'distance'.
            The values of input data X. (default = 'data')
        X : array-like, shape (n_samples, n_features)
            Training vector, where n_samples in the number of samples
            and n_features is the number of features.

        If self.input_type is 'distance', or 'affinity':

        X : array-like, shape (n_samples, n_samples),
            Interpret X as precomputed distance or adjacency graph
            computed from samples.

        Returns
        -------
        self : object
            Returns the instance itself.


    Find the largest graph connected components the contains one
    given node

    Parameters
    ----------
    graph : array-like, shape: (n_samples, n_samples)
        adjacency matrix of the graph, non-zero weight means an edge
        between the nodes

    node_id : int
        The index of the query node of the graph

    Returns
    -------
    connected_components : array-like, shape: (n_samples,)
        An array of bool value indicates the indexes of the nodes
        belong to the largest connected components of the given query
        node


    Return whether the graph is connected (True) or Not (False)

    Parameters
    ----------
    graph : array-like or sparse matrix, shape: (n_samples, n_samples)
        adjacency matrix of the graph, non-zero weight means an edge
        between the nodes

    Returns
    -------
    is_connected : bool
        True means the graph is fully connected and False means not


Credit to Satrajit Ghosh (http://satra.cogitatum.org/) for final steps


    Project the sample on the first eigen vectors of the graph Laplacian.

    The adjacency matrix is used to compute a normalized graph Laplacian
    whose  principal eigenvectors (associated to the
    smallest eigen values) represent the embedding coordinates of the data.

    The ``adjacency`` variable is not strictly the adjacency matrix of a graph but more generally
    an affinity or similarity matrix between samples (for instance the
    heat kernel of a euclidean distance matrix or a k-NN matrix).
    The Laplacian must be symmetric so that the eigen vector decomposition works as expected.
    This is ensured by the default setting (for more details,
    see the documentation in geometry.py).

    The data and generic geometric parameters are passed via a Geometry object, which also
    computes the Laplacian. By default, the 'geometric' Laplacian (or "debiased", or "renormalized" with
    alpha=1) is used. This is the Laplacian construction defined in [Coifman and Lafon, 2006] (see also
    documentation in laplacian.py). Thus, with diffusion_maps=False, spectral embedding is a modification
    of the Laplacian Eigenmaps algorithm of [Belkin and Nyiogi, 2002], with diffusion_maps=False, geom.laplacian_method
    ='symmetricnormalized' it is exactly the Laplacian Eigenmaps, with diffusion_maps=True, diffusion_time>0 it
    is the Diffusion Maps algorithm of [Coifman and Lafon 2006]; diffusion_maps=True and diffusion_time=0 is the same
    as diffusion_maps=False and default geom.laplacian_method.

    Parameters
    ----------
    geom : a Geometry object from megaman.embedding.geometry
    n_components : integer, optional
        The dimension of the projection subspace.
    eigen_solver : {'auto', 'dense', 'arpack', 'lobpcg', or 'amg'}
        'auto' :
            algorithm will attempt to choose the best method for input data
        'dense' :
            use standard dense matrix operations for the eigenvalue decomposition.
            For this method, M must be an array or matrix type.  This method should be avoided for large problems.
        'arpack' :
            use arnoldi iteration in shift-invert mode. For this method,
            M may be a dense matrix, sparse matrix, or general linear operator.
            Warning: ARPACK can be unstable for some problems.  It is best to
            try several random seeds in order to check results.
        'lobpcg' :
            Locally Optimal Block Preconditioned Conjugate Gradient Method.
            A preconditioned eigensolver for large symmetric positive definite
            (SPD) generalized eigenproblems.
        'amg' :
            AMG requires pyamg to be installed. It can be faster on very large,
            sparse problems, but may also lead to instabilities.
    random_state : int seed, RandomState instance, or None (default)
        A pseudo random number generator used for the initialization of the
        lobpcg eigen vectors decomposition when eigen_solver == 'amg'.
        By default, arpack is used.
    drop_first : bool, optional, default=True
        Whether to drop the first eigenvector. For spectral embedding, this
        should be True as the first eigenvector should be constant vector for
        connected graph, but for spectral clustering, this should be kept as
        False to retain the first eigenvector.
    diffusion_map : boolean, optional. Whether to return the diffusion map
        version by re-scaling the embedding coordinate by the eigenvalues to the power
        diffusion_time.
    diffusion_time: if diffusion_map=True, the eigenvectors of the Laplacian are rescaled by
        (1-lambda)^diffusion_time, where lambda is the corresponding eigenvalue.
        diffusion_time has the role of scale parameter. One of the main ideas of diffusion framework is
        that running the diffusion forward in time (taking larger and larger
        powers of the Laplacian/transition matrix) reveals the geometric structure of X at larger and
        larger scales (the diffusion process).
        diffusion_time = 0 empirically provides a reasonable balance from a clustering
        perspective. Specifically, the notion of a cluster in the data set
        is quantified as a region in which the probability of escaping this
        region is low (within a certain time t).
        Credit to Satrajit Ghosh (http://satra.cogitatum.org/) for description
    solver_kwds : any additional keyword arguments to pass to the selected eigen_solver

    Returns
    -------
    embedding : array, shape=(n_samples, n_components)
        The reduced samples.

    Notes
    -----
    Spectral embedding is most useful when the graph has one connected
    component. If there graph has many components, the first few eigenvectors
    will simply uncover the connected components of the graph.

    References
    ----------
    * http://en.wikipedia.org/wiki/LOBPCG

    * Toward the Optimal Preconditioned Eigensolver: Locally Optimal
      Block Preconditioned Conjugate Gradient Method
      Andrew V. Knyazev
      http://dx.doi.org/10.1137%2FS1064827500366124


        Fit the model from data in X.

        Parameters
        ----------
        input_type : string, one of: 'data', 'distance' or 'affinity'.
            The values of input data X. (default = 'data')
        X : array-like, shape (n_samples, n_features)
            Training vector, where n_samples in the number of samples
            and n_features is the number of features.

        If self.input_type is distance, or affinity:

        X : array-like, shape (n_samples, n_samples),
            Interpret X as precomputed distance or adjacency graph
            computed from samples.

        Returns
        -------
        self : object
               Returns the instance itself.


        Predict embedding on new data X_test given the existing embedding on training data

        Uses the Nystrom Extension to estimate the eigenvectors.

        Currently only works with input_type data (i.e. not affinity or distance)


 Check array A and B are equal with possible sign flipping on
    each columns


    Plots an `nstd` sigma ellipse based on the mean and covariance of a point
    "cloud" (points, an Nx2 array).

    Parameters
    ----------
        points : An Nx2 array of the data points.
        nstd : The radius of the ellipse in numbers of standard deviations.
            Defaults to 2 standard deviations.
        ax : The axis that the ellipse will be plotted on. Defaults to the
            current axis.
        Additional keyword arguments are pass on to the ellipse patch.

    Returns
    -------
        A matplotlib ellipse artist


    Plots an `nstd` sigma error ellipse based on the specified covariance
    matrix (`cov`). Additional keyword arguments are passed on to the
    ellipse patch artist.

    Parameters
    ----------
        cov : The 2x2 covariance matrix to base the ellipse on
        pos : The location of the center of the ellipse. Expects a 2-element
            sequence of [x0, y0].
        nstd : The radius of the ellipse in numbers of standard deviations.
            Defaults to 2 standard deviations.
        ax : The axis that the ellipse will be plotted on. Defaults to the
            current axis.
        Additional keyword arguments are pass on to the ellipse patch.

    Returns
    -------
        A matplotlib ellipse artist


Safe way to reset warnings


Helper function to test error messages in exceptions
    Parameters
    ----------
    exceptions : exception or tuple of exception
        Name of the estimator
    func : callable
        Calable object to raise error
    *args : the positional arguments to `func`.
    **kw : the keyword arguments to `func`


Test that a certain warning occurs.
    Parameters
    ----------
    warning_class : the warning class
        The class to test for, e.g. UserWarning.
    func : callable
        Calable object to trigger warnings.
    *args : the positional arguments to `func`.
    **kw : the keyword arguments to `func`
    Returns
    -------
    result : the return value of `func`


 Context manager and decorator to ignore warnings
    Note. Using this (in both variants) will clear all warnings
    from all python modules loaded. In case you need to test
    cross-module-warning-logging this is not your tool of choice.
    Examples
    --------
    >>> with ignore_warnings():
    ...     warnings.warn('buhuhuhu')
    >>> def nasty_warn():
    ...    warnings.warn('buhuhuhu')
    ...    print(42)
    >>> ignore_warnings(nasty_warn)()
    42


Decorator to catch and hide warnings without visual nesting


Check that the selected eigensolver is valid

    Parameters
    ----------
    eigen_solver : string
        string value to validate
    size, nvec : int (optional)
        if both provided, use the specified problem size and number of vectors
        to determine the optimal method to use with eigen_solver='auto'

    Returns
    -------
    eigen_solver : string
        The eigen solver. This only differs from the input if
        eigen_solver == 'auto' and `size` is specified.


    Function to compute the eigendecomposition of a square matrix.

    Parameters
    ----------
    G : array_like or sparse matrix
        The square matrix for which to compute the eigen-decomposition.
    n_components : integer, optional
        The number of eigenvectors to return
    eigen_solver : {'auto', 'dense', 'arpack', 'lobpcg', or 'amg'}
        'auto' :
            attempt to choose the best method for input data (default)
        'dense' :
            use standard dense matrix operations for the eigenvalue decomposition.
            For this method, M must be an array or matrix type.
            This method should be avoided for large problems.
        'arpack' :
            use arnoldi iteration in shift-invert mode. For this method,
            M may be a dense matrix, sparse matrix, or general linear operator.
            Warning: ARPACK can be unstable for some problems.  It is best to
            try several random seeds in order to check results.
        'lobpcg' :
            Locally Optimal Block Preconditioned Conjugate Gradient Method.
            A preconditioned eigensolver for large symmetric positive definite
            (SPD) generalized eigenproblems.
        'amg' :
            Algebraic Multigrid solver (requires ``pyamg`` to be installed)
            It can be faster on very large, sparse problems, but may also lead
            to instabilities.
    random_state : int seed, RandomState instance, or None (default)
        A pseudo random number generator used for the initialization of the
        lobpcg eigen vectors decomposition when eigen_solver == 'amg'.
        By default, arpack is used.
    solver_kwds : any additional keyword arguments to pass to the selected eigen_solver

    Returns
    -------
    lambdas, diffusion_map : eigenvalues, eigenvectors


    Find the null space of a matrix M: eigenvectors associated with 0 eigenvalues

    Parameters
    ----------
    M : {array, matrix, sparse matrix, LinearOperator}
        Input covariance matrix: should be symmetric positive semi-definite
    k : integer
        Number of eigenvalues/vectors to return
    k_skip : integer, optional
        Number of low eigenvalues to skip.
    eigen_solver : {'auto', 'dense', 'arpack', 'lobpcg', or 'amg'}
        'auto' :
            algorithm will attempt to choose the best method for input data
        'dense' :
            use standard dense matrix operations for the eigenvalue decomposition.
            For this method, M must be an array or matrix type.  This method should be avoided for large problems.
        'arpack' :
            use arnoldi iteration in shift-invert mode. For this method,
            M may be a dense matrix, sparse matrix, or general linear operator.
            Warning: ARPACK can be unstable for some problems.  It is best to
            try several random seeds in order to check results.
        'lobpcg' :
            Locally Optimal Block Preconditioned Conjugate Gradient Method.
            A preconditioned eigensolver for large symmetric positive definite
            (SPD) generalized eigenproblems.
        'amg' :
            AMG requires pyamg to be installed. It can be faster on very large,
            sparse problems, but may also lead to instabilities.
    random_state: numpy.RandomState or int, optional
        The generator or seed used to determine the starting vector for arpack
        iterations.  Defaults to numpy.random.
    solver_kwds : any additional keyword arguments to pass to the selected eigen_solver

    Returns
    -------
    null_space : estimated k vectors of the null space
    error : estimated error (sum of eigenvalues)

    Notes
    -----
    dense solver key words: see
        http://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.linalg.eigh.html
        for symmetric problems and
        http://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.linalg.eig.html#scipy.linalg.eig
        for non symmetric problems.
    arpack sovler key words: see
        http://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.sparse.linalg.eigsh.html
        for symmetric problems and http://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.sparse.linalg.eigs.html#scipy.sparse.linalg.eigs
        for non symmetric problems.
    lobpcg solver keywords: see
        http://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.lobpcg.html
    amg solver keywords: see
        http://pyamg.googlecode.com/svn/branches/1.0.x/Docs/html/pyamg.aggregation.html#module-pyamg.aggregation.aggregation
        (Note amg solver uses lobpcg and also accepts lobpcg keywords)


    This function is used to estimate the doubling dimension (approximately equal to the intrinsic
    dimension) by computing a graph of neighborhood radius versus average number of neighbors.

    The "radius" refers to the truncation constant where all distances greater than
    a specified radius are taken to be infinite. This is used for example in the
    truncated Gaussian kernel in estimate_radius.py

    Parameters
    ----------
    data : numpy array,
        Original data set for which we are estimating the bandwidth
    rmin : float,
        smallest radius to consider
    rmax : float,
        largest radius to consider
    nradii : int,
        number of radii between rmax and rmin to consider
    adjacency_method : string,
        megaman adjacency method to use, default 'brute' see geometry.py for details
    adjacency_kwds : dict,
        dictionary of keywords for adjacency method
    fit_range : list of ints,
        range of radii to consider default is range(nradii), i.e. all of them
    savefig: bool,
        whether to save the radius vs. neighbors figure
    plot_name: string,
        filename of the figure to be saved as.

    Returns
    -------
    results : dictionary
        contains the radii, average nieghbors, min and max number of neighbors and number
        of points with no neighbors.
    dim : float,
        estimated doubling dimension (used as an estimate of the intrinsic dimension)


    Parameters
    ----------
    C: array-like, shape = (n, l)
      Stacking the training and testing data where n
      is the total number of data and l is the number of
      training data.
    e_val: array, shape = (1,s)
      If W equals to C[0:l, :], then e_val are the largest s
      eig values of W
    e_vec: array-like, shape = (l, s)
      These are the corresponding eig vectors to e_val

    Returns
    -------
    eval_nystrom: array-like, shape = (1,s)
      These are the estimated largest s eig values of the matrix where C is the
      first l columns.
    evec_nystrom: arrau-like, shape = (n, s)
      These are the corresponding eig vectors to eval_nystrom


        Fit the model from data in X.

        Parameters
        ----------
        input_type : string, one of: 'similarity', 'distance' or 'data'.
            The values of input data X. (default = 'data')
        X : array-like, shape (n_samples, n_features)
            Training vector, where n_samples in the number of samples
            and n_features is the number of features.

        If self.input_type is similarity:
        X : array-like, shape (n_samples, n_samples),
            copy the similarity matrix X to S.


    Spectral clustering for find K clusters by using the eigenvectors of a
    matrix which is derived from a set of similarities S.

    Parameters
    -----------
    S: array-like,shape(n_sample,n_sample)
        similarity matrix
    K: integer
        number of K clusters
    eigen_solver : {'auto', 'dense', 'arpack', 'lobpcg', or 'amg'}
        'auto' :
            algorithm will attempt to choose the best method for input data
        'dense' :
            use standard dense matrix operations for the eigenvalue decomposition.
            For this method, M must be an array or matrix type.  This method should be avoided for large problems.
        'arpack' :
            use arnoldi iteration in shift-invert mode. For this method,
            M may be a dense matrix, sparse matrix, or general linear operator.
            Warning: ARPACK can be unstable for some problems.  It is best to
            try several random seeds in order to check results.
        'lobpcg' :
            Locally Optimal Block Preconditioned Conjugate Gradient Method.
            A preconditioned eigensolver for large symmetric positive definite
            (SPD) generalized eigenproblems.
        'amg' :
            AMG requires pyamg to be installed. It can be faster on very large,
            sparse problems, but may also lead to instabilities.

    random_state : numpy.RandomState or int, optional
        The generator or seed used to determine the starting vector for arpack
        iterations.  Defaults to numpy.random.RandomState
    solver_kwds : any additional keyword arguments to pass to the selected eigen_solver
    renormalize : (bool) whether or not to set the rows of the eigenvectors to have norm 1
                 this can improve label quality
    stabalize : (bool) whether or not to compute the (more stable) eigenvectors of L = D^-1/2*S*D^-1/2
                instead of P = D^-1*S
    additional_vectors : (int) compute additional eigen vectors when computing eigen decomposition.
        When eigen_solver = 'amg' or 'lopcg' often if a small number of eigen values is sought the
        largest eigenvalue returned is *not* equal to 1 (it should be). This can usually be fixed
        by requesting more than K eigenvalues until the first eigenvalue is close to 1 and then
        omitted. The remaining K-1 eigenvectors should be informative.
    Returns
    -------
    labels: array-like, shape (1,n_samples)


    K-means clustering is an algorithm that take a data set and
    a number of clusters K and returns the labels which represents
    the clusters of data which are similar to others

    Parameters
    --------------------
    data: array-like, shape= (m_samples,n_samples)
    K: integer
        number of K clusters
    Returns
    -------
    labels: array-like, shape (1,n_samples)


    Initialize the centrodis by orthogonal_initialization.
    Parameters
    --------------------
    X(data): array-like, shape= (m_samples,n_samples)
    K: integer
        number of K clusters
    Returns
    -------
    centroids: array-like, shape (K,n_samples)
    data_norms: array-like, shape=(1,n_samples)


    Initialize the centrodis by orthogonal_initialization.
    Parameters
    --------------------
    X(data): array-like, shape= (m_samples,n_samples)
    data_norms: array-like, shape=(1,n_samples)
    center_norms:array-like,shape=(centroids.shape[0])
    centroids: array-like, shape (K,n_samples)
    Returns
    -------
    new_center: array-like, shape (1,n_samples)
    new_center_index: integer
                        data index of the new center


    Stop if centroids stop to update
    Parameters
    -----------
    centroids: array-like, shape=(K, n_samples)
    old_centroids: array-like, shape=(K, n_samples)
    ------------
    returns
    True: bool


Like assert_all_finite, but only for ndarray.


Return a platform independent reprensentation of an array shape
    Under Python 2, the `long` type introduces an 'L' suffix when using the
    default %r format for tuples of integers (typically used to store the shape
    of an array).
    Under Windows 64 bit (and Python 2), the `long` type is used by default
    in numpy shapes even when the integer dimensions are well below 32 bit.
    The platform specific type causes string messages or doctests to change
    from one platform to another which is not desirable.
    Under Python 3, there is no more `long` type so the `L` suffix is never
    introduced in string representation.
    >>> _shape_repr((1, 2))
    '(1, 2)'
    >>> one = 2 ** 64 / 2 ** 64  # force an upcast to `long` under Python 2
    >>> _shape_repr((one, 2 * one))
    '(1, 2)'
    >>> _shape_repr((1,))
    '(1,)'
    >>> _shape_repr(())
    '()'


Return number of samples in array-like x.


Convert a sparse matrix to a given format.
    Checks the sparse format of spmatrix and converts if necessary.
    Parameters
    ----------
    spmatrix : scipy sparse matrix
        Input to validate and convert.
    accept_sparse : string, list of string or None (default=None)
        String[s] representing allowed sparse matrix formats ('csc',
        'csr', 'coo', 'dok', 'bsr', 'lil', 'dia'). None means that sparse
        matrix input will raise an error.  If the input is sparse but not in
        the allowed format, it will be converted to the first listed format.
    dtype : string, type or None (default=none)
        Data type of result. If None, the dtype of the input is preserved.
    copy : boolean (default=False)
        Whether a forced copy will be triggered. If copy=False, a copy might
        be triggered by a conversion.
    force_all_finite : boolean (default=True)
        Whether to raise an error on np.inf and np.nan in X.
    Returns
    -------
    spmatrix_converted : scipy sparse matrix.
        Matrix that is ensured to have an allowed type.


Make sure that array is 2D, square and symmetric.
    If the array is not symmetric, then a symmetrized version is returned.
    Optionally, a warning or exception is raised if the matrix is not
    symmetric.
    Parameters
    ----------
    array : nd-array or sparse matrix
        Input object to check / convert. Must be two-dimensional and square,
        otherwise a ValueError will be raised.
    tol : float
        Absolute tolerance for equivalence of arrays. Default = 1E-10.
    raise_warning : boolean (default=True)
        If True then raise a warning if conversion is required.
    raise_exception : boolean (default=False)
        If True then raise an exception if array is not symmetric.
    Returns
    -------
    array_sym : ndarray or sparse matrix
        Symmetrized version of the input array, i.e. the average of array
        and array.transpose(). If sparse, then duplicate entries are first
        summed and zeros are eliminated.


Turn seed into a np.random.RandomState instance
    If seed is None, return the RandomState singleton used by np.random.
    If seed is an int, return a new RandomState instance seeded with seed.
    If seed is already a RandomState instance, return it.
    Otherwise raise ValueError.


Input validation on an array, list, sparse matrix or similar.
    By default, the input is converted to an at least 2nd numpy array.
    If the dtype of the array is object, attempt converting to float,
    raising on failure.
    Parameters
    ----------
    array : object
        Input object to check / convert.
    accept_sparse : string, list of string or None (default=None)
        String[s] representing allowed sparse matrix formats, such as 'csc',
        'csr', etc.  None means that sparse matrix input will raise an error.
        If the input is sparse but not in the allowed format, it will be
        converted to the first listed format.
    dtype : string, type, list of types or None (default="numeric")
        Data type of result. If None, the dtype of the input is preserved.
        If "numeric", dtype is preserved unless array.dtype is object.
        If dtype is a list of types, conversion on the first type is only
        performed if the dtype of the input is not in the list.
    order : 'F', 'C' or None (default=None)
        Whether an array will be forced to be fortran or c-style.
    copy : boolean (default=False)
        Whether a forced copy will be triggered. If copy=False, a copy might
        be triggered by a conversion.
    force_all_finite : boolean (default=True)
        Whether to raise an error on np.inf and np.nan in X.
    ensure_2d : boolean (default=True)
        Whether to make X at least 2d.
    allow_nd : boolean (default=False)
        Whether to allow X.ndim > 2.
    ensure_min_samples : int (default=1)
        Make sure that the array has a minimum number of samples in its first
        axis (rows for a 2D array). Setting to 0 disables this check.
    ensure_min_features : int (default=1)
        Make sure that the 2D array has some minimum number of features
        (columns). The default value of 1 rejects empty datasets.
        This check is only enforced when the input data has effectively 2
        dimensions or is originally 1D and ``ensure_2d`` is True. Setting to 0
        disables this check.
    warn_on_dtype : boolean (default=False)
        Raise DataConversionWarning if the dtype of the input data structure
        does not match the requested dtype, causing a memory copy.
    estimator : str or estimator instance (default=None)
        If passed, include the name of the estimator in warning messages.
    Returns
    -------
    X_converted : object
        The converted and validated X.


    This function is used to estimate the bandwidth, h, of the Gaussian Kernel:
        exp(-||x_i - x_j||/h^2)

    The "radius" refers to the truncation constant which we take to be
    rad_bw_ratio * h and this is the parameter over which we will iterate.

    We use the method of: https://arxiv.org/abs/1406.0118

    Parameters
    ----------
    data : numpy array,
        Original data set for which we are estimating the bandwidth
    dists : scipy.csr_matrix,
        A CSR matrix containing pairwise distances from data up to rmax
    sample : np.array,
        subset of data points over which to evaluate the radii
    d : int,
        dimension over which to evaluate the radii (smaller usually better)
    rmin : float,
        smallest radius ( = rad_bw_ratio * bandwidth) to consider
    rmax : float,
        largest radius ( = rad_bw_ratio * bandwidth) to consider
    ntry : int,
        number of radii between rmax and rmin to try
    run_parallel : bool,
        whether to run the analysis in parallel over radii
    search_space : str,
        either 'linspace' or 'logspace', choose to search in log or linear space
    rad_bw_ratio : float,
        the ratio of radius and kernel bandwidth, default to be 3 (radius = 3*h)
    max_cpus : int,
        the maximum cpus to use when run_parallel is True, ignore if False

    Returns
    -------
    results : np.array (2d)
        first column is the set of radii and the second column is the distortion
        (smaller is better)


Generate 2D point data of the megaman image


Make a 2D S-curve from a 1D vector


Generate a manifold of the megaman data


Split relaxation keywords to keywords for optimizer and others


    Initialize relaxation keywords.

    Parameters
    ----------
    relaxation_kwds : dict
        weights : numpy array, the weights
        step_method : string { 'fixed', 'momentum' }
            which optimizers to use
        linesearch : bool
            whether to do linesearch in search for eta in optimization
        verbose : bool
            whether to print reports to I/O when doing relaxation
        niter : int
            number of iterations to run.
        niter_trace : int
            number of iterations to be traced.
        presave : bool
            whether to store precomputed keywords to files or not.
        sqrd : bool
            whether to use squared norm in loss function. Default : True
        alpha : float
            shrinkage rate for previous gradient. Default : 0
        projected : bool
            whether or not to optimize via projected gradient descent on differences S
        lossf : string { 'epsilon', 'rloss' }
            which loss function to optimize.
            Default : 'rloss' if n == d, otherwise 'epsilon'
        subset : numpy array
            Subset to do relaxation on.
        sub_dir : string
            sub_dir used to store the outputs.
        backup_base_dir : string
            base directory used to store outputs
            Final path will be backup_base_dir/sub_dir
        saveiter : int
            save backup on every saveiter iterations
        printiter : int
            print report on every printiter iterations
        save_init : bool
            whether to save Y0 and L before running relaxation.


compute Lk, neighbors and subset to index map for projected == False


    Compute sparse L matrix, neighbors and subset to L matrix index map.

    Returns
    -------
    Lk_tensor : array-like. Length = n
        each component correspond to the sparse matrix of Lk, which is
        generated by extracting the kth row of laplacian and removing zeros.
    nbk : array-like. Length = n
        each component correspond to the neighbor index of point k, which is
        used in slicing the gradient, Y or S arrays.
    si_map : dictionary.
        subset index to Lk_tensor (or nbk) index mapping.


compute Rk, A, ATAinv, neighbors and pairs for projected mode


    This function create the all neighbor permutations.
    The output A multiply by Y will be [ Y_i - Y_j ].T for all j > i
    So the maximum will be C^n_2. But it will be less than this value
    because of the sparseness of L.

    Returns
    -------
    A : sparse matrix, shape (N_pairs, n_samples)
        Operator for Y projection transformation.
    pairs : matrix, shape (N_pairs, 2)
        Pairs index for A, first column is the row and second is the col.


    Compute sparse L matrix and neighbors.

    Returns
    -------
    Rk_tensor : array-like. Length = n
        each component correspond to the sparse matrix of Lk, which is
        generated by extracting the kth row of laplacian and removing zeros.
    nbk : array-like. Length = n
        each component correspond to the neighbor index of point k, which is
        used in slicing the gradient, Y or S arrays.


Save relaxation keywords to .txt and .pyc file


Update the trace_var in new iteration


Class method save for saving TracingVariable.


Load from stored files


        Calculating (Obtaining) the learning rate (eta) and apply optimizations
        on the embedding states by the specified method.

        Parameters
        ----------
        update_embedding_with : function
            Function used to update the state of RiemannianRelaxation
            class (Y or S).

        grad : (n x s) array
            Gradients used in updating the embedding.

        calc_loss : function (used by its child function)
            Function used to calculated the loss from the temperary state of
            RiemannianRelaxation instance. (YT or ST)

        loss : float (used by its child function)
            Loss of the current state of RiemannianRelaxation instance.


Helper function for creating a RiemannianRelaxation class.


Main function for doing riemannian relaxation.


Helper function to calculate the


3 Dimensional Covariance plotter using matplotlib backend.


Plot 2d ellipse in 3d using matplotlib backend


Given two dicts, merge them into a new dict as a shallow copy.


    Transforms a 2D Patch to a 3D patch using the given normal vector.

    The patch is projected into they XY plane, rotated about the origin
    and finally translated by z.


Translates the 3D pathpatch by the amount delta.


Calculate the properties for 2d ellipse given the covariance matrix.


    Calculates a rotation matrix given a vector d. The direction of d
    corresponds to the rotation axis. The length of d corresponds to
    the sin of the angle of rotation.

    Variant of: http://mail.scipy.org/pipermail/numpy-discussion/2009-March/040806.html


Create parametric ellipse from 200 points.


Project points into 3d from 2d points.


Visualize the ellipse by using the mesh of the points.


Compute the affinity matrix with the given method


        This function will compute the adjacency matrix.
        In order to acquire the existing adjacency matrix use
        self.adjacency_matrix as comptute_adjacency_matrix() will re-compute
        the adjacency matrix.

        Parameters
        ----------
        copy : boolean, whether to return a copied version of the adjacency matrix
        **kwargs : see distance.py docmuentation for arguments for each method.

        Returns
        -------
        self.adjacency_matrix : sparse matrix (N_obs, N_obs)
            Non explicit 0.0 values should be considered not connected.


        This function will compute the affinity matrix. In order to
        acquire the existing affinity matrix use self.affinity_matrix as
        comptute_affinity_matrix() will re-compute the affinity matrix.

        Parameters
        ----------
        copy : boolean
            whether to return a copied version of the affinity matrix
        **kwargs :
            see affinity.py docmuentation for arguments for each method.

        Returns
        -------
        self.affinity_matrix : sparse matrix (N_obs, N_obs)
            contains the pairwise affinity values using the Guassian kernel
            and bandwidth equal to the affinity_radius


        Note: this function will compute the laplacian matrix. In order to acquire
            the existing laplacian matrix use self.laplacian_matrix as
            comptute_laplacian_matrix() will re-compute the laplacian matrix.

        Parameters
        ----------
        copy : boolean, whether to return copied version of the self.laplacian_matrix
        return_lapsym : boolean, if True returns additionally the symmetrized version of
            the requested laplacian and the re-normalization weights.
        **kwargs : see laplacian.py docmuentation for arguments for each method.

        Returns
        -------
        self.laplacian_matrix : sparse matrix (N_obs, N_obs).
            The requested laplacian.
        self.laplacian_symmetric : sparse matrix (N_obs, N_obs)
            The symmetric laplacian.
        self.laplacian_weights : ndarray (N_obs,)
            The renormalization weights used to make
            laplacian_matrix from laplacian_symmetric


Compute the laplacian matrix with the given method


Create a base class with a metaclass.


    Parameters
    ----------
    Y: array-like, shape = (n_samples, mdimY )
        The embedding coordinates of the points
    laplacian: array-like, shape = (n_samples, n_samples)
        The Laplacian of the data. It is recommended to use the "geometric"
        Laplacian (default) option from geometry.graph_laplacian()
    n_dim : integer, optional
        Use only the first n_dim <= mdimY dimensions.All dimensions
        n_dim:mdimY are ignored.
    invert_h: boolean, optional
        if False, only the "dual Riemannian metric" is computed
        if True, the dual metric matrices are inverted to obtain the
        Riemannian metric G.
    mode_inv: string, optional
       How to compute the inverses of h_dual_metric, if invert_h
        "inv", use numpy.inv()
        "svd" (default), use numpy.linalg.svd(), then invert the eigenvalues
        (possibly a more numerically stable method with H is symmetric and
        ill conditioned)

    Returns
    -------
    h_dual_metric : array, shape=(n_samples, n_dim, n_dim)
    Optionally :
    g_riemann_metric : array, shape=(n_samples, n_dim, n_dim )
    Hvv : singular vectors of H, transposed, shape = ( n_samples, n_dim, n_dim )
    Hsvals : singular values of H, shape = ( n_samples, n_dim )
    Gsvals : singular values of G, shape = ( n_samples, n_dim )

    Notes
    -----
    References
    ----------
    "Non-linear dimensionality reduction: Riemannian metric estimation and
    the problem of geometric discovery",
    Dominique Perraul-Joncas, Marina Meila, arXiv:1305.7255


    Parameters
    ----------
    Y: array-like, shape = (n_samples, mdimY )
        The embedding coordinates of the points
    sample : array-like, shape (n_samples)
        array of indices over which to calculate the riemannian metric.
    laplacian: array-like, shape = (n_samples, n_samples)
        The Laplacian of the data. It is recommended to use the "geometric"
        Laplacian (default) option from geometry.graph_laplacian()
    n_dim : integer, optional
        Use only the first n_dim <= mdimY dimensions.All dimensions
        n_dim:mdimY are ignored.
    invert_h: boolean, optional
        if False, only the "dual Riemannian metric" is computed
        if True, the dual metric matrices are inverted to obtain the
        Riemannian metric G.
    mode_inv: string, optional
       How to compute the inverses of h_dual_metric, if invert_h
        "inv", use numpy.inv()
        "svd" (default), use numpy.linalg.svd(), then invert the eigenvalues
        (possibly a more numerically stable method with H is symmetric and
        ill conditioned)

    Returns
    -------
    h_dual_metric : array, shape=(n_samples, n_dim, n_dim)
    Optionally :
    g_riemann_metric : array, shape=(n_samples, n_dim, n_dim )
    Hvv : singular vectors of H, transposed, shape = ( n_samples, n_dim, n_dim )
    Hsvals : singular values of H, shape = ( n_samples, n_dim )
    Gsvals : singular values of G, shape = ( n_samples, n_dim )

    Notes
    -----
    References
    ----------
    "Non-linear dimensionality reduction: Riemannian metric estimation and
    the problem of geometric discovery",
    Dominique Perraul-Joncas, Marina Meila, arXiv:1305.7255


    Parameters
    ----------
    H : the inverse R. Metric
    if mode_inv == 'svd':
       also returns Hvv, Hsvals, Gsvals the (transposed) eigenvectors of
       H and the singular values of H and G
    if mdimG < H.shape[2]:
       G.shape = [ n_samples, mdimG, mdimG ] with n_samples = H.shape[0]

    Notes
    ------
    currently Hvv, Hsvals are n_dim = H.shape[2], and Gsvals, G are mdimG
    (This contradicts the documentation of riemann_metric which states
    that riemann_metric and h_dual_metric have the same dimensions)

    See the notes in RiemannMetric


Compute an adjacency matrix with the given method


 The threshold value to apply for the isosurface render method.
            Also used for the lmip transfer function.


 The id of this GL object used to reference the GL object
        in GLIR. id's are unique within a process.


 The user-set distance. If None (default), the distance is
        internally calculated from the scale factor and fov.


 The threshold at which the isocurve is constructed from the
        2D data.