HEaaN.stat 

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> df = pd.DataFrame({"A": [1,2,3,4,5], "B": [1.3, 4.5, 6.6, -3.1, 2.1]})
>>> hf = heaan_sdk.HEFrame.from_frame(context, df)
>>> hf.encrypt()
>>> hf.drop("A", inplace=True)
>>> hf
HEFrame(
number of rows: 5,
number of columns: 1,
list of columns: ['B']
)

encrypt(inplace: bool = True, data_level: int | str | None = None, vbit_level: int | str | None = None, save_path: Path | str | None = None) → HEFrame

Encrypt HEFrame.

Parameters:

inplace (bool, optional) – Whether to modify HEFrame rather than creating a new one. Defaults to True.
data_level (Optional[Union[int, str]], optional) – Target level of data for encryption. If it is minimum, down level of ciphertexts to the smallest extended bootstrappable level. If None, leave it as is. Defaults to None.
vbit_level (Optional[Union[int, str]], optional) – Target level of vbit for encryption. If it is minimum, down level of ciphertexts to the smallest bootstrappable level. If None, leave it as is. Defaults to None.
save_path (Optional[Union[Path, str]], optional) – Whether to save HEFrame after encryption. If path is entered, save encrypted HEFrame to the path. Defaults to None.

Returns:

Encrypted HEFrame.

Return type:

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> df = pd.DataFrame({"A": [1,2,3,4,5], "B": [1.3, 4.5, 6.6, -3.1, 2.1]})
>>> hf = heaan_sdk.HEFrame.from_frame(context, df)
>>> hf.encrypt()
HEFrame(
number of rows: 5,
number of columns: 2,
list of columns: ['A', 'B']
)
>>> hf.info()
<class 'heaan_sdk.frame.frame.HEFrame'>
Data rows: 5
Data columns (total 2 columns):
#    Column                    Dtype      Encrypted
---  ------------------------  ---------  ----------
  0  A                         int64      True
  1  B                         float64    True
dtypes: float64(1), int64(1)

static from_frame(context: Context, df: DataFrame, fixed_point_columns: str | List[str] | None = None, encrypt_vbit: bool = False, create_vbit_always: bool = False, create_norm: bool = True, save_info_separately: bool = True) → HEFrame

Create HEFrame from a pandas DataFrame. It works as follows: (i) Create an empty HEFrame, (ii) each pandas Series in pandas DataFrame is encoded as HESeries, and (iii) these HESeries are appended to the empty HEFrame.

Parameters:

context (Context) – Context of HEaaN-SDK.
df (pd.DataFrame) – Pandas DataFrame to create HEFrame from.
fixed_point_columns (Union[str, List[str]], optional) – List of column names or a single column name
in (to encode in fixed-point representation if it is numerical. Columns not included this list are encoded) –
None. (floating-point representaion. Defaults to) –
encrypt_vbit (bool, optional) – Whether to encrypt valid bit of HEFrame or not. Defaults to False.
create_vbit_always (bool, optional) – Whether to create valid vbits even if there is no missing. Defaults to False.
create_norm (bool, optional) – Whether to create normalization information if HESeries of HEFrame is encoded as numeric. This is essential for calculating nonlinear functions such as inverse or square root. Defaults to True.
save_info_separately (bool, optional) – Whether to store data and information of data separately. If it is false and there exists extra space to save information of data, information of data are stored with data in same storage. Defaults to True.

Returns:

HEFrame created from pandas DataFrame.

Return type:

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> df = pd.DataFrame({"A": [1,2,3,4,5], "B": [1.3, 4.5, 6.6, -3.1, 2.1]})
>>> hf = heaan_sdk.HEFrame.from_frame(context, df)
>>> hf
HEFrame(
number of rows: 5,
number of columns: 2,
list of columns: ['A', 'B']
)

classmethod from_path(context: Context, path: str | Path) → HEFrame

Create a HEFrame and load data from path into HEFrame.

Parameters:

context (Context) – Context of HEFrame to be loaded.
path (Union[str, Path]) – Path to load data.

Returns:

Loaded HEFrame.

Return type:

info() → Metadata

Information of HEFrame.

Returns:: Metadata of HEFrame
Return type:: Metadata

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> df = pd.DataFrame({"A": [1,2,3,4,5], "B": [1.3, 4.5, 6.6, -3.1, 2.1]})
>>> hf = heaan_sdk.HEFrame.from_frame(context, df)
>>> hf.info()
<class 'heaan_sdk.frame.frame.HEFrame'>
Data rows: 5
Data columns (total 2 columns):
#    Column            Dtype      Encrypted
---  ----------------  ---------  ----------
  0  A                 int64      False
  1  B                 float64    False
dtypes: int64(1), float64(1)
>>> hf.encrypt()
>>> hf.info()
<class 'heaan_sdk.frame.frame.HEFrame'>
Data rows: 5
Data columns (total 2 columns):
#    Column            Dtype      Encrypted
---  ----------------  ---------  ----------
  0  A                 int64      True
  1  B                 float64    True
dtypes: int64(1), float64(1)

property num_rows: int

