Featurisation

Featurization (`payn.Featurisation.Featurisation`)

Orchestrates the transformation of raw chemical identifiers (SMILES) into machine-readable numerical vectors. It supports a hybrid approach, allowing the generation of new fingerprints (ECFP, MFF) alongside the ingestion of pre-calculated molecular descriptors (e.g., DFT properties).

Bit Condensation: Implements a condensed_bits function that automatically identifies and removes bit positions with zero variance across the dataset, reducing feature sparsity and dimensionality without information loss.
Deterministic Featurization: The explicit transform pipeline ensures that feature vectors are generated identically for every run given the same configuration.
Binary Classification: The pipeline includes a binary classification wrapper (classify_binary) that strictly maps continuous regression targets (e.g., yield %) to binary labels (Negative/Positive) based on a fixed threshold.

Multi-Feature Fingerprinting (MFF) Reimplementation (`payn.Featurisation.MFFFingerprinter`)

Reimplementation of the feature generation strategy from EasyChemML, designed to maximize information capture by stacking diverse cheminformatics descriptors.

The MFF vector is a concatenation of the following molecular representations, computed using RDKit:

Connectivity: RDKit Fingerprints (branched and linear paths, lengths 2, 4, 6, 8).
Circular: Morgan/ECFP fingerprints (radii 0, 2, 4, 6), computed both with standard invariants and feature-based invariants (FCFP).
Substructure: Layered Fingerprints (max paths 2, 4, 6, 8) and MACCS Keys (167 bits).
Topology: Avalon, Atom Pairs, and Topological Torsion descriptors.

The final vector length is dynamic, determined by the base bit_length parameter (default 2048) multiplied by the 22 variable-length components, plus the fixed-length MACCS keys. A local caching mechanism (_fingerprint_cache) ensures that identical SMILES strings within a dataset yield identical vectors without redundant computation. Missing data (flagged via absence_flag) is deterministically mapped to a zero-vector of the exact expected length, preserving matrix shape integrity.

Class for featurising the raw input data.

Orchestrates the conversion of SMILES strings into numerical vectors (fingerprints) and initializes metadata columns based on the configuration.

Attributes:

Name	Type	Description
`input_file_path`	`str`	Path to the input file.
`sheet_name`	`str`	Name of the sheet in the input file.
`columns`	`List[str]`	Columns with SMILES to be processed into fingerprints.
`method`	`str`	Fingerprinting method ('ECFP' or 'MFF').
`bit_length`	`int`	Length of fingerprint vector.
`radius`	`int`	Radius of ECFP fingerprint.
`condensed_bits`	`bool`	If True, removes invariable bits (all 0s or all 1s).
`combined_features_column_name`	`str`	Name for the final concatenated feature column.
`meta_columns`	`Dict[str, str]`	Mapping of internal meta keys to column names.
`raw_data`	`DataFrame`	The loaded raw dataset.

Source code in payn\Featurisation\featurisation.py

