How w-decker/wiscs works
Main Components
• Parameter Management: The process starts with setting up experimental parameters. These parameters (e.g., perceptual, conceptual, task-related, standard deviations, correlations, and counts) are defined and stored using the “params” logic in wiscs/params.py. The parameters are set via the set_params() function available in the package’s API.
• Simulation Engine: The core simulation functionality is implemented in wiscs/simulate.py through the DataGenerator class. This component uses the parameters provided (either as defaults or user-specified) to:
• Construct a baseline data matrix (computing expected reaction times).
• Introduce random effects for subjects, questions, items, etc.
• Integrate noise using methods like Cholesky decomposition (as indicated by the README) to preserve the correlation structure among random effects.
• Plotting Component: Data visualization is handled in wiscs/plotting.py. This module provides various plotting utilities (bar graphs, histograms, scatter plots, heatmaps, etc.) which operate on the DataGenerator’s output.
• Utility and Configuration Functions: Additional support functions (in utils.py), configuration settings (in config.py), and possibly formula calculations (in formula.py) are parts of the support structure enabling the simulation process.
Relationships and Interactions Between Components
• The Parameter Manager (using functions in wiscs/params.py) initializes and validates the experimental parameters.
• Once parameters are set, the Simulation Engine (DataGenerator in wiscs/simulate.py) retrieves these parameters internally (or can override them via its fit_transform() method) to generate the simulated data.
• The generated data is exposed through attributes (e.g., DG.data) and is convertible to other formats (using DG.to_pandas() for pandas DataFrame conversion).
• The Plotting Module then takes in a DataGenerator instance to produce various data visualizations, showcasing the simulated reaction time data.
• The internal logic of the simulation might rely on other internal modules like utils.py and formula.py, which support calculations and configurations for generating realistic experimental variability.
Important Architectural Patterns
• Modular Design: Each functional area (parameter handling, simulation, plotting) is isolated in its own module, promoting clarity and maintainability.
• Separation of Concerns: The project distinctly separates parameter configuration from data generation and plotting, which simplifies testing and potential future extensions.
• Dependency Injection: The simulation module can either use preset parameters or accept new ones on-the-fly, allowing for flexible component interaction.
• Functional Pipeline: The sequential flow from parameter setup → data generation → data visualization illustrates a well-defined pipeline.
Relevant Technologies and Libraries
• Python as the core language.
• Standard libraries for numerical computations and possibly numpy (for operations such as generating random variates and performing Cholesky decomposition).
• Pandas for data manipulation (as seen in the conversion utility).
• Matplotlib or similar libraries are likely used in the Plotting module, although not explicitly mentioned in the README.