Number of rows of HEFrame.

Returns:: Number of rows of HEFrame.
Return type:: int

pop(name: str) → HESeries

Return HESeries corresponding to name and drop it from HEFrame.

Parameters:: name (str) – Name to pop.
Returns:: HESeries corresponding to name.
Return type:: HESeries

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> df = pd.DataFrame({"A": [1,2,3,4,5], "B": [1.3, 4.5, 6.6, -3.1, 2.1]})
>>> hf = heaan_sdk.HEFrame.from_frame(context, df)
>>> hf.encrypt()
>>> hs = hf.pop("A")
>>> hs
HESeries(
encrypted: True,
level: 12,
name: "A",
length: 5,
on GPU: False,
unit_series_list: [
    <heaan_sdk.frame.unit_series.HEUnitSeries object at 0x7f93e4fca9d0>
])
>>> hf
HEFrame(
number of rows: 5,
number of columns: 1,
list of columns: ['B']
)

Save HEFrame to path.

Parameters:

path (Union[str, Path]) – Path to save HEFrame.
data_level (Optional[Union[int, str]], optional) – If not None, then save the data with the specified level. If it is minimum, save ciphertexts with the smallest extended bootstrappable level. Defaults to None.
vbit_level (Optional[Union[int, str]], optional) – If not None, then save the data with the specified level. If it is minimum, save ciphertexts with the smallest bootstrappable level. Defaults to None.

to_frame() → DataFrame

Convert HeFrame to pandas DataFrame.

Returns:: Pandas DataFrame created from HEFrame.
Return type:: pd.DataFrame
Raises:: TypeError – When HEFrame is encrypted.

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> df = pd.DataFrame({"A": [1,2,3,4,5], "B": [1.3, 4.5, 6.6, -3.1, 2.1]})
>>> hf = heaan_sdk.HEFrame.from_frame(context, df)
>>> hf.to_frame()
   A    B
0  1  1.3
1  2  4.5
2  3  6.6
3  4 -3.1
4  5  2.1

class heaan_sdk.frame.series.HESeries(context: Context, length: int, name: str | None = None, dtype: str = 'float', index: List[int | str] | None = None, description: str = '', encrypt_vbit: bool = False, has_norm_info: bool = False)

HESeries is the class corresponding to pd.Series. Enable to put data into HESeries using pd.Series and ‘HESeries.from_series()’. HESeries consists of one or several HEUnitSeries which is a unit for storing data. The incoming data is stored in each HEUnitSeries in sequence. Each HEUnitSeries contains data as much as the number of slots which is determined by the HEParameter in the context. For example, the FGb parameter, the default parameter of HEaaN.STAT, has 32768 slots. So, each HEUnitSeries can store 32768 data at most. If the length of HESeries is larger than the number of slots, HESeries would have two or more HEUnitSeries. Also, if the length of data is not a multiple of the number of slots, unfilled space occurs in the last HEUnitSeries of HESeries. These space will be filled with garbage data.

__init__(context: Context, length: int, name: str | None = None, dtype: str = 'float', index: List[int | str] | None = None, description: str = '', encrypt_vbit: bool = False, has_norm_info: bool = False)

Create HESeries object. Note that the generated HESeries is empty. Use from_series() to create HESeries from a pandas Series.

Parameters:

context (Context) – Context of HESeries.
length (int) – Length of HESeries.
name (Optional[str], optional) – Name of HESeries. Defaults to None.
dtype (str, optional) – Data type of HESeries.
index (Optional[List[Union[int, str]]], optional) – Index of HESeries.
description (str, optional) – Description.
encrypt_vbit (bool, optional) – Whether to encrypt valid bit when HESeries is encrypted. Defaults to False.
has_norm_info (bool, optional) – Whether HESeries contains normalization data. Defaults to False.

bootstrap(data_cost_level: int | None = None, vbit_cost_level: int | None = None, include_norm: bool = True) → HESeries

Bootstrap HESeries. Bootstrap data using bootstrap_extended whereas use bootstrap to bootstrap vbit. See bootstrap_extended in Block class for more details about bootstrap_extended.

Parameters:

data_cost_level (Optional[int], optional) – Bootstrap data If the ciphertexts remained level before bootstrapping is lower than data_cost_level. If None, always bootstrap data. Defaults to None.
vbit_cost_level (Optional[int], optional) – Bootstrap vbit If the ciphertexts remained level before bootstrapping is lower than data_cost_level. If None, always bootstrap vbit. Defaults to None.
include_norm (bool, optional) – Whether bootstrap normalization data of HESeries. These ciphertexts are considered as data ciphertexts. Defaults to True.

Returns:

Bootstrapped HESeries.

Return type:

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps, encrypt_vbit=True, create_vbit_always=True)
>>> hs.encrypt()
>>> hs.level_down(data_level=5, vbit_level=7, inplace=True)
>>> hs.data_level
5
>>> hs.vbit_level
7
>>> hs.level
5
>>> hs.bootstrap()
HESeries(
encrypted: True,
level: 12,
length: 5,
unit_series_list: [
    <heaan_sdk.frame.unit_series.HEUnitSeries object at 0x7f93e4fca910>
])
>>> hs.data_level
12
>>> hs.vbit_level
12
>>> hs.level
12

