From 4aeef2d533a06a92c6c92acc99580362575fff26 Mon Sep 17 00:00:00 2001 From: Ana Ruelas Date: Mon, 5 Jun 2017 16:01:33 -0400 Subject: [PATCH] DOC: Change docstrings to make documentation easier to read --- zipline/pipeline/engine.py | 65 ++++++++++++++++++------------ zipline/pipeline/factors/factor.py | 47 +++++++++++---------- 2 files changed, 65 insertions(+), 47 deletions(-) diff --git a/zipline/pipeline/engine.py b/zipline/pipeline/engine.py index 00906f90..335854c8 100644 --- a/zipline/pipeline/engine.py +++ b/zipline/pipeline/engine.py @@ -37,7 +37,8 @@ class PipelineEngine(with_metaclass(ABCMeta)): @abstractmethod def run_pipeline(self, pipeline, start_date, end_date): """ - Compute values for `pipeline` between `start_date` and `end_date`. + Compute values for ``pipeline`` between ``start_date`` and + ``end_date``. Returns a DataFrame with a MultiIndex of (date, asset) pairs. @@ -55,14 +56,14 @@ class PipelineEngine(with_metaclass(ABCMeta)): result : pd.DataFrame A frame of computed results. - The columns `result` correspond to the entries of + The ``result`` columns correspond to the entries of `pipeline.columns`, which should be a dictionary mapping strings to - instances of `zipline.pipeline.term.Term`. + instances of :class:`zipline.pipeline.term.Term`. - For each date between `start_date` and `end_date`, `result` will - contain a row for each asset that passed `pipeline.screen`. A - screen of None indicates that a row should be returned for each - asset that existed each day. + For each date between ``start_date`` and ``end_date``, ``result`` + will contain a row for each asset that passed `pipeline.screen`. + A screen of ``None`` indicates that a row should be returned for + each asset that existed each day. """ raise NotImplementedError("run_pipeline") @@ -90,18 +91,18 @@ class PipelineEngine(with_metaclass(ABCMeta)): result : pd.DataFrame A frame of computed results. - The columns `result` correspond to the entries of + The ``result`` columns correspond to the entries of `pipeline.columns`, which should be a dictionary mapping strings to - instances of `zipline.pipeline.term.Term`. + instances of :class:`zipline.pipeline.term.Term`. - For each date between `start_date` and `end_date`, `result` will - contain a row for each asset that passed `pipeline.screen`. A - screen of None indicates that a row should be returned for each - asset that existed each day. + For each date between ``start_date`` and ``end_date``, ``result`` + will contain a row for each asset that passed `pipeline.screen`. + A screen of ``None`` indicates that a row should be returned for + each asset that existed each day. See Also -------- - :meth:`PipelineEngine.run_pipeline` + :meth:`zipline.pipeline.engine.PipelineEngine.run_pipeline` """ raise NotImplementedError("run_chunked_pipeline") @@ -217,15 +218,6 @@ class SimplePipelineEngine(PipelineEngine): """ Compute a pipeline. - Parameters - ---------- - pipeline : zipline.pipeline.Pipeline - The pipeline to run. - start_date : pd.Timestamp - Start date of the computed matrix. - end_date : pd.Timestamp - End date of the computed matrix. - The algorithm implemented here can be broken down into the following stages: @@ -256,10 +248,33 @@ class SimplePipelineEngine(PipelineEngine): Step 2 is performed in ``SimplePipelineEngine.compute_chunk``. Steps 3, 4, and 5 are performed in ``SimplePiplineEngine._to_narrow``. + Parameters + ---------- + pipeline : zipline.pipeline.Pipeline + The pipeline to run. + start_date : pd.Timestamp + Start date of the computed matrix. + end_date : pd.Timestamp + End date of the computed matrix. + + Returns + ------- + result : pd.DataFrame + A frame of computed results. + + The ``result`` columns correspond to the entries of + `pipeline.columns`, which should be a dictionary mapping strings to + instances of :class:`zipline.pipeline.term.Term`. + + For each date between ``start_date`` and ``end_date``, ``result`` + will contain a row for each asset that passed `pipeline.screen`. + A screen of ``None`` indicates that a row should be returned for + each asset that existed each day. + See Also -------- - :meth:`PipelineEngine.run_pipeline` - :meth:`PipelineEngine.run_chunked_pipeline` + :meth:`zipline.pipeline.engine.PipelineEngine.run_pipeline` + :meth:`zipline.pipeline.engine.PipelineEngine.run_chunked_pipeline` """ if end_date < start_date: raise ValueError( diff --git a/zipline/pipeline/factors/factor.py b/zipline/pipeline/factors/factor.py index 0588ac58..54231e6f 100644 --- a/zipline/pipeline/factors/factor.py +++ b/zipline/pipeline/factors/factor.py @@ -881,34 +881,37 @@ class Factor(RestrictedDTypeMixin, ComputableTerm): winsorized : zipline.pipeline.Factor A Factor producing a winsorized version of self. - Example - ------- + Examples + -------- + .. code-block:: python - price = USEquityPricing.close.latest - columns={ - 'PRICE': price, - 'WINSOR_1: price.winsorize( - min_percentile=0.25, max_percentile=0.75 - ), - 'WINSOR_2': price.winsorize( - min_percentile=0.50, max_percentile=1.0 - ), - 'WINSOR_3': price.winsorize( - min_percentile=0.0, max_percentile=0.5 - ), + price = USEquityPricing.close.latest + columns={ + 'PRICE': price, + 'WINSOR_1: price.winsorize( + min_percentile=0.25, max_percentile=0.75 + ), + 'WINSOR_2': price.winsorize( + min_percentile=0.50, max_percentile=1.0 + ), + 'WINSOR_3': price.winsorize( + min_percentile=0.0, max_percentile=0.5 + ), - } + } Given a pipeline with columns, defined above, the result for a given day could look like: - 'PRICE' 'WINSOR_1' 'WINSOR_2' 'WINSOR_3' - Asset_1 1 2 4 3 - Asset_2 2 2 4 3 - Asset_3 3 3 4 3 - Asset_4 4 4 4 4 - Asset_5 5 5 5 4 - Asset_6 6 5 5 4 + :: + + 'PRICE' 'WINSOR_1' 'WINSOR_2' 'WINSOR_3' + Asset_1 1 2 4 3 + Asset_2 2 2 4 3 + Asset_3 3 3 4 3 + Asset_4 4 4 4 4 + Asset_5 5 5 5 4 + Asset_6 6 5 5 4 See Also --------