class Featurisation:
    """
    Class for featurising the raw input data.

    Orchestrates the conversion of SMILES strings into numerical vectors (fingerprints)
    and initializes metadata columns based on the configuration.

    Attributes:
        input_file_path (str): Path to the input file.
        sheet_name (str): Name of the sheet in the input file.
        columns (List[str]): Columns with SMILES to be processed into fingerprints.
        method (str): Fingerprinting method ('ECFP' or 'MFF').
        bit_length (int): Length of fingerprint vector.
        radius (int): Radius of ECFP fingerprint.
        condensed_bits (bool): If True, removes invariable bits (all 0s or all 1s).
        combined_features_column_name (str): Name for the final concatenated feature column.
        meta_columns (Dict[str, str]): Mapping of internal meta keys to column names.
        raw_data (pd.DataFrame): The loaded raw dataset.
    """

    def __init__(self, input_file_path: str,
                 sheet_name: str,
                 columns: list,
                 combined_feature_column_name: str,
                 method: str = 'ECFP',
                 bit_length: int = 2048,
                 radius: int = 2,
                 condensed_bits: bool = True,
                 meta_columns: Optional[Dict[str, str]] = None,
                 regression_column_name: str = None,
                 classification_threshold: float = None,
                 yield_limit: float = None,
                 absence_flag: list = None,
                 bin_column_name: str = None,
                 application_mode: str = None,
                 existing_feature_columns: list = None,
                 **kwargs):
        """
        Initialize the Featurisation class.
        Args:
            input_file_path (str): Path to the input file.
            sheet_name (str): Name of the sheet in the input file.
            columns (list): Columns with SMILES to be processed into fingerprints.
            combined_feature_column_name (str): Name for the final concatenated feature column.
            method (str): Fingerprinting method ('ECFP' or 'MFF').
            bit_length (int, optional): Length of ECFP fingerprint.
            radius (int, optional): Radius of ECFP fingerprint.
            condensed_bits (bool, optional): Remove invariable bits across the dataset.
            meta_columns (dict, optional): Dictionary of meta column names. Defaults to standard keys if None.
            regression_column_name (str, optional): Column name for regression target.
            classification_threshold (float, optional): Threshold for binary classification.
            yield_limit (float, optional): Yield limit for classification.
            absence_flag (str, optional): Values indicationg missing / invalid data.
            bin_column_name (str, optional): Column name for binary classification.
            application_mode (str, optional): Application mode (e.g. 'training' or 'inference').
            existing_feature_columns (str, optional): Use of existing (DFT) features instead of generating new within this featurisation.
            **kwargs: Additional parameters for DataLoader.
        Raises:
            ValueError: If the method is not 'ECFP' or 'MFF'.

        """

        self.input_file_path = input_file_path
        self.sheet_name = sheet_name
        self.columns = columns
        self.method = method
        self.bit_length = bit_length
        self.radius = radius
        self.condensed_bits = condensed_bits
        self.combined_features_column_name = combined_feature_column_name
        if meta_columns is None:
            self.meta_columns = {
                "meta_true_label_bin": "true_bin",
                "meta_mod_label_bin": "mod_bin",
                "meta_data_point_role": "augm_role",
                "meta_data_point_reg_role": "reg_role",
            }
        else:
            self.meta_columns = meta_columns

        # Optional parameters for classification; if not provided, they can be set later.
        self.regression_column_name = regression_column_name
        self.classification_threshold = classification_threshold
        self.yield_limit = yield_limit
        self.absence_flag = absence_flag
        self.bin_column_name = bin_column_name
        self.application_mode = application_mode
        # Load raw data immediately
        data_loader = DataLoader(input_file_path, **kwargs)
        self.raw_data = data_loader.load_data()
        self.existing_feature_columns = existing_feature_columns

    @classmethod
    def from_config(cls, config: Dict[str, Any], **kwargs: Any) -> "Featurisation":
        """
        Alternative constructor that extracts parameters from a config object.

        This factory method promotes the "Config as Code" pattern, ensuring
        consistent initialization from the central configuration dictionary.

        Args:
            config: The global configuration dictionary.
            **kwargs: Additional overrides.

        Returns:
            An instance of Featurisation initialized from the config.
        """
        return cls(
            input_file_path = config["dataset"]["file_path"],
            sheet_name = config["dataset"]["sheet_name"],
            columns = config["dataset"]["input_columns"],
            method = config["featurisation"]["method"],
            bit_length = config["featurisation"]["ECFP_bit_length"],
            radius = config["featurisation"]["ECFP_radius"],
            condensed_bits = config["featurisation"]["condense_bits"],
            combined_feature_column_name = config["featurisation"]["combined_features_column_name"],
            meta_columns = config["meta_columns"],
            regression_column_name=config["dataset"].get("target_column"),
            classification_threshold=config["dataset"].get("yield_classification_threshold"),
            yield_limit = config["dataset"]["yield_limit"],
            absence_flag = config["dataset"]["absence_flag"],
            bin_column_name=config["meta_columns"].get("meta_true_label_bin"),
            application_mode=config["general"]["usage_mode"],
            existing_feature_columns=config["featurisation"].get("existing_feature_columns", []),
            **kwargs
        )

    def transform(self) -> pd.DataFrame:
        """
        Orchestrate the complete featurisation pipeline.

        1. Identifies columns needing feature generation vs. existing features.
        2. Applies the selected method (ECFP/MFF) to generate fingerprints.
        3. Parses existing feature columns (e.g. from string representations).
        4. Combines all feature vectors into a single column.
        5. Initializes metadata columns.

        Returns:
            The fully featurised DataFrame.

        Raises:
            ValueError: If the configured default featurisation method is unknown.
        """
        # Step 1: Initialization
        df = self.raw_data.copy()
        all_fp_columns: List[str] = []

        # Step 2: Determine which columns to process with which method.
        generated_cols = self.columns
        existing_cols = self.existing_feature_columns

        # Step 3: Process Existing Features
        if existing_cols:
            df, existing_fp_cols = self._apply_existing_features(df, columns_to_process=list(existing_cols))
            all_fp_columns.extend(existing_fp_cols)

        # Step 4: Process Generated Features
        if generated_cols:
            if self.method.lower() == 'ecfp':
                df, generated_fp_cols = self._featurise_ECFP(df, columns_to_process=generated_cols)
                all_fp_columns.extend(generated_fp_cols)
            elif self.method.lower() == 'mff':
                df, generated_fp_cols = self._featurise_MFF(df, columns_to_process=generated_cols)
                all_fp_columns.extend(generated_fp_cols)
            else:
                raise ValueError(f"Invalid method: {self.method}. Please choose 'ECFP' or 'MFF'.")

        # Combination of all Fingerprints
        if all_fp_columns:
            df[self.combined_features_column_name] = df.apply(
                lambda row: sum([row[fp_col] for fp_col in all_fp_columns], []),
                axis=1
            )

        # Step 6: Final initializations
        df = self._initialize_meta_columns(df)
        return df

    def _initialize_meta_columns(self, df: pd.DataFrame) -> pd.DataFrame:
        """
        Initializes the metadata columns for the featurised data.
        For each meta column specified in the config, if it is not present,
        it is added and initialized with NaN.
        Args:
            df (pd.DataFrame): DataFrame to update.
        Returns:
            pd.DataFrame: New DataFrame with meta columns initialized.
        """
        for _, column_name in self.meta_columns.items():
            if column_name not in df.columns:
                df = df.assign(**{column_name: np.nan})
        return df


    def _featurise_ECFP(self, df: pd.DataFrame, columns_to_process: List[str]) -> Tuple[pd.DataFrame, List[str]]:
        """
        Featurise the input data using ECFP fingerprinting.
        Args:
            df: The input DataFrame to which new feature columns will be added.
            columns_to_process: List of column names containing SMILES to featurise.

        Returns:
            Tuple containing the modified DataFrame and a list of new feature column names.

        Raises:
            ValueError: If a specified column is not found.
        """
        new_fp_columns = []
        for col in columns_to_process:
            if col not in df.columns:
                raise ValueError(f"Column {col} not found in the input data.")

            fingerprint_series = df[col].apply(lambda x: list(
                self.convert_to_morgan_fingerprints(smile=x, radius=self.radius, bit_length=self.bit_length)))
            fp_col_name = 'FP_' + col

            if self.condensed_bits:
                df = df.assign(**{fp_col_name: self.condense_bits(fingerprint_series)})
            else:
                df = df.assign(**{fp_col_name: fingerprint_series})
            new_fp_columns.append(fp_col_name)

        return df, new_fp_columns


    def _featurise_MFF(self, df: pd.DataFrame, columns_to_process: List[str]) -> Tuple[pd.DataFrame, List[str]]:
        """
        Featurise the input data using the custom RDKit-based MFF implementation.

        Args:
            df: The input DataFrame.
            columns_to_process: List of column names containing SMILES.

        Returns:
            Tuple containing the modified DataFrame and a list of new feature column names.
        """
        new_fp_columns = []
        fingerprinter = MFFFingerprinter(bit_length=self.bit_length, absence_flag=self.absence_flag)

        for col in columns_to_process:
            if col not in df.columns:
                raise ValueError(f"Column '{col}' not found in input data.")

            smiles_list = df[col].tolist()
            fingerprints = fingerprinter.featurise(smiles_list)
            fp_col_name = f"FP_{col}"

            if self.condensed_bits:
                fp_df = pd.DataFrame(fingerprints)
                # Keep columns that are not all 0s AND not all 1s
                fp_df = fp_df.loc[:, (fp_df != 0).any(axis=0) & (fp_df != 1).any(axis=0)]
                df[fp_col_name] = fp_df.apply(lambda row: list(row), axis=1)
            else:
                df[fp_col_name] = fingerprints

            new_fp_columns.append(fp_col_name)
        return df, new_fp_columns

    def condense_bits(self, fingerprint_series: pd.Series) -> pd.Series:
        """
        Condense the fingerprint data by removing invariable bits.

        Removes bits (columns in the feature vector) that are constant (all 0 or all 1)
        across the entire provided Series.

        Args:
            fingerprint_series: Series where each entry is a list representing a fingerprint.

        Returns:
            A new Series with invariable bits removed.

        Warning:
            If this method is applied to separate data splits (e.g., train vs test)
            independently, it may result in feature vectors of different lengths.
            Ensure this is called on the global dataset before splitting.
        """
        # Expand fingerprint lists into separate columns
        expanded_df = pd.DataFrame(fingerprint_series.tolist())
        # Remove columns that are invariant (all 0s or all 1s)
        variable_bits_df = expanded_df.loc[:, (expanded_df != 0).any(axis=0) & (expanded_df != 1).any(axis=0)]
        # Convert rows back to lists
        return variable_bits_df.apply(lambda row: list(row), axis=1)

    def convert_to_morgan_fingerprints(self, smile: str, radius: int, bit_length: int) -> List[int]:
        """
        Convert a SMILES string to Morgan fingerprints.
        Args:
            smile (str): SMILES string.
            radius (int): Fingerprint radius.
            bit_length (int): Fingerprint size.
        Returns:
            list: List representation of the fingerprint.
        Raises:
            ValueError: If the molecule is invalid.
        """
        if self.absence_flag and smile in self.absence_flag:
            return [0] * self.bit_length

        mol = Chem.MolFromSmiles(smile)
        if mol is None:
            raise ValueError("Invalid molecule object.")
        mfpgen = rdFingerprintGenerator.GetMorganGenerator(radius=radius, fpSize=bit_length)
        return list(mfpgen.GetFingerprint(mol))


    def classify_binary(
        self,
        regression_column_name: str = None,
        classification_threshold: float = None,
        bin_column_name: str = None,
        labels: list = [0, 1],
        schema: DataSchema = None,
        mode: str = None,
    ) -> pd.DataFrame:
        """
        Convert regression target values into binary classification labels.

        Assumes regression values are mapped to a binary outcome based on a threshold.

        Args:
            regression_column_name: Column containing target values.
            classification_threshold: Fraction threshold (e.g. 0.2 for 20% yield).
            bin_column_name: Column name to store binary labels.
            labels: Two labels corresponding to the bins [negative, positive].
            schema: Data schema for validating operations on dataframes.
            mode: Application mode ('training' or 'inference').

        Returns:
            A new DataFrame with an added binary classification column.
        """
        regression_column_name = regression_column_name or self.regression_column_name
        classification_threshold = classification_threshold or self.classification_threshold
        bin_column_name = bin_column_name or self.bin_column_name

        if regression_column_name is None or classification_threshold is None:
            raise ValueError("Regression column or threshold not specified for binary classification.")
        df = self.transform()  # Get the immutable featurised dataframe

        threshold_value = classification_threshold * self.yield_limit  # Convert fraction to percentage scale

        # Create binary bins and assign labels
        max_yield = max(df[regression_column_name].tolist())
        df = df.assign(**{
            bin_column_name: pd.cut(
                df[regression_column_name],
                bins=[-1, threshold_value, max_yield],
                labels=labels,
                right=True,
                include_lowest=True
            ).astype(int)
        })
        if schema:
            validate_dataframe(df=df, schema=schema, mode=mode)

        return df

    def _apply_existing_features(self, df: pd.DataFrame, columns_to_process: List[str]) -> Tuple[pd.DataFrame, List[str]]:
        """
        Process columns that contain pre-computed features.

        Parses string-literals of lists (e.g., "[0, 1, 0...]") into actual list objects.

        Args:
            df: The input DataFrame.
            columns_to_process: List of column names containing features strings.

        Returns:
            Tuple containing the modified DataFrame and a list of new feature column names.

        Raises:
            ValueError: If a specified column is not found.
        """
        new_fp_columns=[]

        # Process each column specified in the config
        for col in columns_to_process:
            if col not in df.columns:
                raise ValueError(f"Column {col} not found in the input data.")

            fp_col_name = 'FP_' + col
            df[fp_col_name] = df[col].apply(ast.literal_eval)
            new_fp_columns.append(fp_col_name)

        return df, new_fp_columns