copy() → HESeries

Copy HESeries to new location on memory.

Returns:: Copied HESeries
Return type:: HESeries

corr(other: HESeries) → HESeries

Compute the Pearson correlation coefficient with HESeries, excluding missing values. The two HESeries objects are required to be the same length but do not have to be same index of valid.

Parameters:: other (HESeries) – HESeries with which to compute the correlation.
Returns:: HESeries of length 1 containing the Pearson correlation coefficient between self and other.
Return type:: HESeries

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps1 = pd.Series([1,2,3,4,5])
>>> ps2 = pd.Series([1.3, 4.5, 6.6, -3.1, 2.1])
>>> hs1 = heaan_sdk.HESeries.from_series(context, ps1)
>>> hs2 = heaan_sdk.HESeries.from_series(context, ps2)
>>> hs1.encrypt()
>>> hs2.encrypt()
>>> hs_corr = hs1.corr(hs2)
>>> hs_corr.decrypt()
>>> hs_corr.to_series()
0   -0.259335
dtype: float64

count() → HESeries

Compute the count for HESeries.

Returns:: HESeries of length 1 containing the count.
Return type:: HESeries

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps, encrypt_vbit=True, create_vbit_always=True)
>>> hs.encrypt()
>>> hs_count = hs.count()
>>> hs_count.decrypt()
>>> hs_count.to_series()
0    5
dtype: int64

cov(other: HESeries) → HESeries

Compute the covariance with HESeries, excluding missing values. The two HESeries objects are required to be the same length but do not have to be same index of valid.

Parameters:: other (HESeries) – HESeries with which to compute the covariance.
Returns:: HESeries of length 1 containing the covariance between self and other, normalized by N-1 where N represents the number of elements (unbiased estimator).
Return type:: HESeries

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps1 = pd.Series([1,2,3,4,5])
>>> ps2 = pd.Series([1.3, 4.5, 6.6, -3.1, 2.1])
>>> hs1 = heaan_sdk.HESeries.from_series(context, ps1)
>>> hs2 = heaan_sdk.HESeries.from_series(context, ps2)
>>> hs1.encrypt()
>>> hs2.encrypt()
>>> hs_cov = hs1.cov(hs2)
>>> hs_cov.decrypt()
>>> hs_cov.to_series()
0   -1.500001
dtype: float64

property data_encrypted: bool

Whether data of HESeries is encrypted or not.

Returns:: Whether data of HESeries is encrypted.
Return type:: bool

property data_level: int

The smallest level of data in HESeries. Returns sys.maxsize if data is plaintext or does not exist.

Returns:: The smallest level of data in HESeries.
Return type:: int

decrypt(inplace: bool = True) → HESeries

Decrypt HESeries.

Parameters:: inplace (bool, optional) – Whether to modify HESeries rather than creating a new one. Defaults to True.
Returns:: Decrypted HESeries.
Return type:: HESeries
Raises:: TypeError – When HESeries is already plaintext.

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps)
>>> hs.encrypt()
>>> hs.decrypt()
HESeries(
encrypted: False,
length: 5,
unit_series_list: [
    <heaan_sdk.frame.unit_series.HEUnitSeries object at 0x7f93e4fca490>
])

encrypt(data_level: int | str | None = None, vbit_level: int | str | None = None, inplace: bool = True) → HESeries

Encrypt HESeries.

Parameters:

data_level (Optional[Union[int, str]], optional) – Target level of data for encryption. If it is minimum, down level of ciphertexts to the smallest extended bootstrappable level. If None, leave it as is. Defaults to None.
vbit_level (Optional[Union[int, str]], optional) – Target level of vbit for encryption. If it is minimum, down level of ciphertexts to the smallest bootstrappable level. If None, leave it as is. Defaults to None.
inplace (bool, optional) – Whether to modify HESeries rather than creating a new one. Defaults to True.

Returns:

Encrypted HESeries.

Return type:

Raises:

TypeError – When HESeries is already encrypted.

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps)
>>> hs.encrypt()
HESeries(
encrypted: True,
level: 12,
length: 5,
unit_series_list: [
    <heaan_sdk.frame.unit_series.HEUnitSeries object at 0x7f93e4fca490>
])

property encrypted: bool

Whether HESeries is encrypted or not.

Returns:: Whether HESeries is encrypted.
Return type:: bool

property exist_data: bool

Whether HESeries has data part.

Returns:: Whether HESeries has data part.
Return type:: bool

property exist_expo: bool

Whether HESeries has exponent part.

Returns:: Whether HESeries has exponent part.
Return type:: bool

property exist_vbit: bool

Whether HESeries has valid bits.

Returns:: Whether HESeries has valid bits.
Return type:: bool

static from_path(context: Context, path: str | Path) → HESeries

Create HESeries and load data from path into HESeries.

Parameters:

context (Context) – Context of HESeries to be loaded.
path (Union[str, Path]) – Path to load data.

Returns:

Loaded HESeries.

