datafake 0.1.0__tar.gz

datafake-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: datafake
+Version: 0.1.0
+Summary: Generate realistic synthetic datasets for testing, education and development
+Project-URL: Homepage, https://github.com/reginacabralc/datafake
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: faker>=18.0.0

datafake-0.1.0/datafake/__init__.py

@@ -0,0 +1,28 @@
+# cada import importa una función de su archivo correspondiente (con el . busca dentro del propio archivo)
+from .sales import generate_sales
+from .users import generate_users
+from .football import generate_football
+from .music import generate_music
+from .weather import generate_weather
+from .social import generate_social
+from .movies import generate_movies
+from .health import generate_health
+from .flights import generate_flights
+from .elections import generate_elections
+
+# define las funciones públicas (lo que se exporta cuando alguien hace from datafake import *)
+__all__ = [
+    "generate_sales",
+    "generate_users",
+    "generate_football",
+    "generate_music",
+    "generate_weather",
+    "generate_social",
+    "generate_movies",
+    "generate_health",
+    "generate_flights",
+    "generate_elections",
+]
+
+# guarda la versión de la librería (debe coincidir siempre con la versión en pyproject.toml)
+__version__ = "0.1.0"

datafake-0.1.0/datafake/elections.py

@@ -0,0 +1,59 @@
+import pandas as pd
+import numpy as np
+from faker import Faker
+from .utils import inject_missing
+
+# crea una instancia global de Faker 
+fake = Faker()
+
+# define la función con 3 parámetros (con parámetros default)
+def generate_elections(n=500, seed=42, missing_rate=0.0):
+    """
+    Genera un conjunto de datos sintético de elecciones ficticias.
+    Parámetros:
+    n : int
+        Número de filas a generar.
+    seed : int
+        Semilla aleatoria para reproducibilidad.
+    missing_rate : float
+        Proporción de valores faltantes a inyectar (0.0 a 1.0).
+    Devuelve: pd.DataFrame
+    """
+    # fija la semilla en numpy y en Faker por separado para garantizar reproducibilidad completa
+    np.random.seed(seed)
+    Faker.seed(seed)
+
+    # define los valores posibles para las columnas categóricas
+    candidates = ["Candidate A", "Candidate B", "Candidate C", "Candidate D"]
+    parties = ["Progressive Party", "Conservative Party", "Green Party", "Liberal Party"]
+    election_types = ["Presidential", "Legislative", "Municipal", "Regional"]
+    # genera nombres de regiones usando Faker y divide entre el número de candidatos porque cada región generará una fila por candidato
+    regions = [fake.state() for _ in range(n // len(candidates))]
+
+    rows = [] # inicializa una lista vacía que irá llenando fila por fila
+    for region in regions: # itera sobre cada región generada 
+        total_votes = np.random.randint(10000, 500000) # genera el total de votos de la región entre 10,000 y 500,000 (1 solo número por región)
+        raw = np.random.dirichlet(alpha=[3, 2, 1, 1]) * total_votes # genera 4 proporciones que usman exactamente 1 usando distribución Dirichlet, luego las múltiplica por el total de votos. alpha hace que el candidato A tenga ventaja sobre todos los demás (imitando realidad)
+        votes_per_candidate = raw.astype(int) # convierte los votos a enteros (pequeña pérdida de precisión)
+
+        for i, candidate in enumerate(candidates): # itera sobre cada candidato (el índice i se usa para asignar el partido correspondiente)
+            rows.append({  # agrega una fila al listado
+                "record_id": f"ELEC_{str(len(rows)).zfill(6)}", # genera ids únicos y secuenciales usando len(rows) como contador
+                "region": region, 
+                "election_type": np.random.choice(election_types), # escoge tipo de elección aleatoriamente con probabilidad uniforme
+                "year": np.random.choice([2020, 2021, 2022, 2023, 2024]), # escoge año de elección con probabilidad uniforme
+                "candidate": candidate,
+                "party": parties[i],
+                "votes": votes_per_candidate[i],
+                "total_votes_region": total_votes,
+                "turnout_pct": np.round(np.random.uniform(40, 85), 1), # genera participación electoral con distribución uniforme continua entre 40% y 85%
+                "incumbent": candidate == "Candidate A", # marca al candidato A como incumbente
+            })
+
+    df = pd.DataFrame(rows[:n])
+    
+    # calcula el porcentaje de votos de cada candidato en su región
+    df["vote_share_pct"] = np.round(df["votes"] / df["total_votes_region"] * 100, 2)
+
+    # pasa el DataFrame completo por inject_missing antes de devolverlo
+    return inject_missing(df, missing_rate=missing_rate, seed=seed)

datafake-0.1.0/datafake/flights.py

@@ -0,0 +1,60 @@
+import pandas as pd
+import numpy as np
+from faker import Faker
+from .utils import inject_missing
+
+fake = Faker()
+
+def generate_flights(n=500, seed=42, missing_rate=0.0):
+    # si al llamar la función no da parámetros, genera por default 500 filas con seed 42 y sin NaNs
+    """
+    Genera un conjunto de datos de vuelos.
+    Parámetros:
+    n : int
+        Número de filas a generar
+    semilla (seed): int
+        Semilla aleatoria para garantizar la reproducibilidad
+    tasa_faltante (missing_rate): float
+        Proporción de valores faltantes a inyectar (0.0 a 1.0)
+    Devuelve: pd.DataFrame
+    """
+    # inicializa la semilla aleatoria y en faker. Hay que fijar ambos para garantizar reproducibilidad
+    np.random.seed(seed)
+    Faker.seed(seed)
+    
+    # define listas con los valores posibles
+    airlines = ["Delta", "United Airlines", "American", "Lufthansa", "Emirates",
+                "Ryanair", "Air France", "British Airways", "Aeromexico", "LATAM"]
+    airports = ["JFK", "LAX", "LHR", "CDG", "DXB", "NRT", "AICM", "GRU", "SYD", "FRA"]
+    statuses = ["on_time", "delayed", "cancelled", "diverted"]
+    classes = ["economy", "business", "first"]
+
+    origins = np.random.choice(airports, size=n) # escoge aleatoriamente n aeropuertos de origen
+    
+    # Para cada origen o, filtra la lista de aeropuertos para excluir ese mismo aeropuerto (if a != o), 
+    # y luego escoge uno al azar. Esto garantiza que ningún vuelo tenga origen igual a destino. 
+    # El np.array() convierte la lista resultante en array de numpy.
+    destinations = np.array([np.random.choice([a for a in airports if a != o]) for o in origins])
+    
+    # Genera n estatus de vuelo con probabilidades no uniformes: 70% a tiempo, 22% retrasado, 5% cancelado y 3% desviado. 
+    # Estás probabilidades se escogen con la intensión de imitar la realidad del sector áereo en el mundo real
+    flight_statuses = np.random.choice(statuses, size=n, p=[0.70, 0.22, 0.05, 0.03])
+
+    df = pd.DataFrame({
+        "flight_id": [f"FLT_{str(i).zfill(6)}" for i in range(1, n + 1)], #Genera IDs únicos tipo FLT_000001. zfill(6) rellena con ceros a la izquierda hasta tener 6 dígitos
+        "date": [fake.date_between(start_date="-1y", end_date="today") for _ in range(n)], # genera n fechas aleatorias entre hace 1 año y hoy
+        "airline": np.random.choice(airlines, size=n), # escoge aleatoriamente n aerolíneas con probabilidad uniforme
+        "origin": origins, # asigna el array que calculamos antes
+        "destination": destinations, # asigna los array que calculamos antes
+        "class": np.random.choice(classes, size=n, p=[0.75, 0.20, 0.05]), # Escoge clase de un vuelo con probabilidades no uniformes: 75% economy, 20% business y 5% primera clase (imitando la realidad)
+        "duration_min": np.random.randint(60, 900, size=n), # Genera duración del vuelo en minutos con distribución uniforme entre 60 y 900 minutos. Este es el rango razonable para vyelos entre los aeropuertos de la lista
+        "distance_km": np.random.randint(200, 15000, size=n), # Genera distancia en kilómetros con distribución uniforme entre 200 km y 15,000 km. Es uniforme porque sin saber el par origen-destino exacto no podemos calcular la distancia real. Sin embargo, estos rangos cubren las distancias entre los aeropuertos de nuestra lista 
+        "price_usd": np.round(np.random.lognormal(mean=5.5, sigma=1.0, size=n), 2), # Genera precios con distribución lognormal (muchos vuelos baratos y pocos muy caros). Mean=5.5 en escala logarítmica equivale a un precio "típico" de 245 dólares
+        "status": flight_statuses, # asigna el array que calculamos antes
+        "delay_min": np.where(flight_statuses == "delayed", np.random.randint(15, 300, size=n), 0), # Si el estatus es "delayed" np.where asigna un número aleatorio entre 15 y 300 minutos, si no asigna 0
+        "passengers": np.random.randint(50, 400, size=n), # Genera número de pasajeros con distribución uniforme entre 50 y 400 (aviones pequeños o grandes, vacíos o totalmente llenos)
+        "satisfaction": np.round(np.random.uniform(1, 10, size=n), 1), # Genera una calificaci´øn de satisfacción entre 1,0 y 10.0 con distribución uniforme. Se usa uniforme porque en encuestas de satisfacción los valores extremos son muy comunes
+    })
+
+    # Antes de devolver el dataFrame, pasa por inject_missing. Si missing_rate=0.0 lo devuelve intacto, si no introduce NaNs en las columnas no protegidas
+    return inject_missing(df, missing_rate=missing_rate, seed=seed)

datafake-0.1.0/datafake/football.py

@@ -0,0 +1,74 @@
+import pandas as pd
+import numpy as np
+from faker import Faker
+from .utils import inject_missing
+
+# crea una instancia global de Faker 
+fake = Faker()
+
+# define la función con 3 parámetros (con parámetros default)
+def generate_football(n=500, seed=42, missing_rate=0.0):
+    """
+    Genera un conjunto de datos sintético de partidos de fútbol.
+    Parámetros:
+    n : int
+        Número de filas a generar.
+    seed : int
+        Semilla aleatoria para reproducibilidad.
+    missing_rate : float
+        Proporción de valores faltantes a inyectar (0.0 a 1.0).
+    Devuelve: pd.DataFrame
+    """
+    # fija la semilla en numpy y en Faker por separado para garantizar reproducibilidad completa
+    np.random.seed(seed)
+    Faker.seed(seed)
+
+    # define los valores posibles para las columnas categóricas
+    teams = [
+        "Real Madrid", "Barcelona", "Manchester City", "Liverpool",
+        "Bayern Munich", "PSG", "Juventus", "Chelsea", "Arsenal",
+        "Atletico Madrid", "Borussia Dortmund", "Inter Milan",
+        "AC Milan", "Ajax", "Porto"
+    ]
+    competitions = ["La Liga", "Premier League", "Bundesliga", "Serie A", "Champions League"]
+    stages = ["Group Stage", "Round of 16", "Quarter Final", "Semi Final", "Final", "Regular Season"]
+
+    # escofe n equipos locales aleatoriamente de la lista con probabilidad uniforme
+    home_teams = np.random.choice(teams, size=n)
+    # para cada equipo local h, filtra la lista para excluirlo y escoge un visitante al azar (garantiza que ningún equipo juegue contra sí mismo)
+    away_teams = np.array([np.random.choice([t for t in teams if t != h]) for h in home_teams])
+    # genera goles con distribución Poisson (el equipo local tiene lam=1.5 y el visitante lam=1.1 porque estadísticamente los equipos locales marcan más goles (fenómeno conocido como "ventaja de local"))
+    home_goals = np.random.poisson(lam=1.5, size=n)
+    away_goals = np.random.poisson(lam=1.1, size=n)
+
+    # función auxiliar que recibe los goles de ambos equipos y devuelve el resultado textual
+    def get_result(h, a):
+        if h > a:
+            return "home_win"
+        elif a > h:
+            return "away_win"
+        else:
+            return "draw"
+
+    df = pd.DataFrame({
+        "match_id": [f"MATCH_{str(i).zfill(5)}" for i in range(1, n + 1)], # genera ids únicos tipo MATCH_00001
+        "date": [fake.date_between(start_date="-3y", end_date="today") for _ in range(n)], # genera n fechas aleatorias en los últimos 3 años usando faker
+        "competition": np.random.choice(competitions, size=n, p=[0.25, 0.25, 0.20, 0.20, 0.10]), # escoge competición con probabilidades no uniformes (La Liga y Premier League son las más comunes y Champion League la menos porque tiene menos partidos que una liga completa)
+        "stage": np.random.choice(stages, size=n), # escoge etapa con probabilidad uniforme
+        "home_team": home_teams, # asigna el array generado antes 
+        "away_team": away_teams, # asigna el array generado antes 
+        "home_goals": home_goals, # asigna el array generado antes 
+        "away_goals": away_goals, # asigna el array generado antes 
+        "total_goals": home_goals + away_goals, # suma los goles de ambos equipos
+        "result": [get_result(h, a) for h, a in zip(home_goals, away_goals)], # aplica la función auxiliar a cada par de goles
+        "attendance": np.random.randint(10000, 90000, size=n), # genera asistencia con distribución uniforme discreta entre 10,000 y 90,000 (cubre desde estadios pequeños hasta los más grandes)
+        "home_shots": np.random.randint(5, 25, size=n), # genera tiros con distribución uniforme discreta (rango 5-24)
+        "away_shots": np.random.randint(3, 20, size=n), # genera tiros con distribución uniforme discreta (rango 3-19 por "ventaja de local")
+        "home_possession": np.round(np.random.uniform(35, 65, size=n), 1), # genera con posesión local con distribución uniforme continua entre 35% y 65% (se limira a ese intervalo porque en fútbol profesional es muy raro ver algo fuera de ese intervalo)
+    })
+
+    # calcula la posesión visitante como complemento de la local (ambas deben sumar 100%)
+    df["away_possession"] = np.round(100 - df["home_possession"], 1)
+
+    # pasa el DataFrame completo por inject_missing antes de devolverlo
+    return inject_missing(df, missing_rate=missing_rate, seed=seed)

datafake-0.1.0/datafake/health.py

@@ -0,0 +1,53 @@
+import pandas as pd
+import numpy as np
+from faker import Faker
+from .utils import inject_missing
+
+# crea una instancia global de Faker 
+fake = Faker()
+
+# define la función con 3 parámetros (con parámetros default)
+def generate_health(n=500, seed=42, missing_rate=0.0):
+    """
+    Genera un conjunto de datos sintético de salud/pacientes.
+    Parámetros:
+    n : int
+        Número de filas a generar.
+    seed : int
+        Semilla aleatoria para reproducibilidad.
+    missing_rate : float
+        Proporción de valores faltantes a inyectar (0.0 a 1.0).
+    Devuelve: pd.DataFrame
+    """
+    # fija la semilla en numpy y en Faker por separado para garantizar reproducibilidad completa
+    np.random.seed(seed)
+    Faker.seed(seed)
+
+    # define los valores posibles para las columnas categóricas
+    diagnoses = ["Hypertension", "Diabetes", "Anxiety", "Depression", "Obesity",
+                 "Asthma", "Arthritis", "Migraine", "Anemia", "None"]
+    blood_types = ["A+", "A-", "B+", "B-", "AB+", "AB-", "O+", "O-"]
+    specialties = ["General", "Cardiology", "Neurology", "Endocrinology", "Psychiatry", "Pediatrics"]
+
+    df = pd.DataFrame({
+        "patient_id": [f"PAT_{str(i).zfill(5)}" for i in range(1, n + 1)], # genera ids únicos tipo PAT_00001
+        "age": np.random.randint(1, 91, size=n), # genera edades entre 1 y 90 con distribución uniforme discreta
+        "gender": np.random.choice(["M", "F", "Other"], size=n, p=[0.48, 0.48, 0.04]), # escoge género con probabilidades iguales para M y F y con 4% para other
+        "blood_type": np.random.choice(blood_types, size=n), # escoge tipo sanguíneo con probabilidad uniforme
+        "weight_kg": np.round(np.random.normal(loc=70, scale=15, size=n).clip(30, 200), 1), # genera peso con distribución normal centrada en 70kg y variación de 15kg (.clip evita valores imposibles)
+        "height_cm": np.round(np.random.normal(loc=168, scale=12, size=n).clip(100, 220), 1), # genera altura con distribución normal centrada en 168cm (promedio global ente hombres y mujeres)
+        "diagnosis": np.random.choice(diagnoses, size=n, p=[0.15, 0.12, 0.10, 0.10, 0.10, 
+                                                              0.08, 0.08, 0.07, 0.05, 0.15]), # escoge diagnóstico con probabilidades no uniformes basada en prevalencia aproximada
+        "specialty": np.random.choice(specialties, size=n), # escoge especialidad con probabilidad uniforme
+        "num_consultations": np.random.poisson(lam=3, size=n), # genera número de consultas con distribución poisson (modela conteos de eventos discretos en el tiempo) con promedio de 3 consultas por paciente
+        "smoker": np.random.choice([True, False], size=n, p=[0.20, 0.80]), # genera con distribución Bernoulli, 20% fumadores (imitando tasas de tabaquismo en países desarrollados)
+        "chronic_condition": np.random.choice([True, False], size=n, p=[0.35, 0.65]), # genera con distribución Bernoulli, 35% condición crónica
+        "satisfaction_score": np.round(np.random.uniform(1, 10, size=n), 1), # genera calificación de satisfacción entre 1.0 y 10.0 con distribución unfirome continua (las encuestas de satisfacción tienden a evitar extremos)
+        "visit_date": [fake.date_between(start_date="-2y", end_date="today") for _ in range(n)], # genera fechas de visita en los últimos 2 años usando Faker
+    })
+
+    # Calcula el índice de masa corporal con la fórmula oficial
+    df["bmi"] = np.round(df["weight_kg"] / (df["height_cm"] / 100) ** 2, 1)
+
+    # pasa el DataFrame completo por inject_missing antes de devolverlo
+    return inject_missing(df, missing_rate=missing_rate, seed=seed)

datafake-0.1.0/datafake/movies.py

@@ -0,0 +1,47 @@
+import pandas as pd
+import numpy as np
+from faker import Faker
+from .utils import inject_missing
+
+# crea una instancia global de Faker 
+fake = Faker()
+
+# define la función con 3 parámetros (con parámetros default)
+def generate_movies(n=500, seed=42, missing_rate=0.0):
+    """
+    Genera un conjunto de datos sintético de películas/streaming.
+    Parámetros:
+    n : int
+        Número de filas a generar.
+    seed : int
+        Semilla aleatoria para reproducibilidad.
+    missing_rate : float
+        Proporción de valores faltantes a inyectar (0.0 a 1.0).
+    Devuelve: pd.DataFrame
+    """
+    # fija la semilla en numpy y en Faker por separado para garantizar reproducibilidad completa
+    np.random.seed(seed)
+    Faker.seed(seed)
+
+    # define los valores posibles para las columnas categóricas
+    genres = ["Action", "Comedy", "Drama", "Horror", "Sci-Fi", "Romance", "Documentary", "Animation"]
+    platforms = ["Netflix", "HBO Max", "Disney+", "Amazon Prime", "Apple TV+"]
+    ratings = ["G", "PG", "PG-13", "R", "NC-17"]
+    languages = ["English", "Spanish", "French", "Japanese", "Chinese", "Italian"]
+
+    df = pd.DataFrame({
+        "movie_id": [f"MOV_{str(i).zfill(5)}" for i in range(1, n + 1)], # genera ids únicos tipo MOV_00001
+        "title": [fake.catch_phrase() for _ in range(n)], # genera frases cortas que se usan como títulos con Faker 
+        "genre": np.random.choice(genres, size=n, p=[0.20, 0.15, 0.20, 0.10, 0.12, 0.10, 0.08, 0.05]), # escoge género con probabilidades no uniformes (acción y drama dominan y animación es el más raro porque hay menos películas animadas en streaming)
+        "platform": np.random.choice(platforms, size=n, p=[0.35, 0.20, 0.20, 0.15, 0.10]), # escoge plataforma con probabilidades no uniformes (netflix domina porque tiene el catálogo más grande y Apple TV+ es el más pequeño por ser la plataforma más nueva)
+        "release_year": np.random.randint(1970, 2025, size=n), # genera año de lanzamiento entre 1970 y 2024 con distribución uniforme discreta
+        "duration_min": np.random.randint(75, 211, size=n), # genera duración entre 75 minutos (película corta) y 210 minutos (película muy larga) con distribución uniforme discreta
+        "rating": np.random.choice(ratings, size=n, p=[0.05, 0.15, 0.40, 0.35, 0.05]), # escoge clasificación con probabilidades no uniformes (imitando la realidad)
+        "language": np.random.choice(languages, size=n, p=[0.50, 0.20, 0.10, 0.08, 0.07, 0.05]), # escoge idioma con probabilidades no uniformes (inglés es el más usando en el mercado de cine)
+        "imdb_score": np.round(np.random.normal(loc=6.5, scale=1.2, size=n).clip(1, 10), 1), # genera calificación con distribución normal centrada en 6.5 (usa normal porque pocas películas se clasifican en los extremos)
+        "box_office_usd": np.random.lognormal(mean=17, sigma=2, size=n).astype(int), # genera ganancia en taquilla con lognormal con media 17 (la mayoría gana poca y algunas ganan mucho)
+        "sequel": np.random.choice([True, False], size=n, p=[0.20, 0.80]), # genera con distribución Bernoulli (el 20% son secuelas, imitando proporciones reales de la industria)
+    })
+
+    # pasa el DataFrame completo por inject_missing antes de devolverlo
+    return inject_missing(df, missing_rate=missing_rate, seed=seed)

datafake-0.1.0/datafake/music.py

@@ -0,0 +1,49 @@
+import pandas as pd
+import numpy as np
+from faker import Faker
+from .utils import inject_missing
+
+# crea una instancia global de Faker 
+fake = Faker()
+
+# define la función con 3 parámetros (con parámetros default)
+def generate_music(n=500, seed=42, missing_rate=0.0):
+    """
+    Genera un conjunto de datos sintético de streaming de música.
+    Parámetros:
+    n : int
+        Número de filas a generar.
+    seed : int
+        Semilla aleatoria para reproducibilidad.
+    missing_rate : float
+        Proporción de valores faltantes a inyectar (0.0 a 1.0).
+    Devuelve: pd.DataFrame
+    """
+    # fija la semilla en numpy y en Faker por separado para garantizar reproducibilidad completa
+    np.random.seed(seed)
+    Faker.seed(seed)
+
+    # define los valores posibles para las columnas categóricas
+    genres = ["Pop", "Rock", "Hip-Hop", "Electronic", "Jazz", "Classical", "Reggaeton", "R&B"]
+    moods = ["Happy", "Sad", "Energetic", "Chill", "Romantic", "Angry"]
+    platforms = ["Spotify", "Apple Music", "YouTube Music", "Tencent Music", "Amazon Music"]
+
+    df = pd.DataFrame({
+        "track_id": [f"TRK_{str(i).zfill(6)}" for i in range(1, n + 1)], # genera ids únicos tipo TRK_000001 (no hay eventos repetidas en el dataset)
+        "title": [fake.catch_phrase() for _ in range(n)], # usa catch_phrase() de Faker para generar títulos (genera frases de 2-4 palabras que funcionan como títulos creativos)
+        "artist": [fake.name() for _ in range(n)], # usa fake.name() para generar nombres de artistas
+        "album": [fake.bs() for _ in range(n)], # usa bs() de Faker (genera frases abstractas que funcionan como nombres de albúmes)
+        "genre": np.random.choice(genres, size=n, p=[0.25, 0.15, 0.20, 0.10, 0.05, 0.05, 0.12, 0.08]), # escoge género con probabilidades no uniformes (basado en la cantidad de oyentes en plataformas de streaming)
+        "mood": np.random.choice(moods, size=n), # escoge estado de ánimo con probabilidad uniforme
+        "duration_seconds": np.random.randint(120, 360, size=n), # genera duración en segundos entre 120 y 359 (casi 6 min) con distribución uniforme
+        "release_year": np.random.randint(1980, 2025, size=n), # gener año de lanzamiento entre 1980 y 2024 con distribución uniforme
+        "streams": np.random.lognormal(mean=12, sigma=2, size=n).astype(int), # genera reproducciones con distribución lognormal (la mayoría de las canciones tienen pocas reproducciones y unas pocas tienen muchas)
+        "likes": np.random.lognormal(mean=8, sigma=2, size=n).astype(int), # genera likes con distribución lognormal
+        "platform": np.random.choice(platforms, size=n, p=[0.40, 0.25, 0.20, 0.08, 0.07]), # escoge plataforma con probabilidad no uniforme 
+        "explicit": np.random.choice([True, False], size=n, p=[0.30, 0.70]), # se genera con distribución Bernoulli 
+        "bpm": np.random.randint(60, 180, size=n), # genera bpm entre 60 y 179 con distribución uniforme discreta
+        "rating": np.round(np.random.uniform(1, 5, size=n), 1), # genera calificación entre 1.0 y 5.o con distribución uniforme continua
+    })
+
+    # pasa el DataFrame completo por inject_missing antes de devolverlo
+    return inject_missing(df, missing_rate=missing_rate, seed=seed)

datafake-0.1.0/datafake/sales.py

@@ -0,0 +1,61 @@
+import pandas as pd
+import numpy as np
+from faker import Faker
+from .utils import inject_missing
+
+# crea una instancia global de Faker 
+fake = Faker()
+
+# define la función con 5 parámetros (con parámetros default)
+def generate_sales(n=500, seed=42, start_date="2024-01-01", end_date="2024-12-31", missing_rate=0.0):
+    """
+    Genera un conjunto de datos de ventas sintético.
+
+    Parámetros:
+    n : int
+        Número de filas a generar.
+    seed : int
+        Semilla aleatoria para reproducibilidad.
+    start_date : str
+        Fecha de inicio para las transacciones (AAAA-MM-DD).
+    end_date : str
+        Fecha de fin para las transacciones (AAAA-MM-DD).
+    missing_rate : float
+        Proporción de valores faltantes a inyectar (0.0 a 1.0).
+    Devuelve: pd.DataFrame
+    """
+    # fija la semilla en numpy y en Faker por separado para garantizar reproducibilidad completa
+    np.random.seed(seed)
+    Faker.seed(seed)
+
+    # define los valores posibles para las columnas categóricas
+    categories = ["Electronics", "Clothing", "Food", "Home", "Sports", "Beauty"]
+    payment_methods = ["card", "transfer", "cash", "paypal"]
+    statuses = ["completed", "returned", "pending"]
+    # crea 200 IDs de clientes y 50 de productos
+    # se crean antes del df para que los mismos IDs se repiran en múltiples filas, simulando que un cliente compra varias veces
+    customer_ids = [f"CUST_{str(i).zfill(4)}" for i in range(1, 201)]
+    product_ids = [f"PROD_{str(i).zfill(4)}" for i in range(1, 51)]
+    # genera n fechas distribuidas uniformemente entre start_date y end_date
+    dates = pd.date_range(start=start_date, end=end_date, periods=n)
+
+    df = pd.DataFrame({
+        "sale_id": [f"SALE_{str(i).zfill(6)}" for i in range(1, n + 1)], # genera IDs tipo SALE_000001 desde 1 hasta n+1, con zfill(6) rellena con ceros a la izquierda hasta tener 6 digitos
+        "date": np.random.choice(dates, size=n), # escoge n fechas aleatoriamente del rango generado, se hace aleatorio para uqe las fechas no sean perfectamente secuenciales
+        "customer_id": np.random.choice(customer_ids, size=n), # escoge IDs aleatoriamente del catálogo (con repetidos)
+        "product_id": np.random.choice(product_ids, size=n), # escoge IDs aleatoriamente del catálogo (con repetidos)
+        "category": np.random.choice(categories, size=n, p=[0.30, 0.20, 0.20, 0.15, 0.10, 0.05]), # escoge categoría con probabilidad no uniforme, imitando patrones reales de comercio (ecommerce)
+        "quantity": np.random.randint(1, 10, size=n), # genera cantidades enteras entre 1 y 9 con distribución uniforme discreta
+        "unit_price": np.round(np.random.lognormal(mean=4.5, sigma=1.0, size=n), 2), # genera precios con distribución lognormal (muchos productos baratos y pocos muy caros) 
+        "payment_method": np.random.choice(payment_methods, size=n, p=[0.55, 0.25, 0.12, 0.08]), # escoge método con probabilidades no unfiromes (tarjeta domina y paypal es menos común)
+        "status": np.random.choice(statuses, size=n, p=[0.88, 0.07, 0.05]), # escoge estatus con probabilidades no uniformes (la mayoría se completan y pocas quedan pendientes)
+        "store": [fake.city() for _ in range(n)], # genera n nombres de ciudades usando Faker. El _ en el for loop indica que la variable iteradora no se usa, solo nos importa repetir la acción n veces
+    })
+    
+    # 
+    df["revenue"] = np.round(df["quantity"] * df["unit_price"], 2) # calcula el ingreso total como quantity*unit_price
+    # convierte la columna date a formato fecha sin hora
+    df["date"] = pd.to_datetime(df["date"]).dt.date
+
+    # pasa el DataFrame completo por inject_missing antes de devolverlo
+    return inject_missing(df, missing_rate=missing_rate, seed=seed)

datafake-0.1.0/datafake/social.py

@@ -0,0 +1,52 @@
+import pandas as pd
+import numpy as np
+from faker import Faker
+from .utils import inject_missing
+
+# crea una instancia global de Faker 
+fake = Faker()
+
+# define la función con 3 parámetros (con parámetros default)
+def generate_social(n=500, seed=42, missing_rate=0.0):
+    """
+    Genera un conjunto de datos sintético de publicaciones en redes sociales.
+    Parámetros:
+    n : int
+        Número de filas a generar.
+    seed : int
+        Semilla aleatoria para reproducibilidad.
+    missing_rate : float
+        Proporción de valores faltantes a inyectar (0.0 a 1.0).
+    Devuelve: pd.DataFrame
+    """
+    # fija la semilla en numpy y en Faker por separado para garantizar reproducibilidad completa
+    np.random.seed(seed)
+    Faker.seed(seed)
+
+    # define los valores posibles para las columnas categóricas
+    platforms = ["Instagram", "Twitter", "TikTok", "Facebook", "LinkedIn"]
+    content_types = ["image", "video", "text", "story", "reel"]
+    topics = ["Food", "Travel", "Tech", "Fashion", "Sports", "Music", "Politics", "Health"]
+
+    df = pd.DataFrame({
+        "post_id": [f"POST_{str(i).zfill(6)}" for i in range(1, n + 1)], # genera IDs únicos tipo POST_000001
+        "user_id": [f"USR_{str(np.random.randint(1, 201)).zfill(5)}" for _ in range(n)], # genera IDs de usuario entre 1 y 200 aleatoriamente (mismos usuarios aparecen muchas veces, un usuario con muchos posts)
+        "platform": np.random.choice(platforms, size=n, p=[0.30, 0.25, 0.20, 0.15, 0.10]), # escoge plataforma con probabilidades no uniformes (basado en que app tiene más usuarios activos en la realidad)
+        "content_type": np.random.choice(content_types, size=n, p=[0.30, 0.25, 0.20, 0.15, 0.10]), # escoge tipo de contenido con probabilidades no uniformes (imagen domina y reel es menos común (aunque está creciendo rápidamente))
+        "topic": np.random.choice(topics, size=n), # escoge tema con probabilidad uniforme
+        "date": [fake.date_between(start_date="-1y", end_date="today") for _ in range(n)], # genera fechas en el último año usando Faker
+        "likes": np.random.lognormal(mean=5, sigma=2, size=n).astype(int), # genera con distribución lognormal con media 5
+        "comments": np.random.lognormal(mean=3, sigma=1.5, size=n).astype(int), # genera con distribución lognormal con media 3 (pues normalmente hay más likes que comentarios)
+        "shares": np.random.lognormal(mean=2, sigma=1.5, size=n).astype(int), # genera con distribución lognormal con media 2 (pues normalmente hay más comentarios que shares)
+        "reach": np.random.lognormal(mean=7, sigma=2, size=n).astype(int), # genera alcance con distribución lognormal con media 7 (siempre mayor que likes porque el alcance incluye personas que vieron el post pero no interactuaron)
+        "followers_at_post": np.random.lognormal(mean=8, sigma=2, size=n).astype(int), # genera seguidores al momento del post con distribución lognormal con media 8 (muchas cuentas pequeñas y pocos influencers)
+        "is_viral": np.random.choice([True, False], size=n, p=[0.05, 0.95]), # genera con distribución Bernoulli (solo el 5% de posts se vuelven virales, imitando la realidad donde la viralidad es un evento raro) 
+    })
+    
+    # calcula el engagement rate usando la fórmula de marketing digital: suma de interacciones dividida entre alcance multiplicado por 100
+    df["engagement_rate"] = np.round(
+        (df["likes"] + df["comments"] + df["shares"]) / df["reach"] * 100, 2
+    )
+
+    # pasa el DataFrame completo por inject_missing antes de devolverlo
+    return inject_missing(df, missing_rate=missing_rate, seed=seed)

datafake-0.1.0/datafake/users.py

@@ -0,0 +1,51 @@
+import pandas as pd
+import numpy as np
+from faker import Faker
+from .utils import inject_missing
+
+# crea una instancia global de Faker 
+fake = Faker()
+
+# define la función con 3 parámetros (con parámetros default)
+# el default de n es 300 en lugar de 500 porque una base de clientes típicamente tiene menos registros que número de transacciones
+def generate_users(n=300, seed=42, missing_rate=0.0):
+    """
+    Genera un conjunto de datos de usuarios sintético.
+
+    Parámetros:
+    n : int
+        Número de filas a generar.
+    seed : int
+        Semilla aleatoria para reproducibilidad.
+    missing_rate : float
+        Proporción de valores faltantes a inyectar (0.0 a 1.0).
+    Devuelve: pd.DataFrame
+    """
+    # fija la semilla en numpy y en Faker por separado para garantizar reproducibilidad completa
+    np.random.seed(seed)
+    Faker.seed(seed)
+
+    # define los valores posibles para las columnas categóricas
+    plans = ["free", "basic", "pro", "enterprise"]
+    devices = ["mobile", "desktop", "tablet"]
+    statuses = ["active", "inactive", "churned"]
+
+    df = pd.DataFrame({
+        "user_id": [f"USR_{str(i).zfill(5)}" for i in range(1, n + 1)], # genera ids únicos tipo USR_00001
+        "name": [fake.name() for _ in range(n)], # usa faker para generar nombres realistas
+        "email": [fake.email() for _ in range(n)], # usa faker para generar emails realistas
+        "country": [fake.country() for _ in range(n)], # usa faker para generar países realistas
+        "age": np.random.randint(18, 71, size=n), # genera edades entre 18 y 70 con distribución uniforme discreta (asume usuarios adultos)
+        "plan": np.random.choice(plans, size=n, p=[0.55, 0.25, 0.15, 0.05]), # escoge plan con probabilidades no uniformes (la mayoría plan gratuito, muy pocos enterprise)
+        "device": np.random.choice(devices, size=n, p=[0.55, 0.35, 0.10]), # escoge dispositivo con probabilidades no unfiromes (la mayoría mobile y pocos tablet)
+        "sessions_per_month": np.random.poisson(lam=12, size=n), # genera número de sesiones mensaules con distribución poisson. Poisson porque modela conteos de eventos en el tiempo (promedio de 12 al mes)
+        "avg_session_minutes": np.round(np.random.lognormal(mean=2.5, sigma=0.8, size=n), 1), # genera duración promedio de sesión con distribución lognormal (la mayoría cortas pero algunas largas)
+        "status": np.random.choice(statuses, size=n, p=[0.70, 0.20, 0.10]), # escoge estatus con probabilidades no uniformes
+        "registration_date": [fake.date_between(start_date="-3y", end_date="today") for _ in range(n)], # genera fechas de registro en los últimos 3 años usando Faker
+    })
+
+    # crea una columna binaria que se deriva del status, donde status es "churned" pone 1, en los demás 0. Convierte la columna de True/False a entero 1/0
+    df["churned"] = (df["status"] == "churned").astype(int)
+    
+    # pasa el DataFrame completo por inject_missing antes de devolverlo
+    return inject_missing(df, missing_rate=missing_rate, seed=seed)

datafake-0.1.0/datafake/utils.py

@@ -0,0 +1,54 @@
+import numpy as np
+import pandas as pd
+
+# definimos la función que recibe 3 parámetros. 
+def inject_missing(df: pd.DataFrame, missing_rate: float = 0.0, seed: int = None):
+    """
+    Inyecta valores NaN aleatoriamente en un DataFrame.
+    Parámetros:
+    df : pd.DataFrame
+        El DataFrame al que se le inyectarán valores NaNs.
+    missing_rate : float
+        Proporción de valores a convertir en NaN (0.0 a 1.0).
+        Las columnas de ID y fechas están protegidas y nunca reciben NaNs.
+        Por default es 0.
+    seed : int
+        Semilla aleatoria para reproducibilidad.
+    Devuelve: pd.DataFrame
+    """
+    # si no se piden NaNs devuelve inmediatamente el DataFrame sin hacer cambios
+    if missing_rate == 0.0:
+        return df
+
+    # verifica que el valor esté entre 0 y 1, si no lanza una excepción
+    if not 0.0 < missing_rate < 1.0:
+        raise ValueError("missing_rate must be between 0.0 and 1.0 (exclusive)")
+
+    # fija la semilla si es que el usuario pasó una
+    if seed is not None:
+        np.random.seed(seed)
+
+    # construye una lista de columnas protegidas que NUNCA deben tener NaNs
+    # recorre todo el df y guarda solo las que terminen en id o que sean exactamente "date", "visit_date" o "registration_date"
+    protected = [col for col in df.columns if any([
+        col.endswith("_id"),
+        col.endswith("id"),
+        col == "date",
+        col == "visit_date",
+        col == "registration_date",
+    ])]
+
+    # hace una copia del df antes de modificarlo
+    df = df.copy()
+
+    # recorre cada columna. Si está en la lista de protegidas la salta y pasa a la siguiente
+    for col in df.columns:
+        if col in protected:
+            continue
+        # genera un array de True/False del mismo largo que el df
+        # np.random.random() produce números entre 0 y 1, los que caen por debajo de missing_rate se vuelven True
+        mask = np.random.random(size=len(df)) < missing_rate
+        # donde mask es True, reemplaza el valor de esa celda por NaN
+        df.loc[mask, col] = np.nan
+    # devuelve el df
+    return df

datafake-0.1.0/datafake/weather.py

@@ -0,0 +1,59 @@
+import pandas as pd
+import numpy as np
+from faker import Faker
+from .utils import inject_missing
+
+# crea una instancia global de Faker 
+fake = Faker()
+
+# define la función con 5 parámetros (con parámetros default)
+# tiene sentido controlar el rango de fechas porque es clima
+def generate_weather(n=500, seed=42, start_date="2024-01-01", end_date="2024-12-31", missing_rate=0.0):
+    """
+    Genera un conjunto de datos de clima sintético.
+
+    Parámetros:
+    n : int
+        Número de filas a generar.
+    seed : int
+        Semilla aleatoria para reproducibilidad.
+    start_date : str
+        Fecha de inicio (AAAA-MM-DD).
+    end_date : str
+        Fecha de fin (AAAA-MM-DD).
+    missing_rate : float
+        Proporción de valores faltantes a inyectar (0.0 a 1.0).
+    Devuelve: pd.DataFrame
+    """
+    # fija la semilla en numpy y en Faker por separado para garantizar reproducibilidad completa
+    np.random.seed(seed)
+    Faker.seed(seed)
+
+    # define los valores posibles para las columnas categóricas
+    cities = [
+        "Mexico City", "New York", "London", "Tokyo", "Paris",
+        "Sydney", "Toronto", "Berlin", "Dubai", "São Paulo"
+    ]
+    conditions = ["Sunny", "Cloudy", "Rainy", "Stormy", "Snowy", "Windy", "Foggy"] # cubren lo que cualquier ciudad de la lista podría experimentar
+
+    # genera n fechas distribuidas uniformemente entre start_date y end_date
+    dates = pd.date_range(start=start_date, end=end_date, periods=n)
+
+    df = pd.DataFrame({
+        "record_id": [f"WTH_{str(i).zfill(6)}" for i in range(1, n + 1)], # genera IDs únicos tipo WTH_000001
+        "date": np.random.choice(dates, size=n), # escoge n fechas aleatoriamente del rango generado para que no sean perfectamente secuenciales
+        "city": np.random.choice(cities, size=n), # escoge ciudad con probabilidad uniforme
+        "temperature_c": np.round(np.random.normal(loc=18, scale=12, size=n), 1), # genera temperatura con distribución normal, con media 18C y variación 12C amplia que cubre ciduades frías (como Toronto) hasta calurosas (como Dubai)
+        "humidity_pct": np.round(np.random.uniform(20, 100, size=n), 1), # genera humedad con distribución uniforme continua entre 20% y 100%
+        "wind_speed_kmh": np.round(np.random.lognormal(mean=2.5, sigma=0.8, size=n), 1), # genera velocidad del viento con distribución lognormal (mucho viento suave, a veces viento fuerte)
+        "precipitation_mm": np.round(np.random.exponential(scale=5, size=n), 1), # genera precipitación con distribución exponencial (la mayoría de días llueve poco o nada, y ocasionalmente llueve mucho. Sigue comportamiento real de la lluvia)
+        "condition": np.random.choice(conditions, size=n, p=[0.30, 0.25, 0.20, 0.08, 0.07, 0.06, 0.04]), # escoge condición con probabilidades no uniformes
+        "uv_index": np.random.randint(0, 11, size=n), # genera índice UV entre 0 y 10 con distribución uniforme discreta (no incluimos 11 en el índice porque es un extremo poco común globalmente)
+        "visibility_km": np.round(np.random.uniform(1, 30, size=n), 1), # genera visibilidad entre 1km (día nublado) y 30km (día despejado) con distribución uniforme continua
+    })
+
+    # convierte la columna date a fecha sin componente de hora
+    df["date"] = pd.to_datetime(df["date"]).dt.date
+
+    # pasa el DataFrame completo por inject_missing antes de devolverlo
+    return inject_missing(df, missing_rate=missing_rate, seed=seed)

datafake-0.1.0/datafake.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: datafake
+Version: 0.1.0
+Summary: Generate realistic synthetic datasets for testing, education and development
+Project-URL: Homepage, https://github.com/reginacabralc/datafake
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: faker>=18.0.0

datafake-0.1.0/datafake.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+pyproject.toml
+datafake/__init__.py
+datafake/elections.py
+datafake/flights.py
+datafake/football.py
+datafake/health.py
+datafake/movies.py
+datafake/music.py
+datafake/sales.py
+datafake/social.py
+datafake/users.py
+datafake/utils.py
+datafake/weather.py
+datafake.egg-info/PKG-INFO
+datafake.egg-info/SOURCES.txt
+datafake.egg-info/dependency_links.txt
+datafake.egg-info/requires.txt
+datafake.egg-info/top_level.txt
+tests/test_generators.py

datafake-0.1.0/datafake.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

datafake-0.1.0/datafake.egg-info/requires.txt

@@ -0,0 +1,3 @@
+pandas>=1.3.0
+numpy>=1.21.0
+faker>=18.0.0

datafake-0.1.0/datafake.egg-info/top_level.txt

@@ -0,0 +1 @@
+datafake

datafake-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "datafake"
+version = "0.1.0"
+description = "Generate realistic synthetic datasets for testing, education and development"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "pandas>=1.3.0",
+    "numpy>=1.21.0",
+    "faker>=18.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/reginacabralc/datafake"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["datafake*"]

datafake-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+