`init(input_file_path, sheet_name, columns, combined_feature_column_name, method='ECFP', bit_length=2048, radius=2, condensed_bits=True, meta_columns=None, regression_column_name=None, classification_threshold=None, yield_limit=None, absence_flag=None, bin_column_name=None, application_mode=None, existing_feature_columns=None, **kwargs)`

Initialize the Featurisation class. Args: input_file_path (str): Path to the input file. sheet_name (str): Name of the sheet in the input file. columns (list): Columns with SMILES to be processed into fingerprints. combined_feature_column_name (str): Name for the final concatenated feature column. method (str): Fingerprinting method ('ECFP' or 'MFF'). bit_length (int, optional): Length of ECFP fingerprint. radius (int, optional): Radius of ECFP fingerprint. condensed_bits (bool, optional): Remove invariable bits across the dataset. meta_columns (dict, optional): Dictionary of meta column names. Defaults to standard keys if None. regression_column_name (str, optional): Column name for regression target. classification_threshold (float, optional): Threshold for binary classification. yield_limit (float, optional): Yield limit for classification. absence_flag (str, optional): Values indicationg missing / invalid data. bin_column_name (str, optional): Column name for binary classification. application_mode (str, optional): Application mode (e.g. 'training' or 'inference'). existing_feature_columns (str, optional): Use of existing (DFT) features instead of generating new within this featurisation. **kwargs: Additional parameters for DataLoader. Raises: ValueError: If the method is not 'ECFP' or 'MFF'.