Return type:

static from_series(context: Context, series: Series, create_expo: bool = True, encrypt_vbit: bool = False, create_vbit_always: bool = False, create_norm: bool = True, save_info_separately: bool = True, remove_outlier_type: str | None = None, remove_outlier_range: float | None = None, categorical_encoding_type: str | None = None) → HESeries

Create HESeries from a pandas Series. The indexes of pandas Series must consist only of nonnegative integers.

Parameters:

context (Context) – Context of HEaaN-SDK.
series (pd.Series) – Pandas Series to create HESeries from.
create_expo (bool, optional) – Whether to create exponent. If False, encode data in floating-point representation. Defaults to True.
encrypt_vbit (bool, optional) – Whether to encrypt valid bit of HESeries or not. If True, create vbit always even if create_vbit_always is set to False. Defaults to False.
create_vbit_always (bool, optional) – Whether to create valid vbits even if there is no missing. Defaults to False.
create_norm (bool, optional) – Whether to create normalization information if HESeries is encoded as numeric. This is essential for calculating nonlinear functions such as inverse or square root. Defaults to True.
save_info_separately (bool, optional) – Whether to store data and information of data separately. If it is false and there exists extra space to save information of data, information of data are stored with data in same storage. Defaults to True.
remove_outlier_type (Optional[str], optional) – If remove_outlier_type is “IQR” or “std”, it removes outliers using IQR or standard deviation procedure, respectively. Defaults to None.
remove_outlier_range (Optional[float], optional) – If remove_outlier_range is specified, remove_outlier_range becomes the limits of outliers. If remove_outlier_range is not specified, set limits to 1.5 times for IQR precedure, 3 times for std precedure. Defaults to None.
categorical_encoding_type (Optional[str], optional) – How to encode categorical columns. If ALL_VALUES, encode all together. If 7_VALUES or 15_VALUES, put 7 or 15 unique values in each of storage. If None, encode autometically with respect to the number of unique values. Defaults to None.

Returns:

HESeries created from pandas Series.

Return type:

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps)
>>> hs
HESeries(
encrypted: False,
length: 5,
unit_series_list: [
    <heaan_sdk.frame.unit_series.HEUnitSeries object at 0x7f93e4fcaa60>
])

property has_norm_block: bool: Whether HESeries has normalization data. Almost all statistical functions can be calculated only if HESeries has normalization data.

info() → str

Information of HESeries.

Returns:: Information of HESeries.
Return type:: str

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps)
>>> hs.info()
<class 'heaan_sdk.frame.series.HESeries'>
Data length: 5
Dtype      Encrypted
---------  ----------
int64      False
>>> hs.encrypt()
>>> hs.name = "A"
>>> hs.info()
<class 'heaan_sdk.frame.series.HESeries'>
Data length: 5
HESeries name: A
Dtype      Encrypted
---------  ----------
int64      True

isnull() → HESeries

Return HESeries where each element is True if the value of HESeries is NaN else False.

Returns:: HESeries cacluated as above.
Return type:: HESeries

kurt() → HESeries

Compute the sample excess kurtosis for HESeries.

Returns:: HESeries of length 1 containing the kurtosis.
Return type:: HESeries

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([5,-3,6,4,126.3])
>>> hs = heaan_sdk.HESeries.from_series(context, ps)
>>> hs.encrypt()
>>> hs_kurt = hs.kurt()
>>> hs_kurt.decrypt()
>>> hs_kurt.to_series()
0    -0.932671
dtype: float64

property level: int

The smallest level of data or vbit in HESeries. Returns sys.maxsize if HESeries is plaintext or empty.

Returns:: The smallest level of data or vbit in HESeries.
Return type:: int

level_down(data_level: int | str | None = None, vbit_level: int | str | None = None, inplace: bool = True) → HESeries

Down level of HESeries to the target level.

Parameters:

data_level (Optional[Union[int, str]], optional) – Down level of data with specified level. If it is minimum, down level of ciphertexts to the smallest extended bootstrappable level. If None, leave it as is. Defaults to None.
vbit_level (Optional[Union[int, str]], optional) – Down level of vbit with specified level. If it is minimum, down level of ciphertexts to the smallest bootstrappable level. If None, leave it as is. Defaults to None.
inplace (bool, optional) – Whether to modify HESeries rather than creating a new one. Defaults to True.

Returns:

HESeries where data and vbit have specific level.

Return type:

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps, encrypt_vbit=True, create_vbit_always=True)
>>> hs.encrypt()
>>> hs.level_down(data_level=5, vbit_level=7, inplace=True)
HESeries(
encrypted: True,
level: 5,
length: 5,
unit_series_list: [
    <heaan_sdk.frame.unit_series.HEUnitSeries object at 0x7f93e4fca910>
])
>>> hs.data_level
5
>>> hs.vbit_level
7
>>> hs.level
5

load(path: str | Path) → None

Load HESeries.

Parameters:: path (Union[str, Path]) – Path to load data.

property max_expo: float

Maximum of exponents of HESeries.

Returns:: Maximum of exponents of HESeries.
Return type:: float

mean() → HESeries

