Critical Gaps in Key Class Implementations (e.g., Order Generation, Trading Parameters)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 48.7k
- Forks
- 7.7k
- PR merge metrics
- No merged PRs in 30d
Description
📖 Documentation
Problem Summary
The current documentation（ version of official documentation（v0.8.6.99）the actual qlib version（v0.9.7）） lacks crucial details for core classes like WeightStrategyBase, forcing users to read the source code to understand fundamental logic. Key parameters, their expected types, and behavioral impacts are either missing or ambiguous, leading to implementation errors and unexpected results.
Critical Gaps & Suggested Improvements
| Gap Category | Specific Issue & Impact | Suggested Improvement |
|---|---|---|
| Order Generation Logic | The default order generator for WeightStrategyBaseis OrderGenWOInteract. Its alternative, OrderGenWInteract, automatically normalizes weights based on tradable stocks, which is vital for full capital utilization but is not mentioned in the docs. Users might unknowingly use a non-capital-efficient method. |
Explicitly document the order generators associated with base classes and explain the core difference: whether weight normalization considers dynamic tradability (e.g., suspension, liquidity). |
| Parameter Types & Logic | The limit_thresholdparameter for handling price limits is ambiguous. The docs don't clarify that passing a float (e.g., 0.1) sets a static threshold, while a tuple uses an expression. The internal conversion of the expression's result to a bool for decision-making is undocumented and unintuitive. |
Clearly document parameter types (float vs. tuple/expression) with examples. Explain the internal logic for expression evaluation and how it triggers the limit logic. |
| Mandatory Fields | The necessity of the factorfield for achieving round-lot (integer) trading is not stated. Without it, orders might be generated in fractional shares, causing execution failures in simulations that require integer units. |
Add a note in the strategy or executor section stating that the factorfield (often representing a lot size multiplier) is required for integer-share order generation. |
Proposed Solution
Enhance the API reference for critical classes (WeightStrategyBase, OrderGenWInteract, etc.) with:
-
Detailed behavioral descriptions of key methods and their dependencies.
-
Clear parameter specifications, including expected data types and practical effects.
-
Concrete code snippets showing proper usage, especially for complex parameters like
limit_threshold.
This will significantly reduce the learning curve and prevent costly errors during strategy development.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the API reference entries for WeightStrategyBase, OrderGenWOInteract, and OrderGenWInteract, then review the strategy or executor sections covering limit_threshold and factor. Done means the reference explains the named classes, parameter types and effects, order-generation differences, integer-share behavior, and includes practical examples.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100