Source code in payn\Featurisation\featurisation.py

def __init__(self, input_file_path: str,
             sheet_name: str,
             columns: list,
             combined_feature_column_name: str,
             method: str = 'ECFP',
             bit_length: int = 2048,
             radius: int = 2,
             condensed_bits: bool = True,
             meta_columns: Optional[Dict[str, str]] = None,
             regression_column_name: str = None,
             classification_threshold: float = None,
             yield_limit: float = None,
             absence_flag: list = None,
             bin_column_name: str = None,
             application_mode: str = None,
             existing_feature_columns: list = None,
             **kwargs):
    """
    Initialize the Featurisation class.
    Args:
        input_file_path (str): Path to the input file.
        sheet_name (str): Name of the sheet in the input file.
        columns (list): Columns with SMILES to be processed into fingerprints.
        combined_feature_column_name (str): Name for the final concatenated feature column.
        method (str): Fingerprinting method ('ECFP' or 'MFF').
        bit_length (int, optional): Length of ECFP fingerprint.
        radius (int, optional): Radius of ECFP fingerprint.
        condensed_bits (bool, optional): Remove invariable bits across the dataset.
        meta_columns (dict, optional): Dictionary of meta column names. Defaults to standard keys if None.
        regression_column_name (str, optional): Column name for regression target.
        classification_threshold (float, optional): Threshold for binary classification.
        yield_limit (float, optional): Yield limit for classification.
        absence_flag (str, optional): Values indicationg missing / invalid data.
        bin_column_name (str, optional): Column name for binary classification.
        application_mode (str, optional): Application mode (e.g. 'training' or 'inference').
        existing_feature_columns (str, optional): Use of existing (DFT) features instead of generating new within this featurisation.
        **kwargs: Additional parameters for DataLoader.
    Raises:
        ValueError: If the method is not 'ECFP' or 'MFF'.

    """

    self.input_file_path = input_file_path
    self.sheet_name = sheet_name
    self.columns = columns
    self.method = method
    self.bit_length = bit_length
    self.radius = radius
    self.condensed_bits = condensed_bits
    self.combined_features_column_name = combined_feature_column_name
    if meta_columns is None:
        self.meta_columns = {
            "meta_true_label_bin": "true_bin",
            "meta_mod_label_bin": "mod_bin",
            "meta_data_point_role": "augm_role",
            "meta_data_point_reg_role": "reg_role",
        }
    else:
        self.meta_columns = meta_columns

    # Optional parameters for classification; if not provided, they can be set later.
    self.regression_column_name = regression_column_name
    self.classification_threshold = classification_threshold
    self.yield_limit = yield_limit
    self.absence_flag = absence_flag
    self.bin_column_name = bin_column_name
    self.application_mode = application_mode
    # Load raw data immediately
    data_loader = DataLoader(input_file_path, **kwargs)
    self.raw_data = data_loader.load_data()
    self.existing_feature_columns = existing_feature_columns