Compute the mean for HESeries.

Returns:: HESeries of length 1 containing the mean.
Return type:: HESeries

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps)
>>> hs.encrypt()
>>> hs_mean = hs.mean()
>>> hs_mean.decrypt()
>>> hs_mean.to_series()
0    3.0
dtype: float64

property min_expo: float: Maximum of exponents of HESeries.

property num_slots: int

Number of slots of the context of HESeries.

Returns:: Number of slots of the context of HESeries.
Return type:: int

property num_units: int

Number of HEUnitSeries in HESeries.

Returns:: Number of HEUnitSeries in HESeries.
Return type:: int

property remained_cost_level: int

The remained level before bootstrapping if the context is bootstrappable. Otherwise, level of self.

Returns:: The remained level before bootstrapping if the context is bootstrappable. Otherwise, level of self.
Return type:: int

Save HESeries.

Parameters:

path (Union[str, Path]) – Path to save HESeries.
data_level (Optional[Union[int, str]], optional) – If not None, then save the data with the specified level. If it is minimum, save ciphertexts with the smallest extended bootstrappable level. Defaults to None.
vbit_level (Optional[Union[int, str]], optional) – If not None, then save the data with the specified level. If it is minimum, save ciphertexts with the smallest bootstrappable level. Defaults to None.

skew() → HESeries

Compute the sample skewness for HESeries.

Returns:: HESeries of length 1 containing the skewness.
Return type:: HESeries

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([5,-3,6,4,126.3])
>>> hs = heaan_sdk.HESeries.from_series(context, ps)
>>> hs.encrypt()
>>> hs_skew = hs.skew()
>>> hs_skew.decrypt()
>>> hs_skew.to_series()
0    1.062129
dtype: float64

std() → HESeries

Compute the sample standard deviation for HESeries.

Returns:: HESeries of length 1 containing the standard deviation.
Return type:: HESeries

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps)
>>> hs.encrypt()
>>> hs_std = hs.std()
>>> hs_std.decrypt()
>>> hs_std.to_series()
0    1.581139
dtype: float64

sum() → HESeries

Compute the sum for HESeries.

Returns:: HESeries of length 1 containing the sum.
Return type:: HESeries

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps)
>>> hs.encrypt()
>>> hs_sum = hs.sum()
>>> hs_sum.decrypt()
>>> hs_sum.to_series()
0    15
dtype: int64

t_interval_for_mean(conf_level: float = 0.95) → HESeries

Compute the confidence interval of the mean of HESeries with t-distribution.

Parameters:: conf_level (float, optional) – Confidence level. It should be in the range [0, 1]. Defaults to 0.95.
Returns:: HESeries containing information of the confidence interval. If it is converted to pandas Series by to_series(), the result becomes of length 2 where the lower limit is stored in the first slot and upper limit is stored in the second slot.
Return type:: HESeries

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps)
>>> hs.encrypt()
>>> hs_t_interval = hs.t_interval_for_mean(conf_level=0.95)
>>> hs_t_interval.decrypt()
>>> hs_t_interval.to_series()
0    1.036757
1    4.963243
dtype: float64

t_test(popmean: float) → HESeries

Compute T-test for the mean of HESeries.

Parameters:: popmean (float) – Expected value in null hypothesis.
Returns:: HESeries of length 2 where the computed t-statistic is stored in the first slot, degrees of freedom is stored in the second slot.
Return type:: HESeries

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps)
>>> hs.encrypt()
>>> hs_t_test = hs.t_test(popmean=2.5)
>>> hs_t_test.decrypt()
>>> hs_t_test.to_series()
0    0.707107
1    4.000000
dtype: float64

to_calculate_form(exponent: int | None = None, remained_cost_level: int = 2) → HESeries

Calculate data, expo and vbit of each HEUnitSeries in HESeries for more efficient computation. The procedure is as follows. Frist, fit exponents of elements to a specific value. Second, if a slot is invalid, set the slot to zero. Even though HESeries has vbit or exponent part, the output does not have vbit and exponent part.

Parameters:

exponent (Optional[int], optional) – Integer to set exponent of all data. If None, use maximum of exponents of HESeries. Defaults to None.
remained_cost_level (int, optional) – Remained_cost_level of the output.

Returns:

HESeries where HEUnitSeries which consists of data Block only.

Return type:

to_series() → Series

Convert HESeries to pandas Series.

Returns:

Pandas Series created from HESeries.

Return type:

pd.Series

Raises:

TypeError – When HESeries is encrypted.
ValueError – When vbit of HESeries is not strict. The value of vbit should be very close to 0 or 1.

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps)
>>> hs.to_series()
0    1
1    2
2    3
3    4
4    5
dtype: int64

property unique: List[int | str] | None

Unique values of HESeries if HESeries is categorical, None otherwise.

Returns:: Unique values of HESeries.
Return type:: Optional[List[Union[int, str]]]

unit_series(idx: int) → HEUnitSeries

Return the idx-th HEUnitSeries in HESeries.

Returns:: HEUnitSeries corresponding to index in HESeries.
Return type:: HEUnitSeries

