[GSoC-PortA] v1->v2 migration guide

[Ross Bennett]

See comments inline below


On Fri, Aug 16, 2013 at 9:36 AM, Brian G. Peterson <brian at braverock.com>wrote:

> 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.

I added to the optimize.portfolio documentation to explain the check for a
v1 constraint object.


>
>      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

Thanks

>
>
>
>  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.


I'm not entirely clear on this step. Take for example the add.objective
functions. We have add.objective_v1.Rd, add.objective_v2.Rd, and
add.objective.Rd files.

add.objective_v2 has an @rdname and @alias tag

add.objective is just the alias for add.objective_v2 and only has an
@export tag.

Are you saying the @param and other tags should go in front of the alias
function?

Should we keep _v1 documentation and export those functions for backwards
compatibility.

Can I just delete the _v2.Rd files in the man directory so we only have the
_v1.Rd files and the unversioned Rd files?

>
>
>      - 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
>
> _______________________________________________
> GSoC-PortA mailing list
> GSoC-PortA at lists.r-forge.r-project.org
> http://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/gsoc-porta
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.r-forge.r-project.org/pipermail/gsoc-porta/attachments/20130817/504d4195/attachment.html>