`classify_binary(regression_column_name=None, classification_threshold=None, bin_column_name=None, labels=[0, 1], schema=None, mode=None)`

Convert regression target values into binary classification labels.

Assumes regression values are mapped to a binary outcome based on a threshold.

Parameters:

Name	Type	Description	Default
`regression_column_name`	`str`	Column containing target values.	`None`
`classification_threshold`	`float`	Fraction threshold (e.g. 0.2 for 20% yield).	`None`
`bin_column_name`	`str`	Column name to store binary labels.	`None`
`labels`	`list`	Two labels corresponding to the bins [negative, positive].	`[0, 1]`
`schema`	`DataSchema`	Data schema for validating operations on dataframes.	`None`
`mode`	`str`	Application mode ('training' or 'inference').	`None`

Returns:

Type	Description
`DataFrame`	A new DataFrame with an added binary classification column.

Source code in payn\Featurisation\featurisation.py

def classify_binary(
    self,
    regression_column_name: str = None,
    classification_threshold: float = None,
    bin_column_name: str = None,
    labels: list = [0, 1],
    schema: DataSchema = None,
    mode: str = None,
) -> pd.DataFrame:
    """
    Convert regression target values into binary classification labels.

    Assumes regression values are mapped to a binary outcome based on a threshold.

    Args:
        regression_column_name: Column containing target values.
        classification_threshold: Fraction threshold (e.g. 0.2 for 20% yield).
        bin_column_name: Column name to store binary labels.
        labels: Two labels corresponding to the bins [negative, positive].
        schema: Data schema for validating operations on dataframes.
        mode: Application mode ('training' or 'inference').

    Returns:
        A new DataFrame with an added binary classification column.
    """
    regression_column_name = regression_column_name or self.regression_column_name
    classification_threshold = classification_threshold or self.classification_threshold
    bin_column_name = bin_column_name or self.bin_column_name

    if regression_column_name is None or classification_threshold is None:
        raise ValueError("Regression column or threshold not specified for binary classification.")
    df = self.transform()  # Get the immutable featurised dataframe

    threshold_value = classification_threshold * self.yield_limit  # Convert fraction to percentage scale

    # Create binary bins and assign labels
    max_yield = max(df[regression_column_name].tolist())
    df = df.assign(**{
        bin_column_name: pd.cut(
            df[regression_column_name],
            bins=[-1, threshold_value, max_yield],
            labels=labels,
            right=True,
            include_lowest=True
        ).astype(int)
    })
    if schema:
        validate_dataframe(df=df, schema=schema, mode=mode)

    return df