var() → HESeries

Compute the sample variance for HESeries.

Returns:: HESeries of length 1 containing the variance.
Return type:: HESeries

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps)
>>> hs.encrypt()
>>> hs_var = hs.var()
>>> hs_var.decrypt()
>>> hs_var.to_series()
0    2.5
dtype: float64

property vbit_encrypted: bool

Whether vbit of HESeries is encrypted or not.

Returns:: Whether vbit of HESeries is encrypted.
Return type:: bool

property vbit_level: int

The smallest level of vbit in HESeries. Returns sys.maxsize if vbit is plaintext or does not exist.

Returns:: The smallest level of vbit in HESeries.
Return type:: int

z_interval_for_mean(conf_level: float = 0.95) → HESeries

Compute the confidence interval of the mean of HESeries with z-distribution.

Parameters:: conf_level (float, optional) – Confidence level. It should be in the range [0, 1]. Defaults to 0.95.
Returns:: HESeries containing information of the confidence interval. If it is converted to pandas Series by to_series(), the result becomes of length 2 where the lower limit is stored in the first slot and upper limit is stored in the second slot.
Return type:: HESeries

Examples

>>> import heaan_sdk
>>> import pandas as pd
>>> params = heaan_sdk.HEParameter.from_preset("FGb")
>>> context = heaan_sdk.Context(params, key_dir_path="keys", load_keys="all", generate_keys=True)
>>> ps = pd.Series([1,2,3,4,5])
>>> hs = heaan_sdk.HESeries.from_series(context, ps)
>>> hs.encrypt()
>>> hs_z_interval = hs.z_interval_for_mean(conf_level=0.95)
>>> hs_z_interval.decrypt()
>>> hs_z_interval.to_series()
0    1.614096
1    4.385904
dtype: float64

HEUnitSeries is the smallest unit class used in Statistics. Three inputs, data, expo, and vbit, are processed into Block, Number or None. This consists of at most 3 Blocks called self.data, self.expo and self.vbit. Note that self.data and self.vbit are Blocks or None, but self.expo is Block or number and cannot be None even if None is entered.

Create HEUnitSeries object.

Parameters:

context (Context) – Context of HEUnitSeries.
data (Optional[Union[Block, Number, Iterable[Number]]], optional) – Data (mantissa). Defaults to None.
expo (Optional[Union[Block, Number, Iterable[Number]]], optional) – Exponent. Defaults to None.
(Optional[Union[Block (vbit) – Valid bit. Defaults to None.
Iterable[Number]]] – Valid bit. Defaults to None.
optional – Valid bit. Defaults to None.
encrypt_vbit (bool, optional) – Whether to encrypt valid bit when HEUnitSeries is encrypted. Defaults to False.
copy_data (bool, optional) – Whether HEUnitSeries use copy of input data if input data is Block. Defaults to True.
copy_expo (bool, optional) – Whether HEUnitSeries use copy of input expo if input expo is Block. Defaults to True.
copy_vbit (bool, optional) – Whether HEUnitSeries use copy of input vbit if input vbit is Block. Defaults to True.

bootstrap() → HEUnitSeries

Bootstrap HEUnitSeries.

Returns:: Bootstrapped HEUnitSeries.
Return type:: HEUnitSeries

bootstrap_extended() → HEUnitSeries

Bootstrap HEUnitSeries in large range. See bootstrap_extended in Block class for more details.

Returns:: Bootstrapped HEUnitSeries.
Return type:: HEUnitSeries

compare(other: HEUnitSeries, numiter_g: int = 8, numiter_f: int = 3) → HEUnitSeries

Compare whether self is greater than other. If this is plaintext, the result is exactly calculated. Otherwise, it uses an approximated method. In this case, the absolute values of difference of self and other must fit in [2^-18, 1]. This range could be changed if numiter_g and numiter_f are different from the default values.

\[\begin{split}&\text{If } self - other \in [-1, 1],\\ &Compare(self, other) = \begin{cases} 0 &\text{if} & -1 & \leq & self - other & < & -2^{-18},\\ y \in (0, 1) & \text{if} & -2^{-18} & < & self - other & < & 2^{-18},\\ 1 & \text{if} & 2^{-18} & < & self - other & \leq & 1. \end{cases}\end{split}\]

Parameters:

self (HEUnitSeries) – HEUnitSeries to compare with.
other (HEUnitSeries) – HEUnitSeries to compare with.
numiter_g (int, optional) – Number of iterations of approximating function g. Defaults to 8.
numiter_f (int, optional) – Number of iterations of approximating function f. Defaults to 3.

Returns:

HEUnitSeries where the data is the result of the comparison.

Return type:

conjugate(inplace=False) → HEUnitSeries

Complex conjugation of HEUnitSeries.

Parameters:: inplace (bool, optional) – Whether to modify HEUnitSeries rather than creating a new one. Defaults to False.
Returns:: Complex conjugated HEUnitSeries.
Return type:: HEUnitSeries

copy() → HEUnitSeries

Copy HEUnitSeries to new location on memory.

Returns:: Copied HEUnitSeries
Return type:: HEUnitSeries

property data_encrypted: bool

Whether data of HEUnitSeries is encrypted or not.

Returns:: Whether data of HEUnitSeries is encrypted.
Return type:: bool

property data_level: int

The smallest level of data in HEUnitSeries.

Returns:: The smallest level of data in HEUnitSeries.
Return type:: int

decrypt(inplace: bool = True) → HEUnitSeries

Decrypt HEUnitSeries.

Parameters:: inplace (bool, optional) – Whether to modify HEUnitSeries rather than creating a new one. Defaults to True.
Returns:: Decrypted HEUnitSeries.
Return type:: HEUnitSeries
Raises:: TypeError – When HEUnitSeries is already plaintext.

encrypt(data_level: int | None = None, vbit_level: int | None = None, inplace: bool = True) → HEUnitSeries

Encrypt HEUnitSeries.

Parameters:

data_level (Optional[int], optional) – Target level of data for encryption. If None, then the result ciphertext would have maximum level. Defaults to None.
vbit_level (Optional[int], optional) – Target level of vbit for encryption. If None, then the result ciphertext would have maximum level. Defaults to None.
inplace (bool, optional) – Whether to modify HEUnitSeries rather than creating a new one. Defaults to True.

Returns:

Encrypted HEUnitSeries.

Return type:

Raises:

TypeError – When HEUnitSeries is already encrypted.

property encrypted: bool

Whether HEUnitSeries is encrypted or not.

Returns:: Whether HEUnitSeries is encrypted.
Return type:: bool

property expo_series: Series | float | int

Return exponents of HEUnitSeries. It could be a Pandas Series if the exponent part is block, float or integer otherwise.

Returns:: Exponents of HEUnitSeries.
Return type:: Union[pd.Series, float, int]

classmethod fill(context: Context, value: Number, expo: Number | None = None) → HEUnitSeries

Build HEUnitSeries filled with a given value.

Parameters:

context (Context) – Context of HEUnitSeries.
value (Number) – Value to fill HEUnitSeries with.
expo (Optional[Number]) – Value to use exponent of value. If None, choose an exponent making mantissa of the value to be single figures. Defaults to None.

Returns:

HEUnitSeries filled with a sepcific value.

Return type:

classmethod from_block(block: Block) → HEUnitSeries

Create HEUnitSeries from Block.

Parameters:: block (Block) – Block to create HEUnitSeries from.
Returns:: HEUnitSeries created from the block.
Return type:: HEUnitSeries

classmethod from_path(context: Context, path: str | Path) → HEUnitSeries

Create HEUnitSeries and load data from path into HEUnitSeries.

Parameters:

context (Context) – Context of HEUnitSeries to be loaded.
path (Union[str, Path]) – Path to load data.

Returns:

Loaded HEUnitSeries.

Return type:

classmethod from_series(context: Context, series: Series, create_expo: bool = False, encrypt_vbit: bool = False) → HEUnitSeries

Create a HEUnitSeries from a pandas Series.

Parameters:

context (Context) – Context of HEUnitSeries.
series (pd.Series) – Pandas Series to create HEUnitSeries from.
create_expo (bool, optional) – Whether to create exponent. If it is false, encode data in floating-point representation. Defaults to False.
encrypt_vbit (bool, optional) – Whether to encrypt valid bit of HEUnitSeries or not. Defaults to False.

Returns:

HEUnitSeries created from pandas Series.

Return type:

get_min_max(other: HEUnitSeries, ascent: bool) → Tuple[HEUnitSeries, HEUnitSeries]: If ascent=True, return [min, max], else, [max, min]

i_mult(inplace=False) → HEUnitSeries

Multiply sqrt(-1) to HEUnitSeries.

Parameters:: inplace (bool, optional) – Whether to modify HEUnitSeries rather than creating a new one. Defaults to False.
Returns:: HEUnitSeries multiplied by sqrt(-1).
Return type:: HEUnitSeries

inverse(greater_than_one: bool, inplace: bool = False) → HEUnitSeries

Calculates 1/x. Calculate the reciprocal of the data of HEUnitSeries and change the sign of exponent. If this is plaintext, the result is exactly calculated. Otherwise, it uses an approximated method. In this case, if greater_than_one is true, the data must fit in [1, 2^18]. If greater_than_one is false, the data must fit in [2^-10, 1].

Parameters:

greater_than_one (bool) – Whether the data of HEUnitSeries are greater than one or not.
inplace (bool, optional) – Whether to modify HEUnitSeries rather than creating a new one. Defaults to False.

Returns:

HEUnitSeries where the values are the reciprocal of the originals.

Return type:

property is_complex: bool

Whether data of HEUnitSeries consist of complex numbers.

Returns:: Whether data of HEUnitSeries consist of complex numbers.
Return type:: bool

property level: int

The smallest level of data or vbit in HEUnitSeries.

Returns:: The smallest level of data or vbit in HEUnitSeries.
Return type:: int

level_down(data_level: int | None = None, vbit_level: int | None = None, inplace: bool = True) → HEUnitSeries

Down level of HEUnitSeries to the target level.

Parameters:

data_level (Optional[int], optional) – Down level of data with specified level. Defaults to None.
vbit_level (Optional[int], optional) – Down level of vbit with specified level. Defaults to None.
inplace (bool, optional) – Whether to modify HEUnitSeries rather than creating a new one. Defaults to True.

Returns:

HEUnitSeries where data and vbit have specific level.

Return type:

load(path: str | Path) → None

Load HEUnitSeries.

Parameters:: path (Union[str, Path]) – Path to load data.

property max_expo: float

Maximum of exponents of HEUnitSeries.

Returns:: Maximum of exponents of HEUnitSeries.
Return type:: float

property num_slots: int

Number of slots of the context of HEUnitSeries.

Returns:: Number of slots of the context of HEUnitSeries.
Return type:: int

on_cpu() → bool

Returns true if HEUnitSeries is on CPU.

Returns:: True if HEUnitSeries is on CPU, false otherwise.
Return type:: bool
Raises:: TypeError – When device types of data and vbit are different.

on_gpu() → bool

Returns true if HEUnitSeries is on GPU.

Returns:: True if HEUnitSeries is on GPU, false otherwise.
Return type:: bool
Raises:: TypeError – When device types of data and vbit are different.

property remained_cost_level: int

The remained level before bootstrapping if the context is bootstrappable. Otherwise, level of self.

Returns:: The remained level before bootstrapping if the context is bootstrappable. Otherwise, level of self.
Return type:: int

rotate_sum(rot_num: int | None = None, left_rotate: bool = True, inplace=False) → HEUnitSeries

Rotate HEUnitSeries and accumulate the rotated ones to add them up. The result is HEUnitSeries: such that each slot is the sum of ‘2**rot_num’ consecutive values.

Parameters:

rot_num (Optional[int], optional) – How many times to repeat rotation and addition. If this is None, the number of iterations is set to context.log_slots. Defaults to None.
left_rotate (bool, optional) – Direction of rotation. Defaults to True.
inplace (bool, optional) – Whether to modify HEUnitSeries rather than creating a new one. Defaults to False.

Returns:

HEUnitSeries filled with sum of all values.

Return type:

save(path: str | Path, data_level: int | None = None, vbit_level: int | None = None) → None

Save HEUnitSeries.

Parameters:

path (Union[str, Path]) – Path to save HEUnitSeries.
data_level (Optional[int], optional) – If not None, then save the data with the specified level. Defaults to None.
vbit_level (Optional[int], optional) – If not None, then save the vbit with the specified level if vbit exists. Defaults to None.

sort(N: int, ascent: bool = True, inplace: bool = False, only_last_stage: bool = False) → HEUnitSeries | None

Sorts values in HEUnitSeries. The range of values should be [-0.5, 0.5].

Parameters:

N (int) – Number of data. (1<=N<=num_slots)
ascent (bool) – If true, sort in ascending order.
only_last_stage (bool) – If true, it only performs bitonic merge(the last part for the entire sort) rather than the entire sort. Defaults to False

sqrt(inplace: bool = False) → HEUnitSeries

Calculates sqrt(x). Calculate the square root of the data of HEUnitSeries and divide the exponent by 2. If this is plaintext, the result is exactly calculated. Otherwise, it uses an approximated method. In this case, the data must fit in [2^-18, 2].

Parameters:: inplace (bool, optional) – Whether to modify HEUnitSeries rather than creating a new one. Defaults to False.
Returns:: HEUnitSeries where the values are the square root of the originals.
Return type:: HEUnitSeries

sqrt_inv(greater_than_one: bool, inplace: bool = False) → HEUnitSeries

Calculates 1/sqrt(x). Calculate the square root of reciprocal of the data of HEUnitSeries and devide the exponent by -2. If this is plaintext, the result is exactly calculated. Otherwise, it uses an approximated method. In this case, if greater_than_one is true, the data must fit in [1, 2^22]. If greater_than_one is false, the data must fit in [2^-10, 1].

Parameters:

greater_than_one (bool) – Whether the data of HEUnitSeries are greater than one or not.
inplace (bool, optional) – Whether to modify HEUnitSeries rather than creating a new one. Defaults to False.

Returns:

HEUnitSeries where the data are the square root of reciprocal of the originals.

Return type:

to(device) → HEUnitSeries

Send HEUnitSeries to device.

Returns:: Sent self HEUnitSeries
Return type:: HEUnitSeries

to_calculate_form(exponent: int | float | None = None, inplace: bool = False) → HEUnitSeries

Calculate data, expo and vbit of HEUnitSeries for more efficient computation. The procedure is as follows. Frist, fit exponents of elements to a specific value. Second, if a slot is invalid, set the slot to zero. Even though HEUnitSeries has vbit or exponent part, the output does not have vbit and exponent part.

Parameters:

exponent (Optional[float], optional) – Integer or float to set exponent of all data. If None, use maximum of exponents of HEUnitSeries. Defaults to None.
inplace (bool, optional) – Whether to modify HEUnitSeries rather than creating a new one. Defaults to False.

Returns:

HEUnitSeries which consists of data Block only.

Return type: