pyckmeans.ordination package

Submodules

pyckmeans.ordination.utils module

ordination utilities

class pyckmeans.ordination.utils.NumpyEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: json.encoder.JSONEncoder

Special json encoder for numpy types

Methods

`default`(obj)	Implement this method in a subclass such that it returns a serializable object for `o`, or calls the base implementation (to raise a `TypeError`).
`encode`(o)	Return a JSON string representation of a Python data structure.
`iterencode`(o[, _one_shot])	Encode the given object and yield each string representation as available.

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

Module contents

ordination

Module for Principle Coordinate Analysis (PCoA) calculation.

exception pyckmeans.ordination.IncompatibleNamesError

Bases: Exception

Error, signalling that provided names are incompatible with provided data.

exception pyckmeans.ordination.InvalidCorrectionTypeError: Bases: Exception

exception pyckmeans.ordination.InvalidFilterError: Bases: Exception

exception pyckmeans.ordination.InvalidOutFormatError: Bases: Exception

exception pyckmeans.ordination.InvalidPCOAResultError

Bases: Exception

Error, signalling an invalid PCOAResult.

exception pyckmeans.ordination.NegativeEigenvaluesCorrectionError

Bases: Exception

FailedCorrectionError

Error, signalling that the correction of negative eigenvalues failed.

exception pyckmeans.ordination.NegativeEigenvaluesWarning

Bases: Warning

Warning, signalling that negative eigenvalues were encountered.

class pyckmeans.ordination.PCOAResult(vectors: numpy.ndarray, eigvals: numpy.ndarray, eigvals_rel: numpy.ndarray, trace: float, negative_eigvals: bool, correction: Optional[str] = None, eigvals_corr_rel: Optional[numpy.ndarray] = None, trace_corr: Optional[float] = None, names: Optional[Iterable[str]] = None)

Bases: object

Object containing the results of a Principle Coordinate Analysis.

Parameters

vectorsnumpy.ndarray: n * m matrix of potentially corrected eigenvectors, where n is the number of samples and m is the number of retained axes.
eigvalsnumpy.ndarray: Vector of eigenvalues.
eigvals_relnumpy.ndarray: Vector of relative eigenvalues.
tracefloat: Trace.
negative_eigvalsbool: Bool, determining whether negative eigenvalues are present.
correctionOptional[str], optional: Type of correction, by default None
eigvals_corr_relOptional[numpy.ndarray], optional: Vector of corrected relative eigenvalues, by default None
trace_corrOptional[float], optional: Corrected trace, by default None
namesOptional[Iterable[str]], optional: Vector of names, by default None

Raises

InvalidPCOAResultError: Raised if invalid parameter combinations are provided.
IncompatibleNamesError: Raised if provided names are incompatible with provided data.

Methods

`from_dict`(pcoa_res_dict)	Construct PCOAResult from dictionary.
`from_dir`(directory)	Construct PCOAResult from a directory contraining the three files 'vectors.csv', 'values.csv', and 'others.csv'.
`from_json`(file, **kwargs)	Construct PCOAResult from JSON file.
`from_json_str`(json_str, **kwargs)	Construct PCOAResult from JSON string.
`get_vectors`([filter_by, filter_th, out_format])	getVectors
`to_dict`()	Convert PCOAResult to dictionary.
`to_dir`(out_dir[, force])	Save PCOAResult to directory.
`to_json`([file])	Convert PCOAResult to JSON string or file.

classmethod from_dict(pcoa_res_dict: Dict) → pyckmeans.ordination.PCOAResult

Construct PCOAResult from dictionary.

Parameters

pcoa_res_dictDict: PCOAResult as dictionary.

Returns

PCOAResult: PCOAResult

classmethod from_dir(directory: str) → pyckmeans.ordination.PCOAResult

Construct PCOAResult from a directory contraining the three files ‘vectors.csv’, ‘values.csv’, and ‘others.csv’. See <pyckmeans.ordination.PCOAResult.to_dir>().