`condense_bits(fingerprint_series)`

Condense the fingerprint data by removing invariable bits.

Removes bits (columns in the feature vector) that are constant (all 0 or all 1) across the entire provided Series.

Parameters:

Name	Type	Description	Default
`fingerprint_series`	`Series`	Series where each entry is a list representing a fingerprint.	required

Returns:

Type	Description
`Series`	A new Series with invariable bits removed.

Warning

If this method is applied to separate data splits (e.g., train vs test) independently, it may result in feature vectors of different lengths. Ensure this is called on the global dataset before splitting.

Source code in payn\Featurisation\featurisation.py

def condense_bits(self, fingerprint_series: pd.Series) -> pd.Series:
    """
    Condense the fingerprint data by removing invariable bits.

    Removes bits (columns in the feature vector) that are constant (all 0 or all 1)
    across the entire provided Series.

    Args:
        fingerprint_series: Series where each entry is a list representing a fingerprint.

    Returns:
        A new Series with invariable bits removed.

    Warning:
        If this method is applied to separate data splits (e.g., train vs test)
        independently, it may result in feature vectors of different lengths.
        Ensure this is called on the global dataset before splitting.
    """
    # Expand fingerprint lists into separate columns
    expanded_df = pd.DataFrame(fingerprint_series.tolist())
    # Remove columns that are invariant (all 0s or all 1s)
    variable_bits_df = expanded_df.loc[:, (expanded_df != 0).any(axis=0) & (expanded_df != 1).any(axis=0)]
    # Convert rows back to lists
    return variable_bits_df.apply(lambda row: list(row), axis=1)

