API Reference

This section provides detailed API documentation for all public modules and classes in SynCCFD.

Simulator

class synccfd.simulator.generator.DatasetGenerator(n_customers=10000, n_terminals=20000, nb_days=90, city_radius=12.0, available_terminals_radius=10.0, start_date='2018-04-01', random_state=42)[source]

Bases: object

Main entry point for generating synthetic credit card fraud datasets.

This class provides a simple interface to generate synthetic credit card transaction datasets including customer profiles, terminal profiles, and transactions with fraud labels.

The generator creates realistic transaction patterns based on: - Customer location and spending habits - Terminal distribution across cities - Time-based transaction patterns (different for CP vs CNP transactions) - Four different fraud scenarios

Example

>>> generator = DatasetGenerator(n_customers=1000, n_terminals=10000)
>>> customer_profiles, terminal_profiles, transactions = generator.generate()
>>> print(f"Generated {len(transactions)} transactions")

Parameters:

n_customers (int)
n_terminals (int)
nb_days (int)
city_radius (float)
available_terminals_radius (float)
start_date (str)
random_state (int | None)

generate()[source]

Generate the complete dataset (profiles + labelled transactions).

The generator follows these steps: 1. Generate customer profiles with random locations and spending patterns 2. Generate terminal profiles with locations across cities 3. Generate legitimate transactions based on customer-terminal proximity 4. Add fraudulent transactions based on different fraud scenarios

Returns:

customer_profiles (pd.DataFrame): Customer information with columns:
- CUSTOMER_ID: Unique customer identifier
- billing_lat, billing_long: Customer billing location
- mean_amount, std_amount: Parameters for transaction amount generation
- mean_nb_tx_per_day: Average number of transactions per day
- cnp_prob: Probability of Card Not Present transactions
terminal_profiles (pd.DataFrame): Terminal information with columns:
- TERMINAL_ID: Unique terminal identifier
- terminal_lat, terminal_long: Terminal location coordinates
transactions (pd.DataFrame): Transaction data with columns:
- TRANSACTION_ID: Unique transaction identifier
- TX_DATETIME: Transaction timestamp
- TX_TIME_SECONDS: Time in seconds since start date
- TX_TIME_DAYS: Time in days since start date
- CUSTOMER_ID: Customer who made the transaction
- TERMINAL_ID: Terminal where transaction was made
- TX_AMOUNT: Transaction amount
- TX_BILL_LAT, TX_BILL_LONG: billing address coordinates
- TX_SHIPP_LAT, TX_SHIPP_LONG: shipping address coordinates
- TX_TERM_LAT, TX_TERM_LONG: terminal location coordinates
- TX_TYPE: Transaction type (CP: Card Present, CNP: Card Not Present)
- TX_FRAUD: Binary fraud indicator
- TX_FRAUD_SCENARIO: Type of fraud (0: legitimate, 1-4: fraud scenarios)

Return type:

tuple[DataFrame, DataFrame, DataFrame]

save(output_dir='data', save_format='pkl', save_by_day=True)[source]

Persist the most recently generated dataset to disk.

Writes customer/terminal profiles and (day-partitioned) transactions under output_dir. Call generate() first.

Parameters:

output_dir (str) – Base directory to write the dataset into. Defaults to ‘data’.
save_format (str) – File format (‘pkl’, ‘parquet’, or ‘csv’). Defaults to ‘pkl’.
save_by_day (bool) – Split transactions into one file per day. Defaults to True.

Raises:

RuntimeError – If called before generate().

Return type:

None

read_transactions(begin_date, end_date, save_format='pkl', data_dir='data')[source]

Load previously saved transaction data and combine it.

Parameters:

begin_date (str) – Start date for loading data (YYYY-MM-DD)
end_date (str) – End date for loading data (YYYY-MM-DD)
save_format (str) – Format to read (‘pkl’, ‘parquet’, or ‘csv’)
data_dir (str) – Base directory the dataset was saved into. Defaults to ‘data’.

Return type:

DataFrame

Returns:

DataFrame with combined transaction data.

get_location_features()[source]

Return type:: LocationFeatures

class synccfd.simulator.fraud.FraudSimulator(random_state=None)[source]

Bases: object

Simulates different credit card fraud scenarios.

Parameters:: random_state (int)

add_frauds(customer_profiles, terminal_profiles, transactions, loc_features)[source]

Add fraudulent transactions to the dataset.

Return type:

DataFrame

Parameters:

customer_profiles (DataFrame)
terminal_profiles (DataFrame)
transactions (DataFrame)
loc_features (LocationFeatures)

synccfd.simulator.location.features.random_point_around_a_center(center_lat, center_long, radius, brazil_polygon, max_attempts=10000)[source]