Parameters

directorystr: PCOAResult directory.

Returns

PCOAResult: PCOAResult

Raises

Exception: Raised if there is a problem with directory.

classmethod from_json(file: str, **kwargs: Dict[str, Any]) → pyckmeans.ordination.PCOAResult

Construct PCOAResult from JSON file.

Parameters

filestr: JSON file
kwargsDict[str, Any]: Additional keyword arguments passed to json.loads.
Returns
——-
PCOAResult: PCOAResult

classmethod from_json_str(json_str: str, **kwargs: Dict[str, Any]) → pyckmeans.ordination.PCOAResult

Construct PCOAResult from JSON string.

Parameters

json_str: str: JSON string.
kwargsDict[str, Any]: Additional keyword arguments passed to json.loads.

Returns

PCOAResult: PCOAResult

get_vectors(filter_by: Optional[str] = None, filter_th: Optional[float] = None, out_format: str = 'numpy') → Union[numpy.ndarray, pandas.core.frame.DataFrame]

getVectors

Get eigenvectors, potentially filtered by cumulative eigenvalue scores.

Parameters

filter_byOptional[str], optional

Cumulative eigenvalue score to filter by or None if no filtering should be applied, by default None. Can be one of:

‘eigvals_rel_cum’
‘eigvals_rel_corrected_cum’

If filter_by is provided filter_th is required.

filter_thOptional[float], optional

Filtering treshold, by default None. Eigenvectors will be retained until cumulative eigenvalue score is greater than or equal to filter_th.

out_formatstr, optional

Output format, by default ‘numpy’. Must be ‘numpy’ or ‘np’ for output as numpy.ndarray (Note: name information will be lost), or ‘pandas’ or ‘pd’ for output as pandas.DataFrame.

Returns

Union[numpy.ndarray, pandas.DataFrame]: Eigenvectors.

Raises

InvalidFilterError: Raised if filter arguments are invalid.
InvalidOutFormatError: Raised if an invalid out_format is provided.

to_dict() → Dict

Convert PCOAResult to dictionary.

Returns

Dict: PCOAResult as dictionary.

to_dir(out_dir: str, force: bool = False)

Save PCOAResult to directory. The directory will contain the three files ‘vectors.csv’, comprising the eigenvectors, ‘values.csv’, comprising the eigenvalues, and ‘others.csv’, comprising trace and correction data.

Parameters

out_dirstr: Output directory. Will be created if it does not exist.
forcebool, optional: Write into out_dir even if it does already exist, by default False.

Raises

Exception: Raised if there is a problem with out_dir.

to_json(file: Optional[str] = None, **kwargs: Dict[str, Any]) → Optional[str]

Convert PCOAResult to JSON string or file.

Parameters

fileOptional[str], optional: File path to write the PCOAResult to or None. If None, the JSON string will be returned.
kwargsDict[str, Any]: Additional keyword arguments passed to json.dump or json.dumps.

Returns

Optional[str]: None or JSON string.

pyckmeans.ordination.pcoa(dist: Union[numpy.ndarray, pyckmeans.distance.DistanceMatrix], correction: Optional[str] = None, eps: float = 1e-08) → pyckmeans.ordination.PCOAResult

Principle Coordinate Analysis.

Parameters

distUnion[numpy.ndarray, pyckmeans.distance.DistanceMatrix]

n*n distance matrix either as numpy ndarray or as pyckmeans DistanceMatrix.

correction: Optional[str]

Correction for negative eigenvalues, by default None. Available corrections are:

None: negative eigenvalues are set to 0

lingoes: Lingoes correction

cailliez: Cailliet correction

epsfloat, optional

Eigenvalues smaller than eps will be dropped. By default 0.0001

Returns

PCOAResult: PCoA result object.

Raises

InvalidCorrectionTypeError: Raised if an unknown correction type is passed.
NegativeEigenvaluesCorrectionError: Raised if correction parameter is set and correction of negative eigenvalues is not successful.