`convert_to_morgan_fingerprints(smile, radius, bit_length)`

Convert a SMILES string to Morgan fingerprints. Args: smile (str): SMILES string. radius (int): Fingerprint radius. bit_length (int): Fingerprint size. Returns: list: List representation of the fingerprint. Raises: ValueError: If the molecule is invalid.

Source code in payn\Featurisation\featurisation.py

def convert_to_morgan_fingerprints(self, smile: str, radius: int, bit_length: int) -> List[int]:
    """
    Convert a SMILES string to Morgan fingerprints.
    Args:
        smile (str): SMILES string.
        radius (int): Fingerprint radius.
        bit_length (int): Fingerprint size.
    Returns:
        list: List representation of the fingerprint.
    Raises:
        ValueError: If the molecule is invalid.
    """
    if self.absence_flag and smile in self.absence_flag:
        return [0] * self.bit_length

    mol = Chem.MolFromSmiles(smile)
    if mol is None:
        raise ValueError("Invalid molecule object.")
    mfpgen = rdFingerprintGenerator.GetMorganGenerator(radius=radius, fpSize=bit_length)
    return list(mfpgen.GetFingerprint(mol))

`from_config(config, **kwargs)` `classmethod`

Alternative constructor that extracts parameters from a config object.

This factory method promotes the "Config as Code" pattern, ensuring consistent initialization from the central configuration dictionary.

Parameters:

Name	Type	Description	Default
`config`	`Dict[str, Any]`	The global configuration dictionary.	required
`**kwargs`	`Any`	Additional overrides.	`{}`

Returns:

Type	Description
`Featurisation`	An instance of Featurisation initialized from the config.

Source code in payn\Featurisation\featurisation.py

@classmethod
def from_config(cls, config: Dict[str, Any], **kwargs: Any) -> "Featurisation":
    """
    Alternative constructor that extracts parameters from a config object.

    This factory method promotes the "Config as Code" pattern, ensuring
    consistent initialization from the central configuration dictionary.

    Args:
        config: The global configuration dictionary.
        **kwargs: Additional overrides.

    Returns:
        An instance of Featurisation initialized from the config.
    """
    return cls(
        input_file_path = config["dataset"]["file_path"],
        sheet_name = config["dataset"]["sheet_name"],
        columns = config["dataset"]["input_columns"],
        method = config["featurisation"]["method"],
        bit_length = config["featurisation"]["ECFP_bit_length"],
        radius = config["featurisation"]["ECFP_radius"],
        condensed_bits = config["featurisation"]["condense_bits"],
        combined_feature_column_name = config["featurisation"]["combined_features_column_name"],
        meta_columns = config["meta_columns"],
        regression_column_name=config["dataset"].get("target_column"),
        classification_threshold=config["dataset"].get("yield_classification_threshold"),
        yield_limit = config["dataset"]["yield_limit"],
        absence_flag = config["dataset"]["absence_flag"],
        bin_column_name=config["meta_columns"].get("meta_true_label_bin"),
        application_mode=config["general"]["usage_mode"],
        existing_feature_columns=config["featurisation"].get("existing_feature_columns", []),
        **kwargs
    )