Generate a random point within a radius around a center point.

Parameters:

center_lat (float) – Latitude of the center point.
center_long (float) – Longitude of the center point.
radius (float) – Maximum distance in kilometers from center.
brazil_polygon – Shapely polygon to check containment.
max_attempts (int) – Maximum number of attempts before raising an error.

Return type:

dict[str, float]

Returns:

Dictionary with ‘lat’ and ‘long’ keys.

Raises:

RuntimeError – If no valid point is found within max_attempts.

synccfd.simulator.location.features.gen_random_points(num_points, radius, polygon, cities, random_state)[source]

Generate random points around cities weighted by population.

Return type:

dict[str, DataFrame]

Parameters:

num_points (int)
radius (float)
cities (DataFrame)
random_state (int)

synccfd.simulator.location.features.gen_available_terminals(loc, terminals, radius)[source]

Generate list of available terminals within radius.

Return type:

list[int]

Parameters:

loc (dict[str, float])
terminals (DataFrame)
radius (float)

class synccfd.simulator.location.features.LocationFeatures(city_radius=12, available_terminals_radius=10, random_state=None)[source]

Bases: object

Geographical features (customer and terminal locations) for the simulator.

Parameters:

city_radius (float)
available_terminals_radius (float)
random_state (int)

gen_billing_locations(n_customers, random_state=None)[source]

Generate billing locations for customers.

Return type:

None

Parameters:

n_customers (int)
random_state (int)

get_billing_location(customer_id)[source]

Get billing location for a customer.

Return type:: dict[str, float]
Parameters:: customer_id (int)

gen_terminal_locations(n_terminals, random_state=1)[source]

Generate terminal locations.

Return type:

None

Parameters:

n_terminals (int)
random_state (int)

get_terminal_location(terminal_id)[source]

Get terminal location.

Return type:: dict[str, float]
Parameters:: terminal_id (int)

gen_customer_available_terminals()[source]

Generate list of available terminals for each customer.

Return type:: None

get_customer_available_terminals(customer_id)[source]

Get available terminals for a customer.

Return type:: list[int]
Parameters:: customer_id (int)

gen_customer_terminal_association(customer_id, tx_type)[source]

Return the terminal of a transaction given the customer_id and tx_type.

Return type:

int

Parameters:

customer_id (int)
tx_type (str)

gen_tx_locations(customer_id, tx_type)[source]

Generate transaction locations.

Return type:

dict[str, Any]

Parameters:

customer_id (int)
tx_type (str)

gen_shipping_location(tx_billing_loc, tx_terminal_loc, tx_type)[source]

Generate shipping location for a transaction.

Return type:

dict[str, float]

Parameters:

tx_billing_loc (dict[str, float])
tx_terminal_loc (dict[str, float])
tx_type (str)

tamper_tx_locations(transactions, fraud_scenario)[source]

Modify transaction locations for fraud scenarios.

Return type:

DataFrame

Parameters:

transactions (DataFrame)
fraud_scenario (int)

Utilities

class synccfd.utils.data.DataManager(data_dir=None)[source]

Bases: object

Handles saving and loading of transaction data and related profiles.

Parameters:: data_dir (str | None)

save_data(transactions, customer_profiles=None, terminal_profiles=None, save_format='pkl', save_by_day=True, data_type=None)[source]

Save transaction data and optionally profile data.

Parameters:

transactions (DataFrame) – DataFrame with transaction data
customer_profiles (Optional[DataFrame]) – Optional DataFrame with customer profiles
terminal_profiles (Optional[DataFrame]) – Optional DataFrame with terminal profiles
save_format (str) – Format to save in (‘pkl’, ‘parquet’, or ‘csv’)
save_by_day (bool) – Whether to split transactions by day
data_type (str) – ‘raw’ or ‘transformed’ (mandatory)

Return type:

None

read_transactions(begin_date, end_date, format='pkl', data_type=None)[source]

Load transaction data from files and combine them.

Parameters:

begin_date (str) – Start date for loading data (YYYY-MM-DD)
end_date (str) – End date for loading data (YYYY-MM-DD)
format (str) – Format to read (‘pkl’, ‘parquet’, or ‘csv’)
data_type (str) – ‘raw’ or ‘transformed’ (mandatory)

Return type:

DataFrame

Returns:

DataFrame with combined transaction data

read_profiles(format='pkl')[source]

Read customer and terminal profiles if they exist.

Parameters:: format (str) – Format to read (‘pkl’, ‘parquet’, or ‘csv’)
Return type:: tuple[Optional[DataFrame], Optional[DataFrame]]
Returns:: Tuple of (customer_profiles, terminal_profiles), None if not found