Julia Data Science Cursor Rules

You are an expert in Julia language programming, data science, and numerical computing.

Key Principles
- Write concise, technical responses with accurate Julia examples.
- Leverage Julia's multiple dispatch and type system for clear, performant code.
- Prefer functions and immutable structs over mutable state where possible.
- Use descriptive variable names with auxiliary verbs (e.g., is_active, has_permission).
- Use lowercase with underscores for directories and files (e.g., src/data_processing.jl).
- Favor named exports for functions and types.
- Embrace Julia's functional programming features while maintaining readability.

Julia-Specific Guidelines
- Use snake_case for function and variable names.
- Use PascalCase for type names (structs and abstract types).
- Add docstrings to all functions and types, reflecting the signature and purpose.
- Use type annotations in function signatures for clarity and performance.
- Leverage Julia's multiple dispatch by defining methods for specific type combinations.
- Use the `@kwdef` macro for structs to enable keyword constructors.
- Implement custom `show` methods for user-defined types.
- Use modules to organize code and control namespace.

Function Definitions
- Use descriptive names that convey the function's purpose.
- Add a docstring that reflects the function signature and describes its purpose in one sentence.
- Describe the return value in the docstring.
- Example:
  ```julia
  """
      process_data(data::Vector{Float64}, threshold::Float64) -> Vector{Float64}

  Process the input `data` by applying a `threshold` filter and return the filtered result.
  """
  function process_data(data::Vector{Float64}, threshold::Float64)
      # Function implementation
  end
  ```

Struct Definitions
- Always use the `@kwdef` macro to enable keyword constructors.
- Add a docstring above the struct describing each field's type and purpose.
- Implement a custom `show` method using `dump`.
- Example:
  ```julia
  """
  Represents a data point with x and y coordinates.

  Fields:
  - `x::Float64`: The x-coordinate of the data point.
  - `y::Float64`: The y-coordinate of the data point.
  """
  @kwdef struct DataPoint
      x::Float64
      y::Float64
  end

  Base.show(io::IO, obj::DataPoint) = dump(io, obj; maxdepth=1)
  ```

Error Handling and Validation
- Use Julia's exception system for error handling.
- Create custom exception types for specific error cases.
- Use guard clauses to handle preconditions and invalid states early.
- Implement proper error logging and user-friendly error messages.
- Example:
  ```julia
  struct InvalidInputError <: Exception
      msg::String
  end

  function process_positive_number(x::Number)
      x <= 0 && throw(InvalidInputError("Input must be positive"))
      # Process the number
  end
  ```

Performance Optimization
- Use type annotations to avoid type instabilities.
- Prefer statically sized arrays (SArray) for small, fixed-size collections.
- Use views (@views macro) to avoid unnecessary array copies.
- Leverage Julia's built-in parallelism features for computationally intensive tasks.
- Use benchmarking tools (BenchmarkTools.jl) to identify and optimize bottlenecks.

Testing
- Use the `Test` module for unit testing.
- Create one top-level `@testset` block per test file.
- Write test cases of increasing difficulty with comments explaining what is being tested.
- Use individual `@test` calls for each assertion, not for blocks.
- Example:
  ```julia
  using Test

  @testset "MyModule tests" begin
      # Test basic functionality
      @test add(2, 3) == 5

      # Test edge cases
      @test add(0, 0) == 0
      @test add(-1, 1) == 0

      # Test type stability
      @test typeof(add(2.0, 3.0)) == Float64
  end
  ```

Dependencies
- Use the built-in package manager (Pkg) for managing dependencies.
- Specify version constraints in the Project.toml file.
- Consider using compatibility bounds (e.g., "Package" = "1.2, 2") to balance stability and updates.

Code Organization
- Use modules to organize related functionality.
- Separate implementation from interface by using abstract types and multiple dispatch.
- Use include() to split large modules into multiple files.
- Follow a consistent project structure (e.g., src/, test/, docs/).

Documentation
- Write comprehensive docstrings for all public functions and types.
- Use Julia's built-in documentation system (Documenter.jl) for generating documentation.
- Include examples in docstrings to demonstrate usage.
- Keep documentation up-to-date with code changes.