`transform()`

Orchestrate the complete featurisation pipeline.

Identifies columns needing feature generation vs. existing features.
Applies the selected method (ECFP/MFF) to generate fingerprints.
Parses existing feature columns (e.g. from string representations).
Combines all feature vectors into a single column.
Initializes metadata columns.

Returns:

Type	Description
`DataFrame`	The fully featurised DataFrame.

Raises:

Type	Description
`ValueError`	If the configured default featurisation method is unknown.

Source code in payn\Featurisation\featurisation.py

def transform(self) -> pd.DataFrame:
    """
    Orchestrate the complete featurisation pipeline.

    1. Identifies columns needing feature generation vs. existing features.
    2. Applies the selected method (ECFP/MFF) to generate fingerprints.
    3. Parses existing feature columns (e.g. from string representations).
    4. Combines all feature vectors into a single column.
    5. Initializes metadata columns.

    Returns:
        The fully featurised DataFrame.

    Raises:
        ValueError: If the configured default featurisation method is unknown.
    """
    # Step 1: Initialization
    df = self.raw_data.copy()
    all_fp_columns: List[str] = []

    # Step 2: Determine which columns to process with which method.
    generated_cols = self.columns
    existing_cols = self.existing_feature_columns

    # Step 3: Process Existing Features
    if existing_cols:
        df, existing_fp_cols = self._apply_existing_features(df, columns_to_process=list(existing_cols))
        all_fp_columns.extend(existing_fp_cols)

    # Step 4: Process Generated Features
    if generated_cols:
        if self.method.lower() == 'ecfp':
            df, generated_fp_cols = self._featurise_ECFP(df, columns_to_process=generated_cols)
            all_fp_columns.extend(generated_fp_cols)
        elif self.method.lower() == 'mff':
            df, generated_fp_cols = self._featurise_MFF(df, columns_to_process=generated_cols)
            all_fp_columns.extend(generated_fp_cols)
        else:
            raise ValueError(f"Invalid method: {self.method}. Please choose 'ECFP' or 'MFF'.")

    # Combination of all Fingerprints
    if all_fp_columns:
        df[self.combined_features_column_name] = df.apply(
            lambda row: sum([row[fp_col] for fp_col in all_fp_columns], []),
            axis=1
        )

    # Step 6: Final initializations
    df = self._initialize_meta_columns(df)
    return df

Featurisation

Featurization (payn.Featurisation.Featurisation)

Multi-Feature Fingerprinting (MFF) Reimplementation (payn.Featurisation.MFFFingerprinter)

classify_binary(regression_column_name=None, classification_threshold=None, bin_column_name=None, labels=[0, 1], schema=None, mode=None)

condense_bits(fingerprint_series)

convert_to_morgan_fingerprints(smile, radius, bit_length)

from_config(config, **kwargs) classmethod

transform()

Featurization (`payn.Featurisation.Featurisation`)

Multi-Feature Fingerprinting (MFF) Reimplementation (`payn.Featurisation.MFFFingerprinter`)

`classify_binary(regression_column_name=None, classification_threshold=None, bin_column_name=None, labels=[0, 1], schema=None, mode=None)`

`condense_bits(fingerprint_series)`

`convert_to_morgan_fingerprints(smile, radius, bit_length)`

`from_config(config, **kwargs)` `classmethod`

`transform()`