[GSoC-PortA] v1->v2 migration guide

[Brian G. Peterson]

Comments in-line.

On 08/16/2013 10:52 AM, Ross Bennett wrote:
<...>
>     What I'd like your thoughts on is developing an example of
>     converting a v1 constraints specification of any reasonable
>     complexity to a v2 portfolio specification.  I know you have some
>     helper functions for doing that, but the documentation is still
>     rather sparse.
>
> Are you looking for an example of how the user would go about doing this
> manually or how this is done behind the scenes with the helper
> functions? Or both?

I think it's reasonable to say in the documentation (the roxygen 
comments) that attempts will be made to detect and automatically convert 
v1 style objects. The mechanics of the automatic conversion aren't 
important to the user.

>     My thoughts run along these lines:
>     - generate a basic PortfolioAnalytics-package.Rd file either
>     manually or via roxygen comments that will describe the structure of
>     the portfolio specification, constraints, and objectives, with links
>     to the relevant functions.  maybe condense soeme generic text from
>     the optimization overview vignette
>
> I have been progressively adding to the portfolio_vignette file in the
> sandbox folder. I am thinking this could serve as the primary vignette
> because I have examples for creating the portfolio object, constraints,
> and objectives. I still have work to do to improve the objectives
> section. I can add a section that discusses the v1 to v2 migration.

I like your idea of using the new portfolio_vignette as the primary. 
The CVaR vignette is still valuable, but it should be secondary to the 
one you've been working on.

I've moved that out of sandbox to a vignettes/ dir in the package. 
Should be the most recent commit r2798


> I also think it would be helpful to have something similar to the
> PerformanceAnalytics.pdf reference manual. Is the reference manual
> automaticaly generated by .Rd files with roxygen. It would be good to
> have both the reference manual and a vignette with complete examples.


I've attached the reference manual built from this morning's code.

As you can see, it jumps right in to function documentation.  Addition 
of a PortfolioAnalytics-package.Rd file would be placed at the beginning 
of the manual, which would help anyone reading it get started.

I think we'll also want to consider collapsing some of the v1/v2 
functions into the documentation for the main functions e.g. contraint, 
objective, etc.  This can be done with the @rdname tag as a single line 
comment before the v1/v2 functions, and then we can put the text and all 
the @param and other tags in front of the main wrapper function.

>     - put more detail in the documentation for those functions.  most of
>     them are one-liners beyond the required @param info
>
> I'll beef up the documentation for those functions.

Thanks.

>     - perhaps take a look at the 2012 seminar script, and rework one or
>     more of those portfolios for discussion on this list, with notes
>     that we can add back into the documentation somewhere.
>
> Sounds good, I can rework several of the examples.

Excellent.

Regards,


   - Brian
-------------- next part --------------
A non-text attachment was scrubbed...
Name: PortfolioAnalytics.pdf
Type: application/pdf
Size: 250033 bytes
Desc: not available
URL: <http://lists.r-forge.r-project.org/pipermail/gsoc-porta/attachments/20130816/cec23b61/attachment-0001.pdf>